CommitCycle para Claude Code Shipped
CommitCycle para Claude Code
El plugin instala la parte que dice que no. Las áreas de tu código que son peligrosas de cambiar reciben un owner, el trabajo declara cuáles necesita, y el acceso se concede para una task en una rama — y se retira cuando entregas.
> add an index on tasks.updated_at — the board query is slow
● Write(apps/api/migrations/0042_tasks_updated_at.sql)
⎿ PreToolUse:Write — ✗ Denied by CC
zone schema · risk high
owner ana@acme.dev
task CC-42 declared no protected zones
reason path is in a zone the task never asked for
● The schema zone is closed to CC-42. Asking its owner rather than looking for another way in.
● Bash(cycle request-access --zone schema --mode write --reason "the board query needs an index" --alternative "hand the DDL to the owner")
⎿ REQ-7 is with the zone owner
approve or deny: https://dash.commitcycle.com/requests
El hook rechaza la escritura antes de que ocurra, nombra la zone y su owner, y el agente pide acceso en vez de buscar otro camino. Claude Code es donde se ha visto funcionar este bloqueo.
Instalación
/plugin marketplace add pow-paulinho/commitcycle-plugin
/plugin install commitcycle@commitcycleTrae sus propios binarios. No hay npm install y no se añade nada a tu PATH; el comando cycle que te piden las skills va aparte, con npm i -g commitcycle. Fuera del proyecto sólo escribe ~/.commitcycle/, para el inicio de sesión, el emparejamiento y la comprobación de actualizaciones — y, cuando el núcleo del hook no puede responder con la failure policy open por defecto, un marcador vacío por sesión en el directorio temporal.
Qué instala la versión 0.1.25
| Componente | Qué hace |
|---|---|
set-up-commitcycle | Configura un repositorio preguntando por él — qué áreas son peligrosas, quién aprueba cada una, a qué board reporta |
start-work-inside-cc | Registra y acota la task antes del trabajo, para que la regla llegue como un acuerdo y no como una negativa |
Servidor MCP commitcycle | Seis herramientas en la versión 0.1.25 (2026-10-12): el mapa de zones, intake de una línea, la entrevista, el scoping, el estado del board y qué tasks cambiaron un archivo. El intake y el scoping escriben en el board; ninguna mueve una task |
| El hook | La parte que de verdad bloquea una escritura, en PreToolUse y PostToolUse |
El hook Stop | En una rama de task, en un repositorio con board, publica en la task del board la última respuesta del agente y guarda una copia en .zones/state/replies/ |
Por qué instalarlo no puede romper tus otros repositorios
Los hooks de un plugin se cargan a nivel de usuario — se ejecutan en todos los repositorios que abras, no sólo en el que configuraste. Precisamente por eso el hook se retuvo hasta que supo distinguir "este repositorio nunca instaló CommitCycle" de "esta task aún no ha empezado". No sabía, respondía deny a las dos, y una sola instalación habría bloqueado cada escritura en cada proyecto sin relación de la máquina.
Ya sabe. Un repositorio sin .zones/zones.yml se deja en paz y en silencio: permitido, sin registro, sin consejos — no deberías poder notar que el hook se ejecutó. Y un mapa vacío no es lo mismo que un mapa ausente: eso es un proyecto que hizo la configuración y no protegió nada, así que ahí sigue haciendo falta una task.
Las seis herramientas, y la línea que no cruzan
cc_zones, cc_intake, cc_interview, cc_scope, cc_status, cc_why. Ninguna empieza trabajo, emite un grant ni aprueba acceso a nada. Una séptima, cc_search, que encuentra las tasks relacionadas con una petición o con unos archivos, está en el trunk desde el 2026-10-13 y todavía en ninguna versión publicada.
No es un descuido pendiente de arreglar. Una aprobación que llega por una herramienta que llama el agente va autenticada con un token que tiene el agente, así que un board no podría distinguir tu sí del suyo. Las herramientas describen el trabajo. Empezarlo es cycle start (o cc_start en el conector alojado), y la skill sólo lo ejecuta cuando tú lo dices.
Por qué el board no es opcional
El mapa de zones, la auditoría de lo que es peligroso y los registros de lo que declaró cada task son ficheros de tu repositorio, y siguen siendo tuyos. Lo que necesita un board es el ciclo: el gate es el único emisor de un grant, y vive allí. Instala el hook sin board y no habrá nada que pueda abrir nada — toda escritura se deniega, también en los paths sin proteger. Por eso la skill de configuración pide el board en lugar de ofrecer un modo local que acaba en un repositorio donde nadie puede escribir.
Dónde se detiene esto
El modelo de zones es agnóstico del agente; el punto de enforcement necesita un adaptador pequeño por cada harness. cycle init escribe archivos de hook — los de Claude Code y Codex por defecto, los de Cursor y Windsurf con --harness — sólo donde ya hay un wrapper del hook en disco; ninguno de los dos paquetes publicados lo pone ahí, así que en tu máquina no escribe ninguno y el que hace cumplir es el hook del plugin — sólo en Claude Code, así que Codex, Cursor y Windsurf no tienen hook ahí. Sólo se ha visto denegar a Claude Code en una instalación real. Donde se escriben los archivos de los demás, nunca se han probado y reciben la respuesta en el formato de Claude Code; Windsurf no tiene canal para el motivo de una denegación, y el archivo de Cursor sólo conecta preToolUse.
- El hook decidió en 68–83 ms en p95 contra un presupuesto de 100 ms, medido el 2026-08-03 con la primera versión del hook y una máquina en reposo — y el p99 tocó 102 ms en un caso. CC-1377 lo volvió a medir en octubre de 2026 en dos VM en la nube: en la más lenta, wrapper y núcleo llegaron a 211–228 ms en p95 (carga 0,74–1,04), y el coste del hook sobre un proceso node lanzado por shell fue de 84–111 ms allí frente a 44–48 ms en la más rápida, con el mismo código. Dos hosts, no un estudio.
- El harness de Claude Code es fail-open en los cuatro modos de fallo que medimos contra sesiones reales el 2026-08-03. Por eso el plugin trae un wrapper que puede cerrar tres de ellos cuando la failure policy del repositorio está en closed — por defecto deja pasar la llamada y se lo dice a la sesión — y por eso existe un check de CI para el cuarto, el único que CI puede ver, donde el hook nunca llegó a instalarse. Ese check hoy sólo corre en el repositorio de CommitCycle.
El mecanismo completo está en la documentación (en inglés): la referencia de instalación, el modelo de zones y las herramientas MCP.
Preguntas que responde esta página
¿Instalar el plugin afecta a mis otros repositorios?
No. Los hooks de un plugin se cargan a nivel de usuario, así que el hook sí se ejecuta en todos los repositorios que abras — y por eso se retuvo hasta que supo distinguir "este repositorio nunca instaló CommitCycle" de "esta task aún no ha empezado". Un repositorio sin mapa de zones se deja en paz, en silencio.
¿Necesito una cuenta para usar el plugin de Claude Code?
Sí, para trabajar con tasks. El gate es el único emisor de un grant y vive en el board, así que con el hook instalado y sin board no se puede abrir nada y toda escritura se deniega. El mapa de zones y los registros son ficheros que conservas igualmente — pero el ciclo necesita un board, y la skill de configuración lo dice en vez de ofrecer una vía local que acaba en un repositorio donde nadie puede escribir.