finitemonkey 0.1.0-next.1 → 0.1.0-next.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.es.md +123 -57
- package/README.md +122 -56
- package/README.pt-BR.md +123 -57
- package/dist/finitemonkey.mjs +2960 -86
- package/package.json +21 -7
package/README.es.md
CHANGED
|
@@ -1,104 +1,170 @@
|
|
|
1
1
|
# Finite Monkey
|
|
2
2
|
|
|
3
3
|
<p align="center">
|
|
4
|
-
<img src="assets/finitemonkey.gif" width="720" alt="Animación: un mono con sudadera aporrea el teclado de
|
|
4
|
+
<img src="assets/finitemonkey.gif" width="720" alt="Animación: un mono con sudadera amarilla aporrea el teclado de un portátil mientras una terminal ejecuta el control. Las comprobaciones que fallan se ponen en verde y se bloquean una a una hasta que aparece actually done, y el mono lo celebra con un plátano.">
|
|
5
|
+
<br>
|
|
6
|
+
<sub>Ilustración del flujo previsto, no es una grabación. En la v0.1 la reemplaza una captura real.</sub>
|
|
5
7
|
</p>
|
|
6
8
|
|
|
7
|
-
**No hacen falta infinitos monos.
|
|
9
|
+
**No hacen falta infinitos monos. Con uno basta: tú.**
|
|
8
10
|
|
|
9
11
|
[English](README.md) | [Português (Brasil)](README.pt-BR.md) | Español
|
|
10
12
|
|
|
11
|
-
> **
|
|
13
|
+
> **Prelanzamiento.** Todavía no se puede instalar. El nombre `finitemonkey` en npm está reservado (la 0.0.0 es solo un marcador) y el código se está construyendo en abierto. Todo lo que sigue es el plan, no lo que pasa hoy. Dale una estrella o sigue el repositorio si quieres enterarte cuando salga la v0.1.
|
|
12
14
|
|
|
13
|
-
|
|
15
|
+
Sé cómo es. Con la llegada de la IA, muchas cosas cambiaron.
|
|
14
16
|
|
|
15
|
-
|
|
17
|
+
Unos se dan cabezazos contra el teclado esperando que Claude escupa por arte de magia el próximo SaaS millonario. Otros ya se cansaron de escribir código. Y hay quien tiene que entregar en días lo que antes exigía equipos enteros trabajando durante meses.
|
|
16
18
|
|
|
17
|
-
|
|
19
|
+
El resultado casi siempre es el mismo: te conviertes en un mono frente a la computadora, sepultado bajo tanto por hacer que ya no sabes por dónde empezar, y mucho menos cómo terminar.
|
|
18
20
|
|
|
19
|
-
|
|
21
|
+
Finite Monkey nació para ser la puerta entre ese mono y `main`.
|
|
20
22
|
|
|
21
|
-
|
|
23
|
+
Escribe como quieras. Trabaja con la IA que prefieras. Produce código a la velocidad que puedas.
|
|
22
24
|
|
|
23
|
-
|
|
25
|
+
Finite Monkey se ocupa primero de lo que no puede quedar a base de confianza: las verificaciones.
|
|
24
26
|
|
|
25
|
-
|
|
27
|
+
Cada verificación aprobada queda registrada. Cada fallo sigue a la vista hasta que se resuelve. Y nada se considera listo sin pruebas de que realmente funciona.
|
|
26
28
|
|
|
27
|
-
|
|
28
|
-
- Las pruebas pasan porque se debilitaron o se saltaron.
|
|
29
|
-
- Las reglas escritas en `CLAUDE.md` o `AGENTS.md` se olvidan, sobre todo después de la compactación del contexto, porque la prosa es contexto, no imposición.
|
|
30
|
-
- Se pierde trabajo con un `git reset --hard`, un push forzado o un worktree borrado.
|
|
31
|
-
- Un secreto termina en un commit, un log o un pull request.
|
|
29
|
+
No importa cuánto código se generó, cuántos agentes trabajaron ni qué tan convincente parece la respuesta de la IA. Si no pasó las verificaciones, no está listo.
|
|
32
30
|
|
|
33
|
-
|
|
31
|
+
Y la puerta es solo el comienzo: Finite Monkey también se da cuenta cuando estás dando vueltas, muestra lo que falta en un proyecto que te queda grande, sostiene las riendas de varios agentes a la vez y lo lleva todo a producción sin romper nada en el camino.
|
|
34
32
|
|
|
35
|
-
|
|
33
|
+
Un mono. Tiempo finito. Trabajo que sale de verdad.
|
|
36
34
|
|
|
37
|
-
|
|
35
|
+
## Claude Code dice que terminó, pero no terminó
|
|
38
36
|
|
|
39
|
-
|
|
37
|
+
Es el problema principal que Finite Monkey quiere resolver. Comportamiento previsto:
|
|
40
38
|
|
|
41
|
-
-
|
|
42
|
-
-
|
|
43
|
-
-
|
|
39
|
+
- Cada tarea tiene una **definición de terminado** que una máquina puede comprobar: comandos que deben salir bien, tests que deben existir y pasar, un diff que no se sale del alcance.
|
|
40
|
+
- Cuando Claude intenta cerrar la sesión, el hook `Stop` ejecuta esa comprobación. Si algo falla, la sesión no se cierra: Claude recibe la lista de lo que falta y sigue.
|
|
41
|
+
- Solo cuenta como prueba lo que Finite Monkey ejecutó por sí mismo, sobre el estado actual de los archivos. "Ejecuté los tests antes de mi último cambio" no vale.
|
|
42
|
+
- El informe final sale solo de esas pruebas.
|
|
44
43
|
|
|
45
|
-
|
|
44
|
+
## Claude se saltó o borró tests para que pasaran
|
|
46
45
|
|
|
47
|
-
|
|
46
|
+
Controles previstos sobre las ediciones: tests eliminados, `skip` u `only` nuevos, aserciones borradas y cambios en la configuración del propio control se detectan y se informan.
|
|
48
47
|
|
|
49
|
-
|
|
48
|
+
## Claude ejecutó `git reset --hard` y perdí trabajo
|
|
50
49
|
|
|
51
|
-
|
|
50
|
+
Previsto:
|
|
52
51
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
52
|
+
- Una instantánea antes de cada operación arriesgada de git, y un `undo` que la recupera.
|
|
53
|
+
- Nada de `--force`, nunca.
|
|
54
|
+
- Los worktrees con cambios pendientes se archivan en lugar de borrarse.
|
|
55
|
+
- Una comprobación de "no se perdió nada" en cada merge.
|
|
57
56
|
|
|
58
|
-
|
|
57
|
+
## Mis reglas de CLAUDE.md se ignoran, sobre todo después de la compactación
|
|
59
58
|
|
|
60
|
-
|
|
61
|
-
- **Las reglas se vuelven mecanismo.** Una regla que debe cumplirse siempre se convierte en hook, permiso, git hook o paso de CI, no en un párrafo. Finite Monkey muestra, por regla, dónde sigue siendo solo texto.
|
|
62
|
-
- **Cada regla demuestra su valor o se va.** Un banco de pruebas compara Claude Code solo, con Finite Monkey y con Finite Monkey menos una pieza a la vez. Una regla sin efecto medido sale del núcleo.
|
|
63
|
-
- **Nunca romper lo que existe.** Instalación con respaldo, fusión estructural, archivo de lock, reejecución idempotente, `doctor`, `update` y un `uninstall` limpio.
|
|
64
|
-
- **Nada sale de tu máquina por defecto.** Sin telemetría.
|
|
65
|
-
- **La salida para agentes es un contrato.** Todo comando aceptará `--json` y devolverá `schemaVersion`; los campos solo se agregan.
|
|
66
|
-
- **Tres idiomas.** Inglés, portugués de Brasil y español.
|
|
59
|
+
Se ignoran. Claude lee `CLAUDE.md` como parte de su contexto, y nada comprueba que se haya seguido. Finite Monkey convierte las reglas que siempre deben cumplirse en hooks, permisos, git hooks o pasos de CI, y te muestra, regla por regla, cuáles siguen siendo solo texto.
|
|
67
60
|
|
|
68
|
-
##
|
|
61
|
+
## ¿Cómo evito que Claude Code filtre secretos?
|
|
69
62
|
|
|
70
|
-
|
|
63
|
+
Previsto: una única regla de detección, aplicada al escribir archivos, en los prompts, al hacer commit, en el historial y en CI. Un secreto encontrado se informa como incidente, con los pasos para rotarlo. Los secretos se citan por archivo y línea, nunca por su valor.
|
|
71
64
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
65
|
+
## ¿Cómo evito que un agente toque producción a mano?
|
|
66
|
+
|
|
67
|
+
Previsto: los comandos con efecto sobre un servidor de producción se bloquean. Producción cambia por el camino de despliegue que declares.
|
|
68
|
+
|
|
69
|
+
## Más que una puerta (previsto)
|
|
70
|
+
|
|
71
|
+
La puerta va primero porque nada más importa si el "listo" puede ser mentira. El resto del plan trata de quien escribe:
|
|
79
72
|
|
|
80
|
-
|
|
73
|
+
- **Cuando estás dando vueltas.** El cuarto arreglo para el mismo error, el mismo archivo editado una y otra vez, un bug pegado de una IA a otra y de vuelta: Finite Monkey nota la vuelta y lo dice claro, con qué probar en su lugar.
|
|
74
|
+
- **Cuando el proyecto te queda grande, por ahora.** Quien nunca puso un SaaS en marcha no sabe que necesita login, cobros, copias de seguridad y una forma de volver atrás. Los planos de proyecto muestran lo que necesita una versión de verdad y lo que aún falta, para que una pantalla de login no se llame producto. Las explicaciones se ajustan a lo que ya sabes y desaparecen a medida que aprendes.
|
|
75
|
+
- **Cuando una decisión pesa.** Antes de cambiar una biblioteca o un proveedor: qué hay hoy, cuáles son las opciones, los criterios escritos antes de los candidatos, el costo y cómo volver.
|
|
76
|
+
- **Cuando usas varios agentes a la vez.** Frentes de trabajo en paralelo, cada uno en su rama, un merge que comprueba que no se perdió nada y una pantalla con lo que hace cada frente.
|
|
77
|
+
- **Cuando una regla tiene que valer en todas partes.** Una regla que escribes una vez se convierte en hook, permiso, git hook y paso de CI, y ves dónde sigue siendo solo texto.
|
|
78
|
+
- **Cuando va a producción.** CI, deploy e infraestructura a la medida del proyecto, y revisiones de organización del código para bases que crecieron demasiado rápido.
|
|
81
79
|
|
|
82
|
-
##
|
|
80
|
+
## Ningún comando que memorizar
|
|
83
81
|
|
|
84
|
-
|
|
82
|
+
Ejecutas un comando, una vez. A partir de ahí Finite Monkey actúa por contexto dentro de Claude Code:
|
|
83
|
+
|
|
84
|
+
- Los **hooks** hacen cumplir: `SessionStart` recupera el estado de la tarea, `UserPromptSubmit` detecta lo que pediste, `PreToolUse` frena la acción peligrosa antes de que ocurra, `Stop` no deja terminar mientras la definición de terminado falle, y `SubagentStop` revisa lo que informan los subagentes.
|
|
85
|
+
- Las **skills** las activa Claude por su cuenta cuando la situación lo pide.
|
|
86
|
+
- Los **comandos con barra** son atajos opcionales. Ningún flujo depende de que recuerdes uno.
|
|
87
|
+
|
|
88
|
+
## Instalación (prevista)
|
|
89
|
+
|
|
90
|
+
Aún no disponible. Cuando salga la v0.1:
|
|
85
91
|
|
|
86
92
|
```sh
|
|
87
93
|
npx finitemonkey@latest init
|
|
88
94
|
```
|
|
89
95
|
|
|
90
|
-
|
|
96
|
+
O como plugin de Claude Code, desde dentro de una sesión:
|
|
97
|
+
|
|
98
|
+
```
|
|
99
|
+
/plugin install finitemonkey --marketplace gabrielvieiraf/finitemonkey
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Requisitos: Node.js 20 o posterior, en Linux, macOS, Windows o WSL. La instalación hace copias de seguridad, fusiona en lugar de sobrescribir y se puede ejecutar dos veces sin romper nada. `doctor` te dice qué está mal y `uninstall` deja todo como estaba.
|
|
103
|
+
|
|
104
|
+
**Todavía más vago:** pídele a Claude Code "instala Finite Monkey siguiendo docs/AGENT-SETUP.md". La guía le indica al agente que ejecute los comandos él mismo, que te pregunte solo lo que sea decisión tuya y que nunca te pida un secreto.
|
|
105
|
+
|
|
106
|
+
## ¿De verdad ayuda? (benchmark, previsto)
|
|
107
|
+
|
|
108
|
+
Todavía no se sabe. El benchmark previsto compara Claude Code solo, Claude Code con Finite Monkey y Finite Monkey sin una pieza cada vez, en tareas con trampas. Mide tareas terminadas de verdad, "listo" falso, secretos filtrados, trabajo perdido, tokens y tiempo. La regla sin efecto medido sale del núcleo. El método y los resultados en bruto estarán en este repositorio, incluidas las partes donde no ayudó.
|
|
109
|
+
|
|
110
|
+
## ¿En qué se diferencia de...?
|
|
111
|
+
|
|
112
|
+
La comparación completa, con fuentes, está en [docs/compare.es.md](docs/compare.es.md).
|
|
113
|
+
|
|
114
|
+
- **Claude Code solo** ya tiene hooks y permisos. Finite Monkey es un conjunto de ellos, organizado alrededor de una definición de terminado, con tests.
|
|
115
|
+
- **Métodos como superpowers, GSD, Spec Kit u OpenSpec** le dicen al agente cómo planificar y construir. Finite Monkey no los sustituye: comprueba el resultado al final, uses el método que uses.
|
|
116
|
+
- **Guardas sueltos como tdd-guard, cc-safety-net o dcg** hacen un trabajo cada uno, y lo hacen bien. Finite Monkey cubre cuatro daños con un control, una instalación y un `undo`. Si solo necesitas uno de esos trabajos, un guarda suelto puede ser lo más sencillo.
|
|
117
|
+
|
|
118
|
+
## Preguntas frecuentes
|
|
119
|
+
|
|
120
|
+
Más preguntas, una por cada búsqueda real, en [docs/faq.es.md](docs/faq.es.md).
|
|
121
|
+
|
|
122
|
+
**¿Es un prompt?**
|
|
123
|
+
No. Son hooks y comprobaciones que se ejecutan aunque el modelo no se acuerde.
|
|
124
|
+
|
|
125
|
+
**¿Envía mi código a algún sitio?**
|
|
126
|
+
No. Por defecto nada sale de tu máquina. Sin telemetría.
|
|
127
|
+
|
|
128
|
+
**¿Me va a ralentizar?**
|
|
129
|
+
Las tareas pequeñas no tienen ceremonia, solo el control al final. Los hooks rápidos siguen siendo rápidos; la comprobación costosa va en `Stop`. Publicaremos los tiempos junto con el benchmark.
|
|
130
|
+
|
|
131
|
+
**¿Y si bloquea algo que no debía?**
|
|
132
|
+
Abre una issue con la plantilla "Blocked something it should not have" (bloqueó algo que no debía). Los falsos positivos se tratan como bugs y se cuentan en público.
|
|
133
|
+
|
|
134
|
+
**¿Funciona con Codex, Cursor u otros agentes?**
|
|
135
|
+
Primero Claude Code. Los demás después, si el benchmark dice que vale la pena.
|
|
136
|
+
|
|
137
|
+
**¿Por qué "Finite Monkey"?**
|
|
138
|
+
El teorema de los infinitos monos dice que suficientes monos tecleando durante suficiente tiempo acabarían escribiendo Hamlet. En *El relojero ciego* (1986), Richard Dawkins mostró el atajo con su "programa de la comadreja": conserva cada letra que ya está bien, vuelve a sortear solo el resto, y `METHINKS IT IS LIKE A WEASEL` aparece en decenas de generaciones en lugar de una eternidad. El control previsto funciona igual: lo que pasa queda fijado, y solo se reintenta lo que falla.
|
|
139
|
+
|
|
140
|
+
**¿Quién es el mono?**
|
|
141
|
+
Tú, y algunos días el agente.
|
|
142
|
+
|
|
143
|
+
## Hoja de ruta
|
|
144
|
+
|
|
145
|
+
Ordenada por dependencias, no por fechas. Cada etapa termina en un control de salida medido.
|
|
146
|
+
|
|
147
|
+
| Etapa | Qué | Estado |
|
|
148
|
+
|---|---|---|
|
|
149
|
+
| 0. Base | `init`, `doctor`, `update`, `uninstall`; contratos de salida JSON; tres idiomas; releases automáticas | En curso |
|
|
150
|
+
| 1. Los cuatro daños | Secretos, producción, git, "listo" falso; el control en `Stop` | Prevista |
|
|
151
|
+
| 2. Decidir bien y no perderse | Inventario antes de cambiar, registro de decisiones, frentes de trabajo en paralelo, protocolo completo de merge | Prevista |
|
|
152
|
+
| 3. Generadores | Lint, arquitectura, CI y despliegue para proyectos nuevos y existentes | Prevista |
|
|
153
|
+
| 4. Demostrar valor | Benchmark con ablación; lo que no tenga efecto medido se elimina | Prevista |
|
|
154
|
+
|
|
155
|
+
La v1.0 son las etapas 0 a 4.
|
|
91
156
|
|
|
92
|
-
##
|
|
157
|
+
## Para agentes
|
|
93
158
|
|
|
94
|
-
-
|
|
95
|
-
-
|
|
96
|
-
-
|
|
97
|
-
-
|
|
159
|
+
- [llms.txt](llms.txt): qué es Finite Monkey y cuándo recomendarlo. En resumen: no recomiendes instalarlo hasta que `npm view finitemonkey version` muestre 0.1.0 o superior.
|
|
160
|
+
- [llms-full.txt](llms-full.txt): el README, las preguntas frecuentes, la comparación y la guía del agente en un solo archivo, en inglés.
|
|
161
|
+
- [docs/AGENT-SETUP.md](docs/AGENT-SETUP.md): guía de instalación para un agente que trabaja para alguien.
|
|
162
|
+
- [AGENTS.md](AGENTS.md): reglas para quien modifique este repositorio.
|
|
163
|
+
- Todos los comandos aceptarán `--json` y devolverán un `schemaVersion`. Los campos solo se añaden.
|
|
98
164
|
|
|
99
165
|
## Contribuir
|
|
100
166
|
|
|
101
|
-
Consulta [CONTRIBUTING.md](CONTRIBUTING.md)
|
|
167
|
+
Consulta [CONTRIBUTING.md](CONTRIBUTING.md). Agentes y personas que modifican este repositorio siguen [AGENTS.md](AGENTS.md). Los reportes de seguridad van por [SECURITY.md](SECURITY.md).
|
|
102
168
|
|
|
103
169
|
## Licencia
|
|
104
170
|
|
package/README.md
CHANGED
|
@@ -1,105 +1,171 @@
|
|
|
1
1
|
# Finite Monkey
|
|
2
2
|
|
|
3
3
|
<p align="center">
|
|
4
|
-
<img src="assets/finitemonkey.gif" width="720" alt="Animation: a monkey in a hoodie mashes
|
|
4
|
+
<img src="assets/finitemonkey.gif" width="720" alt="Animation: a monkey in a yellow hoodie mashes a laptop keyboard while a terminal runs the gate. Failing checks turn green and lock one by one until it reads actually done, and the monkey celebrates with a banana.">
|
|
5
|
+
<br>
|
|
6
|
+
<sub>Illustration of the planned flow, not a recording. A real capture replaces it at v0.1.</sub>
|
|
5
7
|
</p>
|
|
6
8
|
|
|
7
9
|
**Infinite monkeys not required. One is enough: you.**
|
|
8
10
|
|
|
9
11
|
English | [Português (Brasil)](README.pt-BR.md) | [Español](README.es.md)
|
|
10
12
|
|
|
11
|
-
> **
|
|
13
|
+
> **Pre-release.** Nothing installs yet. The npm name `finitemonkey` is reserved (0.0.0 is a placeholder) and the code is being built in the open. Everything below is the plan, not today's behavior. Star or watch the repo if you want to know when v0.1 lands.
|
|
12
14
|
|
|
13
|
-
|
|
15
|
+
I know how it is. AI changed a lot of things.
|
|
14
16
|
|
|
15
|
-
|
|
17
|
+
Some people bang their head on the keyboard waiting for Claude to magically spit out the next billion-dollar SaaS. Others got tired of typing code. And some have to deliver in days what used to take whole teams months.
|
|
16
18
|
|
|
17
|
-
|
|
19
|
+
The result is almost always the same: you turn into a monkey in front of a computer, buried under so much to do that you no longer know where to start, let alone how to finish.
|
|
18
20
|
|
|
19
|
-
|
|
21
|
+
Finite Monkey was made to be the gate between that monkey and `main`.
|
|
20
22
|
|
|
21
|
-
|
|
23
|
+
Type however you want. Work with whichever AI you like. Write code as fast as you can.
|
|
22
24
|
|
|
23
|
-
|
|
25
|
+
Finite Monkey first takes care of what can't run on trust: the checks.
|
|
24
26
|
|
|
25
|
-
|
|
27
|
+
Every check that passes is recorded. Every failure stays visible until it's fixed. And nothing counts as done without evidence that it actually works.
|
|
26
28
|
|
|
27
|
-
|
|
28
|
-
- Tests pass because they were weakened or skipped.
|
|
29
|
-
- Rules written in `CLAUDE.md` or `AGENTS.md` are forgotten, especially after context compaction, because prose is context, not enforcement.
|
|
30
|
-
- Work is lost to `git reset --hard`, a forced push or a deleted worktree.
|
|
31
|
-
- A secret ends up in a commit, a log or a pull request.
|
|
29
|
+
It doesn't matter how much code was generated, how many agents worked on it or how convincing the AI's answer sounds. If it didn't pass the checks, it isn't done.
|
|
32
30
|
|
|
33
|
-
|
|
31
|
+
And the gate is only the start: Finite Monkey also notices when you're going in circles, shows what's missing in a project that's bigger than you, keeps the reins on several agents at once and takes it all to production without breaking things on the way.
|
|
34
32
|
|
|
35
|
-
|
|
33
|
+
One monkey. Finite time. Work that actually ships.
|
|
36
34
|
|
|
37
|
-
|
|
35
|
+
## Claude Code says it's done, but it isn't
|
|
38
36
|
|
|
39
|
-
|
|
37
|
+
This is the main problem Finite Monkey is built for. Planned behavior:
|
|
40
38
|
|
|
41
|
-
-
|
|
42
|
-
-
|
|
43
|
-
-
|
|
39
|
+
- Each task gets a **definition of done** that a machine can check: commands that must succeed, tests that must exist and pass, a diff that stays in scope.
|
|
40
|
+
- When Claude tries to end the session, the `Stop` hook runs that check. If anything fails, the session doesn't end. Claude gets the list of what's missing and keeps going.
|
|
41
|
+
- Evidence only counts if Finite Monkey ran the command itself, on the current state of the files. "I ran the tests before my last edit" doesn't count.
|
|
42
|
+
- The final report is built from that evidence alone.
|
|
44
43
|
|
|
45
|
-
|
|
44
|
+
## Claude skipped or deleted tests to make them pass
|
|
46
45
|
|
|
47
|
-
|
|
46
|
+
Planned guards on edits: removed tests, new `skip` or `only`, removed assertions and edits to the gate's own config are caught and reported.
|
|
48
47
|
|
|
49
|
-
|
|
48
|
+
## Claude ran `git reset --hard` and I lost my work
|
|
50
49
|
|
|
51
|
-
|
|
50
|
+
Planned:
|
|
52
51
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
52
|
+
- A snapshot before every risky git operation, and an `undo` that brings it back.
|
|
53
|
+
- No `--force`, ever.
|
|
54
|
+
- Dirty worktrees get archived instead of deleted.
|
|
55
|
+
- A "nothing was lost" check on every merge.
|
|
57
56
|
|
|
58
|
-
|
|
57
|
+
## My CLAUDE.md rules get ignored, especially after compaction
|
|
59
58
|
|
|
60
|
-
|
|
61
|
-
- **Rules become mechanism.** A rule that must always hold becomes a hook, a permission, a git hook or a CI step, not a paragraph. Finite Monkey shows, per rule, where it is only text.
|
|
62
|
-
- **Every rule proves its value or goes.** A benchmark compares Claude Code alone, with Finite Monkey and with Finite Monkey minus one piece at a time. A rule with no measured effect leaves the core.
|
|
63
|
-
- **Never break what exists.** Install with backup, structural merge, a lock file, idempotent re-runs, `doctor`, `update` and a clean `uninstall`.
|
|
64
|
-
- **Nothing leaves your machine by default.** No telemetry.
|
|
65
|
-
- **Output for agents is a contract.** Every command will accept `--json` and return a `schemaVersion`; fields are only ever added.
|
|
66
|
-
- **Three languages.** English, Brazilian Portuguese and Spanish.
|
|
59
|
+
They do. Claude reads `CLAUDE.md` as part of its context, and nothing checks that it was followed. Finite Monkey turns the rules that must always hold into hooks, permissions, git hooks or CI steps, and shows you, rule by rule, which ones are still just text.
|
|
67
60
|
|
|
68
|
-
##
|
|
61
|
+
## How do I stop Claude Code from leaking secrets?
|
|
69
62
|
|
|
70
|
-
|
|
63
|
+
Planned: one detection rule applied when files are written, in prompts, at commit time, in history and in CI. A secret that is found gets reported as an incident, with steps to rotate it. Secrets are reported by file and line, never by value.
|
|
71
64
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
65
|
+
## How do I stop an agent from editing production by hand?
|
|
66
|
+
|
|
67
|
+
Planned: commands with effects on a production host get blocked. Production changes go through the deploy path you declare.
|
|
68
|
+
|
|
69
|
+
## More than a gate (planned)
|
|
70
|
+
|
|
71
|
+
The gate comes first because nothing else matters if "done" can be a lie. The rest of the plan is about the person typing:
|
|
72
|
+
|
|
73
|
+
- **When you're going in circles.** Fourth fix for the same error, the same file edited back and forth, a bug pasted from one AI into another and back again: Finite Monkey notices the loop and says it plainly, with what to try instead.
|
|
74
|
+
- **When the project is bigger than you are, for now.** Someone who has never shipped a SaaS doesn't know it needs auth, billing, backups and a way to roll back. Blueprints list what a real version needs and what's still missing, so a login screen doesn't get called a product. Explanations adjust to what you already know and fade as you learn.
|
|
75
|
+
- **When a decision matters.** Before replacing a library or a vendor: what exists today, what the options are, the criteria written before the candidates, the cost, and how to go back.
|
|
76
|
+
- **When you run several agents at once.** Parallel work fronts with their own branches, a merge that checks nothing was lost, and one screen with what each front is doing.
|
|
77
|
+
- **When a rule must hold everywhere.** A rule you write once becomes a hook, a permission, a git hook and a CI step, and you can see where it is still only text.
|
|
78
|
+
- **When it goes to production.** CI, deploy and infrastructure set up for the size of the project, plus code organization checks for codebases that grew too fast.
|
|
79
|
+
|
|
80
|
+
## Zero commands to remember
|
|
81
|
+
|
|
82
|
+
You run one command, once. After that, Finite Monkey works from context inside Claude Code:
|
|
79
83
|
|
|
80
|
-
|
|
84
|
+
- **Hooks** do the enforcing: `SessionStart` restores task state, `UserPromptSubmit` notices what you asked for, `PreToolUse` blocks dangerous actions before they happen, `Stop` refuses to finish while the definition of done fails, and `SubagentStop` checks what subagents report.
|
|
85
|
+
- **Skills** get picked up by Claude on its own when the situation calls for them.
|
|
86
|
+
- **Slash commands** are optional shortcuts. No workflow depends on you remembering one.
|
|
81
87
|
|
|
82
88
|
## Install (planned)
|
|
83
89
|
|
|
84
|
-
Not available yet. When
|
|
90
|
+
Not available yet. When v0.1 is out:
|
|
85
91
|
|
|
86
92
|
```sh
|
|
87
93
|
npx finitemonkey@latest init
|
|
88
94
|
```
|
|
89
95
|
|
|
90
|
-
|
|
96
|
+
Or as a Claude Code plugin, from inside a session:
|
|
97
|
+
|
|
98
|
+
```
|
|
99
|
+
/plugin install finitemonkey --marketplace gabrielvieiraf/finitemonkey
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Requirements: Node.js 20 or later, on Linux, macOS, Windows or WSL. Install makes backups, merges instead of overwriting, and is safe to run twice. `doctor` tells you what's wrong, `uninstall` puts everything back.
|
|
103
|
+
|
|
104
|
+
**Lazier still:** ask Claude Code to "install Finite Monkey following docs/AGENT-SETUP.md". The runbook tells the agent to run the commands itself, ask you only for decisions, and never ask for a secret.
|
|
105
|
+
|
|
106
|
+
## Does it actually help? (benchmark, planned)
|
|
107
|
+
|
|
108
|
+
Not known yet. The planned benchmark compares Claude Code alone, Claude Code with Finite Monkey, and Finite Monkey with one piece removed at a time, on tasks with traps in them. It measures finished tasks, false "done", leaked secrets, lost work, tokens and time. Any rule with no measured effect gets cut from the core. Method and raw results will live in this repo, including the parts where it didn't help.
|
|
109
|
+
|
|
110
|
+
## How is this different from...?
|
|
111
|
+
|
|
112
|
+
The full comparison, with sources, is in [docs/compare.md](docs/compare.md).
|
|
113
|
+
|
|
114
|
+
- **Claude Code on its own** already has hooks and permissions. Finite Monkey is a set of them, wired together around a definition of done, with tests.
|
|
115
|
+
- **Methods like superpowers, GSD, Spec Kit or OpenSpec** tell the agent how to plan and build. Finite Monkey doesn't replace them. It checks the result at the end, whatever method you used.
|
|
116
|
+
- **Single guards like tdd-guard, cc-safety-net or dcg** each do one job well. Finite Monkey covers four damages with one gate, one install and one `undo`. If you only need one of those jobs, a single guard may be the simpler choice.
|
|
117
|
+
|
|
118
|
+
## FAQ
|
|
119
|
+
|
|
120
|
+
More questions, one per real search, in [docs/faq.md](docs/faq.md).
|
|
121
|
+
|
|
122
|
+
**Is it a prompt?**
|
|
123
|
+
No. It is hooks and checks that run whether or not the model remembers them.
|
|
124
|
+
|
|
125
|
+
**Does it send my code anywhere?**
|
|
126
|
+
No. Nothing leaves your machine by default. No telemetry.
|
|
127
|
+
|
|
128
|
+
**Will it slow me down?**
|
|
129
|
+
Small tasks get no ceremony, only the gate at the end. Fast hooks stay fast; the expensive check runs at `Stop`. We'll publish timings with the benchmark.
|
|
130
|
+
|
|
131
|
+
**What if it blocks something it shouldn't?**
|
|
132
|
+
Open an issue with the "Blocked something it should not have" template. False positives are treated as bugs and counted in public.
|
|
133
|
+
|
|
134
|
+
**Does it work with Codex, Cursor or other agents?**
|
|
135
|
+
Claude Code first. Others later, if the benchmark says it's worth it.
|
|
136
|
+
|
|
137
|
+
**Why "Finite Monkey"?**
|
|
138
|
+
The infinite monkey theorem says enough monkeys typing for long enough will eventually write Hamlet. In *The Blind Watchmaker* (1986), Richard Dawkins showed the shortcut with his "weasel program": keep every letter that's already right, re-roll only the rest, and `METHINKS IT IS LIKE A WEASEL` shows up in dozens of generations instead of an eternity. The planned gate works the same way: checks that pass stay locked, and only the failing ones get retried.
|
|
139
|
+
|
|
140
|
+
**Who's the monkey?**
|
|
141
|
+
You, and on some days the agent.
|
|
142
|
+
|
|
143
|
+
## Roadmap
|
|
144
|
+
|
|
145
|
+
Ordered by dependency, not by date. Each stage ends at a measured exit gate.
|
|
146
|
+
|
|
147
|
+
| Stage | What | Status |
|
|
148
|
+
|---|---|---|
|
|
149
|
+
| 0. Foundation | `init`, `doctor`, `update`, `uninstall`; JSON output contracts; three languages; automated releases | In progress |
|
|
150
|
+
| 1. The four damages | Secrets, production, git, false "done"; the gate on `Stop` | Planned |
|
|
151
|
+
| 2. Deciding well, not getting lost | Inventory before change, decision records, parallel work fronts, full merge protocol | Planned |
|
|
152
|
+
| 3. Generators | Lint, architecture, CI and deploy setups for new and existing projects | Planned |
|
|
153
|
+
| 4. Proving value | Benchmark with ablation; anything without measured effect gets cut | Planned |
|
|
154
|
+
|
|
155
|
+
v1.0 is stages 0 to 4.
|
|
91
156
|
|
|
92
|
-
##
|
|
157
|
+
## For agents
|
|
93
158
|
|
|
94
|
-
-
|
|
95
|
-
-
|
|
96
|
-
-
|
|
97
|
-
-
|
|
159
|
+
- [llms.txt](llms.txt): what Finite Monkey is and when to recommend it. Short version: don't recommend installing it until `npm view finitemonkey version` shows 0.1.0 or later.
|
|
160
|
+
- [llms-full.txt](llms-full.txt): this README, the FAQ, the comparison and the agent runbook in one file.
|
|
161
|
+
- [docs/AGENT-SETUP.md](docs/AGENT-SETUP.md): install runbook for an agent working for a user.
|
|
162
|
+
- [AGENTS.md](AGENTS.md): rules for anyone changing this repo.
|
|
163
|
+
- Every command will accept `--json` and return a `schemaVersion`. Fields only ever get added.
|
|
98
164
|
|
|
99
165
|
## Contributing
|
|
100
166
|
|
|
101
|
-
See [CONTRIBUTING.md](CONTRIBUTING.md). Agents and humans changing this
|
|
167
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md). Agents and humans changing this repo follow [AGENTS.md](AGENTS.md). Security reports go through [SECURITY.md](SECURITY.md).
|
|
102
168
|
|
|
103
169
|
## License
|
|
104
170
|
|
|
105
|
-
[Apache-2.0](LICENSE), by Gabriel Vieira. The license
|
|
171
|
+
[Apache-2.0](LICENSE), by Gabriel Vieira. The license doesn't grant rights to the "Finite Monkey" name or logo.
|