> ## Documentation Index
> Fetch the complete documentation index at: https://zeropath.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrações com Agentes de Codificação

> Escaneie o código que Claude Code, Codex e Cursor escrevem, no momento em que ele é escrito

O ZeroPath se integra a agentes de codificação com IA para que o código passe
por revisão de segurança no **ponto de geração**, antes mesmo de chegar a um
commit, a um PR ou à produção. Agentes suportados:

| Agente                                                       | Ferramentas MCP | Orientação do agente                      | Stop hook                             |
| ------------------------------------------------------------ | :-------------: | ----------------------------------------- | ------------------------------------- |
| [Claude Code](/pt/developer-tools/coding-agents/claude-code) |        ✅        | bloco gerenciado em `~/.claude/CLAUDE.md` | ✅ bloqueio ou monitoramento           |
| [OpenAI Codex](/pt/developer-tools/coding-agents/codex)      |        ✅        | bloco gerenciado em `~/.codex/AGENTS.md`  | ❌ sem suporte a hooks multiplataforma |
| [Cursor](/pt/developer-tools/coding-agents/cursor)           |        ✅        | `.cursor/rules/zeropath.mdc` por projeto  | ✅ observacional (beta)                |

<h2 id="installation">
  Instalação
</h2>

Um único instalador, do repositório
[ZeroPathAI/agent\_install](https://github.com/ZeroPathAI/agent_install),
detecta quais agentes estão presentes e configura todos eles:

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/ZeroPathAI/agent_install/main/install.sh | bash
```

O instalador solicita um token de API (crie um em **Settings → API
Tokens** no dashboard do ZeroPath), ou você pode passá-lo de forma não
interativa:

```bash theme={null}
export ZEROPATH_API_TOKEN_ID="..."
export ZEROPATH_API_TOKEN_SECRET="..."
curl -fsSL https://raw.githubusercontent.com/ZeroPathAI/agent_install/main/install.sh | bash
```

Flags úteis (após `bash -s --`): `--agents claude,codex,cursor`, `--org-id`,
`--base-url` (ambientes self-hosted / de branch), `--no-hooks`, `--no-mcp`,
`--no-rules`. Para desinstalar, execute o `uninstall.sh` do repositório da
mesma forma.

O que o instalador faz:

1. Instala a CLI `zeropath` em `~/.zeropath/bin/` e armazena as credenciais em
   `~/.config/zeropath/credentials.json`.
2. Registra o servidor MCP do ZeroPath em cada agente detectado (executado via
   `uvx`; o instalador avisa se o [uv](https://docs.astral.sh/uv/) estiver ausente).
3. Instala os scripts de stop hook em `~/.zeropath/hooks/` e os registra nos
   agentes que suportam hooks.
4. Adiciona os blocos de regras/orientação descritos abaixo.
5. Grava as configurações padrão em `~/.zeropath/config.env`
   (veja [Configuração](/pt/developer-tools/coding-agents/configuration)).

<h2 id="how-the-integration-works">
  Como a integração funciona
</h2>

A integração usa dois mecanismos deliberadamente diferentes.

<h3 id="1-mcp-tools-agent-initiated-context-rich">
  1. Ferramentas MCP — iniciadas pelo agente, ricas em contexto
</h3>

Cada agente é configurado com o [servidor MCP do ZeroPath](/pt/mcp/overview), que
expõe a API do ZeroPath como ferramentas que o próprio agente pode chamar —
consultas a issues, gerenciamento de varreduras e, principalmente, as
ferramentas de [Varredura de Código Sob Demanda](/pt/developer-tools/async-code-scans):

| Ferramenta               | Endpoint                                | Finalidade                                                   |
| ------------------------ | --------------------------------------- | ------------------------------------------------------------ |
| `asyncCodeScans.submit`  | `POST /api/v2/async-code-scans/submit`  | Enviar um diff, arquivos ou trechos de código para varredura |
| `asyncCodeScans.status`  | `POST /api/v2/async-code-scans/status`  | Consultar o estado do job                                    |
| `asyncCodeScans.results` | `POST /api/v2/async-code-scans/results` | Buscar vulnerabilidades estruturadas + correções sugeridas   |

O que torna essa superfície valiosa é o **contexto**: o agente sabe o que lhe
foi pedido para construir, quais entradas são controladas por atacantes e
quais suposições ele fez. O campo `additionalContext` da ferramenta `submit`
(até 20 KiB) leva esse conhecimento para a varredura, onde o ZeroPath o trata
como informação de contexto não confiável — não como instruções para o
scanner.

O instalador adiciona orientações para que os agentes realmente usem essas
ferramentas (os arquivos de regras na tabela acima): escanear após mudanças
não triviais, corrigir achados críticos/altos antes de declarar uma tarefa
concluída e apresentar o restante ao usuário.

A limitação é inerente: chamadas MCP acontecem a critério do modelo. Um
agente sob um prompt enganoso — ou simplesmente preguiçoso — pode pular a
varredura. É para isso que serve a segunda superfície.

<h3 id="2-stop-hooks-deterministic-harness-enforced">
  2. Stop hooks — determinísticos, aplicados pelo harness
</h3>

Harnesses de agentes com hooks de ciclo de vida executam o stop hook do
ZeroPath **toda vez que o agente termina um turno**, independentemente do que
o modelo decidir. O hook (`~/.zeropath/hooks/zeropath_hook.py`):

```
agent stops
  └─ hook reads the hook payload (workspace cwd, session id) from stdin
     └─ collects the uncommitted Git diff (staged + unstaged, `git diff HEAD`)
        ├─ no diff / not a repo → exit silently
        ├─ diff unchanged since last scan (sha256 cache) → reuse last verdict
        └─ otherwise: zeropath scan-code --diff --base-ref HEAD --caller agent --json
           └─ findings?
              ├─ monitoring mode → user-visible warning + full report in ~/.zeropath/logs/
              └─ blocking mode  → agent is blocked from stopping; findings are
                                  injected back so it remediates, then the
                                  rescan (new diff hash) decides again
```

Propriedades que vale a pena conhecer:

* **Fail open.** Erros de rede, problemas de autenticação e timeouts de
  varredura nunca bloqueiam o agente; eles aparecem como um aviso e são
  registrados em log.
* **Sem varreduras redundantes.** O SHA-256 do diff é armazenado em cache por
  workspace; um turno que não produziu mudanças de código não custa nada.
* **Loops de remediação limitados.** O modo de bloqueio gasta um orçamento por
  sessão (padrão: 3 bloqueios). Um agente que não consegue corrigir um achado
  eventualmente para, e os achados são repassados ao usuário em vez de entrar
  em loop para sempre.
* **Controlados por severidade.** Apenas achados no limiar configurado ou
  acima dele (padrão `high`) bloqueiam; tudo o que for encontrado ainda é
  reportado e registrado em log.

O suporte a hooks varia por agente: os Stop hooks do Claude Code podem
bloquear (loop completo de remediação); os stop hooks do Cursor são
observacionais; o Codex não tem mecanismo de hooks multiplataforma e depende
inteiramente da superfície MCP mais a orientação do `AGENTS.md`.

<Note>
  As varreduras disparadas por essas integrações são
  [Varreduras de Código Sob Demanda](/pt/developer-tools/async-code-scans): elas
  analisam apenas o diff/arquivos enviados (limites: 256 KiB de código, 20
  arquivos/trechos, 20 KiB de contexto adicional), executam de forma assíncrona
  (tipicamente dezenas de segundos) e os resultados expiram após 7 dias. Com
  `target.kind: "auto"` e uma URL de remote Git, o ZeroPath resolve o workspace
  para um repositório vinculado e enriquece a análise com o contexto persistido
  de repositório, aplicação e modelo de ameaças. Elas complementam — não
  substituem — as varreduras completas de repositório e a varredura de PRs.
</Note>

<h2 id="verifying-the-setup">
  Verificando a configuração
</h2>

* **Claude Code:** execute `/mcp` — um servidor `zeropath` deve aparecer
  listado e conectado. `claude --debug` mostra o Stop hook disparando ao final
  de um turno.
* **Codex:** execute `/mcp` na TUI do Codex, ou verifique se há um bloco
  `[mcp_servers.zeropath]` em `~/.codex/config.toml`.
* **Cursor:** abra **Settings → MCP** — `zeropath` deve aparecer listado com
  suas ferramentas.
* **De ponta a ponta:** peça ao agente para "escanear minhas alterações não
  commitadas com o ZeroPath", ou execute a mesma varredura que o hook executa:

```bash theme={null}
~/.zeropath/bin/zeropath scan-code --diff --base-ref HEAD --caller agent
```

<h2 id="telemetry-the-agent-caller">
  Telemetria: o caller `agent`
</h2>

As varreduras enviadas por essas integrações são marcadas com
`metadata.caller = "agent"` (hooks) ou `"mcp"` (chamadas MCP iniciadas pelo
agente), para que você possa distinguir varreduras no ponto de geração do uso
via CLI, IDE e pre-commit ao revisar a atividade de varredura.