finitemonkey 0.1.0-next.1 → 0.1.0-next.2
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 +97 -60
- package/README.md +97 -60
- package/README.pt-BR.md +98 -61
- package/dist/finitemonkey.mjs +1702 -38
- package/package.json +18 -7
package/README.es.md
CHANGED
|
@@ -1,104 +1,141 @@
|
|
|
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
|
+
Claude Code cierra un refactor con "¡Listo! Todos los tests pasan." Solo había ejecutado el linter. El único test que fallaba recibió un `.skip` a las dos de la madrugada, y la CI se puso en rojo veinte minutos después del merge. Finite Monkey se está construyendo como hooks de Claude Code que ejecutan tus comprobaciones por su cuenta cuando el agente intenta parar, y mantienen la sesión abierta hasta que pasan. El mono de la sudadera amarilla eres tú.
|
|
14
16
|
|
|
15
|
-
|
|
17
|
+
## Claude Code dice que terminó, pero no terminó
|
|
16
18
|
|
|
17
|
-
|
|
19
|
+
Es el problema principal que Finite Monkey quiere resolver. Comportamiento previsto:
|
|
18
20
|
|
|
19
|
-
|
|
21
|
+
- 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.
|
|
22
|
+
- 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.
|
|
23
|
+
- 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.
|
|
24
|
+
- El informe final sale solo de esas pruebas.
|
|
20
25
|
|
|
21
|
-
|
|
26
|
+
## Claude se saltó o borró tests para que pasaran
|
|
22
27
|
|
|
23
|
-
|
|
28
|
+
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.
|
|
24
29
|
|
|
25
|
-
|
|
30
|
+
## Claude ejecutó `git reset --hard` y perdí trabajo
|
|
26
31
|
|
|
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.
|
|
32
|
+
Previsto:
|
|
32
33
|
|
|
33
|
-
|
|
34
|
+
- Una instantánea antes de cada operación arriesgada de git, y un `undo` que la recupera.
|
|
35
|
+
- Nada de `--force`, nunca.
|
|
36
|
+
- Los worktrees con cambios pendientes se archivan en lugar de borrarse.
|
|
37
|
+
- Una comprobación de "no se perdió nada" en cada merge.
|
|
34
38
|
|
|
35
|
-
##
|
|
39
|
+
## Mis reglas de CLAUDE.md se ignoran, sobre todo después de la compactación
|
|
36
40
|
|
|
37
|
-
|
|
41
|
+
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.
|
|
38
42
|
|
|
39
|
-
|
|
43
|
+
## ¿Cómo evito que Claude Code filtre secretos?
|
|
40
44
|
|
|
41
|
-
|
|
42
|
-
- **Skills** que Claude invoca automáticamente, según su descripción, cuando la situación lo pide.
|
|
43
|
-
- **Slash commands** existen solo como atajos opcionales. Ningún flujo depende de ellos.
|
|
45
|
+
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.
|
|
44
46
|
|
|
45
|
-
|
|
47
|
+
## ¿Cómo evito que un agente toque producción a mano?
|
|
46
48
|
|
|
47
|
-
|
|
49
|
+
Previsto: los comandos con efecto sobre un servidor de producción se bloquean. Producción cambia por el camino de despliegue que declares.
|
|
48
50
|
|
|
49
|
-
|
|
51
|
+
## Ningún comando que memorizar
|
|
50
52
|
|
|
51
|
-
|
|
53
|
+
Ejecutas un comando, una vez. A partir de ahí Finite Monkey actúa por contexto dentro de Claude Code:
|
|
52
54
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
4. **Un "listo" falso.** La compuerta de arriba, más protecciones contra pruebas eliminadas, `skip` u `only` nuevos, aserciones eliminadas y ediciones a la configuración de la propia compuerta.
|
|
55
|
+
- 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.
|
|
56
|
+
- Las **skills** las activa Claude por su cuenta cuando la situación lo pide.
|
|
57
|
+
- Los **comandos con barra** son atajos opcionales. Ningún flujo depende de que recuerdes uno.
|
|
57
58
|
|
|
58
|
-
|
|
59
|
+
## Instalación (prevista)
|
|
59
60
|
|
|
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.
|
|
61
|
+
Aún no disponible. Cuando salga la v0.1:
|
|
67
62
|
|
|
68
|
-
|
|
63
|
+
```sh
|
|
64
|
+
npx finitemonkey@latest init
|
|
65
|
+
```
|
|
69
66
|
|
|
70
|
-
|
|
67
|
+
O como plugin de Claude Code, desde dentro de una sesión:
|
|
71
68
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
| 1. Los cuatro daños | Secretos, producción, git, "listo" falso; la compuerta en `Stop` | Planeado |
|
|
76
|
-
| 2. Decidir bien y no perderse | Inventario antes de cambiar, registros de decisión, controles de costo y de paridad, frentes de trabajo en paralelo, protocolo completo de merge, reglas compiladas por superficie | Planeado |
|
|
77
|
-
| 3. Generadores | Generadores de lint, arquitectura, CI y despliegue para proyectos nuevos y existentes | Planeado |
|
|
78
|
-
| 4. Demostrar valor | Banco de pruebas con ablación; se recortan las piezas sin efecto medido | Planeado |
|
|
69
|
+
```
|
|
70
|
+
/plugin install finitemonkey --marketplace gabrielvieiraf/finitemonkey
|
|
71
|
+
```
|
|
79
72
|
|
|
80
|
-
|
|
73
|
+
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.
|
|
81
74
|
|
|
82
|
-
|
|
75
|
+
**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.
|
|
83
76
|
|
|
84
|
-
|
|
77
|
+
## ¿De verdad ayuda? (benchmark, previsto)
|
|
85
78
|
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
79
|
+
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ó.
|
|
80
|
+
|
|
81
|
+
## ¿En qué se diferencia de...?
|
|
82
|
+
|
|
83
|
+
La comparación completa, con fuentes, está en [docs/compare.es.md](docs/compare.es.md).
|
|
84
|
+
|
|
85
|
+
- **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.
|
|
86
|
+
- **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.
|
|
87
|
+
- **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.
|
|
88
|
+
|
|
89
|
+
## Preguntas frecuentes
|
|
90
|
+
|
|
91
|
+
Más preguntas, una por cada búsqueda real, en [docs/faq.es.md](docs/faq.es.md).
|
|
92
|
+
|
|
93
|
+
**¿Es un prompt?**
|
|
94
|
+
No. Son hooks y comprobaciones que se ejecutan aunque el modelo no se acuerde.
|
|
95
|
+
|
|
96
|
+
**¿Envía mi código a algún sitio?**
|
|
97
|
+
No. Por defecto nada sale de tu máquina. Sin telemetría.
|
|
98
|
+
|
|
99
|
+
**¿Me va a ralentizar?**
|
|
100
|
+
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.
|
|
101
|
+
|
|
102
|
+
**¿Y si bloquea algo que no debía?**
|
|
103
|
+
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.
|
|
104
|
+
|
|
105
|
+
**¿Funciona con Codex, Cursor u otros agentes?**
|
|
106
|
+
Primero Claude Code. Los demás después, si el benchmark dice que vale la pena.
|
|
107
|
+
|
|
108
|
+
**¿Por qué "Finite Monkey"?**
|
|
109
|
+
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.
|
|
110
|
+
|
|
111
|
+
**¿Quién es el mono?**
|
|
112
|
+
Tú, y algunos días el agente.
|
|
113
|
+
|
|
114
|
+
## Hoja de ruta
|
|
115
|
+
|
|
116
|
+
Ordenada por dependencias, no por fechas. Cada etapa termina en un control de salida medido.
|
|
117
|
+
|
|
118
|
+
| Etapa | Qué | Estado |
|
|
119
|
+
|---|---|---|
|
|
120
|
+
| 0. Base | `init`, `doctor`, `update`, `uninstall`; contratos de salida JSON; tres idiomas; releases automáticas | En curso |
|
|
121
|
+
| 1. Los cuatro daños | Secretos, producción, git, "listo" falso; el control en `Stop` | Prevista |
|
|
122
|
+
| 2. Decidir bien y no perderse | Inventario antes de cambiar, registro de decisiones, frentes de trabajo en paralelo, protocolo completo de merge | Prevista |
|
|
123
|
+
| 3. Generadores | Lint, arquitectura, CI y despliegue para proyectos nuevos y existentes | Prevista |
|
|
124
|
+
| 4. Demostrar valor | Benchmark con ablación; lo que no tenga efecto medido se elimina | Prevista |
|
|
89
125
|
|
|
90
|
-
|
|
126
|
+
La v1.0 son las etapas 0 a 4.
|
|
91
127
|
|
|
92
|
-
##
|
|
128
|
+
## Para agentes
|
|
93
129
|
|
|
94
|
-
-
|
|
95
|
-
-
|
|
96
|
-
-
|
|
97
|
-
-
|
|
130
|
+
- [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.
|
|
131
|
+
- [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.
|
|
132
|
+
- [docs/AGENT-SETUP.md](docs/AGENT-SETUP.md): guía de instalación para un agente que trabaja para alguien.
|
|
133
|
+
- [AGENTS.md](AGENTS.md): reglas para quien modifique este repositorio.
|
|
134
|
+
- Todos los comandos aceptarán `--json` y devolverán un `schemaVersion`. Los campos solo se añaden.
|
|
98
135
|
|
|
99
136
|
## Contribuir
|
|
100
137
|
|
|
101
|
-
Consulta [CONTRIBUTING.md](CONTRIBUTING.md)
|
|
138
|
+
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
139
|
|
|
103
140
|
## Licencia
|
|
104
141
|
|
package/README.md
CHANGED
|
@@ -1,105 +1,142 @@
|
|
|
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
|
+
Claude Code ends a refactor with "Done! All tests pass." It had only run the linter. The only failing test got a `.skip` at 2 a.m., and CI went red twenty minutes after the merge. Finite Monkey is planned as Claude Code hooks that run your checks themselves when the agent tries to stop, and keep the session open until they pass. The monkey in the yellow hoodie is you.
|
|
14
16
|
|
|
15
|
-
|
|
17
|
+
## Claude Code says it's done, but it isn't
|
|
16
18
|
|
|
17
|
-
|
|
19
|
+
This is the main problem Finite Monkey is built for. Planned behavior:
|
|
18
20
|
|
|
19
|
-
|
|
21
|
+
- 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.
|
|
22
|
+
- 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.
|
|
23
|
+
- 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.
|
|
24
|
+
- The final report is built from that evidence alone.
|
|
20
25
|
|
|
21
|
-
|
|
26
|
+
## Claude skipped or deleted tests to make them pass
|
|
22
27
|
|
|
23
|
-
|
|
28
|
+
Planned guards on edits: removed tests, new `skip` or `only`, removed assertions and edits to the gate's own config are caught and reported.
|
|
24
29
|
|
|
25
|
-
|
|
30
|
+
## Claude ran `git reset --hard` and I lost my work
|
|
26
31
|
|
|
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.
|
|
32
|
+
Planned:
|
|
32
33
|
|
|
33
|
-
|
|
34
|
+
- A snapshot before every risky git operation, and an `undo` that brings it back.
|
|
35
|
+
- No `--force`, ever.
|
|
36
|
+
- Dirty worktrees get archived instead of deleted.
|
|
37
|
+
- A "nothing was lost" check on every merge.
|
|
34
38
|
|
|
35
|
-
##
|
|
39
|
+
## My CLAUDE.md rules get ignored, especially after compaction
|
|
36
40
|
|
|
37
|
-
|
|
41
|
+
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.
|
|
38
42
|
|
|
39
|
-
|
|
43
|
+
## How do I stop Claude Code from leaking secrets?
|
|
40
44
|
|
|
41
|
-
|
|
42
|
-
- **Skills** are invoked by Claude automatically, based on their description, when the situation calls for them.
|
|
43
|
-
- **Slash commands** exist only as optional shortcuts. No workflow requires them.
|
|
45
|
+
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.
|
|
44
46
|
|
|
45
|
-
|
|
47
|
+
## How do I stop an agent from editing production by hand?
|
|
46
48
|
|
|
47
|
-
|
|
49
|
+
Planned: commands with effects on a production host get blocked. Production changes go through the deploy path you declare.
|
|
48
50
|
|
|
49
|
-
|
|
51
|
+
## Zero commands to remember
|
|
50
52
|
|
|
51
|
-
|
|
53
|
+
You run one command, once. After that, Finite Monkey works from context inside Claude Code:
|
|
52
54
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
4. **False "done".** The gate above, plus guards against removed tests, new `skip` or `only`, removed assertions and edits to the gate's own configuration.
|
|
55
|
+
- **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.
|
|
56
|
+
- **Skills** get picked up by Claude on its own when the situation calls for them.
|
|
57
|
+
- **Slash commands** are optional shortcuts. No workflow depends on you remembering one.
|
|
57
58
|
|
|
58
|
-
|
|
59
|
+
## Install (planned)
|
|
59
60
|
|
|
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.
|
|
61
|
+
Not available yet. When v0.1 is out:
|
|
67
62
|
|
|
68
|
-
|
|
63
|
+
```sh
|
|
64
|
+
npx finitemonkey@latest init
|
|
65
|
+
```
|
|
69
66
|
|
|
70
|
-
|
|
67
|
+
Or as a Claude Code plugin, from inside a session:
|
|
71
68
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
| 1. The four damages | Secrets, production, git, false "done"; the gate on `Stop` | Planned |
|
|
76
|
-
| 2. Deciding well and not getting lost | Inventory before change, decision records, cost and parity checks, parallel work fronts, full merge protocol, rules compiled per surface | Planned |
|
|
77
|
-
| 3. Generators | Lint, architecture, CI and deploy generators for new and existing projects | Planned |
|
|
78
|
-
| 4. Proving value | Benchmark with ablation; pieces without measured effect are cut | Planned |
|
|
69
|
+
```
|
|
70
|
+
/plugin install finitemonkey --marketplace gabrielvieiraf/finitemonkey
|
|
71
|
+
```
|
|
79
72
|
|
|
80
|
-
|
|
73
|
+
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.
|
|
81
74
|
|
|
82
|
-
|
|
75
|
+
**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.
|
|
83
76
|
|
|
84
|
-
|
|
77
|
+
## Does it actually help? (benchmark, planned)
|
|
85
78
|
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
79
|
+
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.
|
|
80
|
+
|
|
81
|
+
## How is this different from...?
|
|
82
|
+
|
|
83
|
+
The full comparison, with sources, is in [docs/compare.md](docs/compare.md).
|
|
84
|
+
|
|
85
|
+
- **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.
|
|
86
|
+
- **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.
|
|
87
|
+
- **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.
|
|
88
|
+
|
|
89
|
+
## FAQ
|
|
90
|
+
|
|
91
|
+
More questions, one per real search, in [docs/faq.md](docs/faq.md).
|
|
92
|
+
|
|
93
|
+
**Is it a prompt?**
|
|
94
|
+
No. It is hooks and checks that run whether or not the model remembers them.
|
|
95
|
+
|
|
96
|
+
**Does it send my code anywhere?**
|
|
97
|
+
No. Nothing leaves your machine by default. No telemetry.
|
|
98
|
+
|
|
99
|
+
**Will it slow me down?**
|
|
100
|
+
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.
|
|
101
|
+
|
|
102
|
+
**What if it blocks something it shouldn't?**
|
|
103
|
+
Open an issue with the "Blocked something it should not have" template. False positives are treated as bugs and counted in public.
|
|
104
|
+
|
|
105
|
+
**Does it work with Codex, Cursor or other agents?**
|
|
106
|
+
Claude Code first. Others later, if the benchmark says it's worth it.
|
|
107
|
+
|
|
108
|
+
**Why "Finite Monkey"?**
|
|
109
|
+
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.
|
|
110
|
+
|
|
111
|
+
**Who's the monkey?**
|
|
112
|
+
You, and on some days the agent.
|
|
113
|
+
|
|
114
|
+
## Roadmap
|
|
115
|
+
|
|
116
|
+
Ordered by dependency, not by date. Each stage ends at a measured exit gate.
|
|
117
|
+
|
|
118
|
+
| Stage | What | Status |
|
|
119
|
+
|---|---|---|
|
|
120
|
+
| 0. Foundation | `init`, `doctor`, `update`, `uninstall`; JSON output contracts; three languages; automated releases | In progress |
|
|
121
|
+
| 1. The four damages | Secrets, production, git, false "done"; the gate on `Stop` | Planned |
|
|
122
|
+
| 2. Deciding well, not getting lost | Inventory before change, decision records, parallel work fronts, full merge protocol | Planned |
|
|
123
|
+
| 3. Generators | Lint, architecture, CI and deploy setups for new and existing projects | Planned |
|
|
124
|
+
| 4. Proving value | Benchmark with ablation; anything without measured effect gets cut | Planned |
|
|
89
125
|
|
|
90
|
-
|
|
126
|
+
v1.0 is stages 0 to 4.
|
|
91
127
|
|
|
92
|
-
##
|
|
128
|
+
## For agents
|
|
93
129
|
|
|
94
|
-
-
|
|
95
|
-
-
|
|
96
|
-
-
|
|
97
|
-
-
|
|
130
|
+
- [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.
|
|
131
|
+
- [llms-full.txt](llms-full.txt): this README, the FAQ, the comparison and the agent runbook in one file.
|
|
132
|
+
- [docs/AGENT-SETUP.md](docs/AGENT-SETUP.md): install runbook for an agent working for a user.
|
|
133
|
+
- [AGENTS.md](AGENTS.md): rules for anyone changing this repo.
|
|
134
|
+
- Every command will accept `--json` and return a `schemaVersion`. Fields only ever get added.
|
|
98
135
|
|
|
99
136
|
## Contributing
|
|
100
137
|
|
|
101
|
-
See [CONTRIBUTING.md](CONTRIBUTING.md). Agents and humans changing this
|
|
138
|
+
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
139
|
|
|
103
140
|
## License
|
|
104
141
|
|
|
105
|
-
[Apache-2.0](LICENSE), by Gabriel Vieira. The license
|
|
142
|
+
[Apache-2.0](LICENSE), by Gabriel Vieira. The license doesn't grant rights to the "Finite Monkey" name or logo.
|