--- title: "Plugin do Claude Code: zones, uma task, acesso que expira" description: "Instale o CommitCycle no Claude Code: as skills dele, um servidor MCP e o hook que bloqueia uma escrita. Os paths que você nomeia ganham owner." url: https://commitcycle.com/pt-br/claude-code/ language: pt-BR --- # CommitCycle para Claude Code > Instale o CommitCycle no Claude Code: as skills dele, um servidor MCP e o hook que bloqueia uma escrita. Os paths que você nomeia ganham owner. CommitCycle para Claude Code Shipped 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. 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@commitcycle ``` Ele 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](https://commitcycle.com/docs/) (em inglês): a [referência de instalação](https://commitcycle.com/docs/start/install/), o [modelo de zones](https://commitcycle.com/pt-br/zones/) e as [ferramentas MCP](https://commitcycle.com/docs/reference/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.