CommitCycle para Claude Code Shipped
CommitCycle para Claude Code
O plugin instala a parte que diz não. As áreas do seu código que são perigosas de mudar ganham um owner, o trabalho declara de quais precisa, e o acesso é concedido para uma task em um branch — e devolvido quando você entrega.
> 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
O hook recusa a escrita antes que ela aconteça, nomeia a zone e o owner, e o agente pede acesso em vez de procurar outro caminho. O Claude Code é onde esse bloqueio já foi visto funcionando.
Instalação
/plugin marketplace add pow-paulinho/commitcycle-plugin
/plugin install commitcycle@commitcycleEle traz os próprios binários. Não há npm install e nada é adicionado ao seu PATH; o comando cycle que as skills pedem para você rodar vem à parte, com npm i -g commitcycle. Fora do projeto ele só escreve ~/.commitcycle/, para o login, o pareamento e a checagem de atualização — e, quando o núcleo do hook não consegue responder sob a failure policy open padrão, um marcador vazio por sessão no diretório temporário.
O que a versão 0.1.25 instala
| Componente | O que faz |
|---|---|
set-up-commitcycle | Configura um repositório perguntando sobre ele — quais áreas são perigosas, quem aprova cada uma, para qual board ele reporta |
start-work-inside-cc | Registra e delimita a task antes do trabalho, para que a regra chegue como um combinado e não como uma recusa |
Servidor MCP commitcycle | Seis ferramentas na versão 0.1.25 (2026-10-12): o mapa de zones, intake de uma linha, a entrevista, o scoping, o estado do board e quais tasks mudaram um arquivo. O intake e o scoping escrevem no board; nenhuma move uma task |
| O hook | A parte que de fato bloqueia uma escrita, em PreToolUse e PostToolUse |
O hook Stop | Num branch de task, num repositório com board, publica na task do board a última resposta do agente e guarda uma cópia em .zones/state/replies/ |
Por que instalar isso não quebra seus outros repositórios
Os hooks de um plugin carregam no nível do usuário — rodam em todo repositório que você abrir, não só naquele que você configurou. Foi exatamente por isso que o hook ficou retido até saber distinguir "este repositório nunca instalou CommitCycle" de "esta task ainda não começou". Ele não sabia, respondia deny para as duas, e uma única instalação teria bloqueado cada escrita em cada projeto sem relação na máquina.
Agora sabe. Um repositório sem .zones/zones.yml é deixado em paz e em silêncio: permitido, sem registro, sem conselhos — você não deveria conseguir perceber que o hook rodou. E um mapa vazio não é a mesma coisa que um mapa ausente: isso é um projeto que fez a configuração e não protegeu nada, então ali uma task continua sendo exigida.
As seis ferramentas, e a linha que elas não cruzam
cc_zones, cc_intake, cc_interview, cc_scope, cc_status, cc_why. Nenhuma inicia trabalho, emite um grant ou aprova acesso a nada. Uma sétima, cc_search, que encontra as tasks relacionadas a um pedido ou a arquivos, está no trunk desde 2026-10-13 e ainda em nenhuma versão publicada.
Isso não é um descuido a ser corrigido depois. Uma aprovação que chega por uma ferramenta chamada pelo agente é autenticada por um token que o agente carrega, então um board não teria como distinguir o seu sim do dele. As ferramentas descrevem o trabalho. Iniciá-lo é cycle start (ou cc_start no conector hospedado), e a skill só o roda quando você manda.
Por que o board não é opcional
O mapa de zones, a auditoria do que é perigoso e os registros do que cada task declarou são arquivos do seu repositório, e continuam sendo seus. O que precisa de um board é o ciclo: o gate é o único emissor de um grant, e ele roda lá. Instale o hook sem board e nada conseguirá abrir coisa alguma — toda escrita é negada, inclusive nos paths desprotegidos. Por isso a skill de configuração pede o board em vez de oferecer um modo local que termina num repositório onde ninguém consegue escrever.
Onde isso para
O modelo de zones independe do agente; o ponto de enforcement precisa de um adaptador pequeno por harness. O cycle init escreve arquivos de hook — os do Claude Code e do Codex por padrão, os do Cursor e do Windsurf com --harness — só onde já existe um wrapper do hook em disco; nenhum dos dois pacotes publicados coloca um ali, então na sua máquina ele não escreve nenhum e quem faz valer é o hook do plugin — só no Claude Code, então Codex, Cursor e Windsurf ficam sem hook ali. Só o Claude Code já foi visto negando numa instalação real. Onde os arquivos dos outros são escritos, eles nunca foram exercitados e recebem a resposta no formato do Claude Code; o Windsurf não tem canal para o motivo de uma negação, e o arquivo do Cursor só liga o preToolUse.
- O hook decidiu em 68–83 ms no p95 contra um orçamento de 100 ms, medido em 2026-08-03 com a primeira versão do hook e uma máquina ociosa — e o p99 encostou em 102 ms num caso. O CC-1377 mediu de novo em outubro de 2026 em duas VMs na nuvem: na mais lenta, wrapper e núcleo chegaram a 211–228 ms no p95 (carga 0,74–1,04), e o custo do hook sobre um processo node lançado por shell foi de 84–111 ms lá contra 44–48 ms na mais rápida, com o mesmo código. Dois hosts, não um levantamento.
- O harness do Claude Code é fail-open nos quatro modos de falha que medimos contra sessões reais em 2026-08-03. Por isso o plugin traz um wrapper que pode fechar três deles quando a failure policy do repositório está em closed — por padrão ele deixa a chamada passar e avisa a sessão — e por isso existe um check de CI para o quarto, o único que a CI consegue ver, onde o hook nunca chegou a ser instalado. Esse check hoje só roda no repositório do CommitCycle.
O mecanismo completo está na documentação (em inglês): a referência de instalação, o modelo de zones e as ferramentas MCP.
Perguntas que esta página responde
Instalar o plugin afeta meus outros repositórios?
Não. Os hooks de um plugin carregam no nível do usuário, então o hook roda em todo repositório que você abrir — e foi exatamente por isso que ele ficou retido até saber distinguir "este repositório nunca instalou CommitCycle" de "esta task ainda não começou". Um repositório sem mapa de zones é deixado em paz, silenciosamente.
Preciso de conta para usar o plugin do Claude Code?
Sim, para trabalhar com tasks. O gate é o único emissor de um grant e ele roda no board, então com o hook instalado e sem board nada pode ser aberto e toda escrita é negada. O mapa de zones e os registros são arquivos que você mantém de todo jeito — mas o ciclo precisa de um board, e a skill de configuração diz isso em vez de oferecer um caminho local que termina num repositório onde ninguém consegue escrever.