> ## 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.

# Coding Agent Integrations

> Scan code that Claude Code, Codex, and Cursor write, at the moment it is written

ZeroPath integrates with AI coding agents so that code is security-reviewed at
the **point of generation**, before it ever reaches a commit, a PR, or
production. Supported agents:

| Agent                                                     | MCP tools | Agent guidance                           | Stop hook                        |
| --------------------------------------------------------- | :-------: | ---------------------------------------- | -------------------------------- |
| [Claude Code](/developer-tools/coding-agents/claude-code) |     ✅     | managed block in `~/.claude/CLAUDE.md`   | ✅ blocking or monitoring         |
| [OpenAI Codex](/developer-tools/coding-agents/codex)      |     ✅     | managed block in `~/.codex/AGENTS.md`    | ❌ no cross-platform hook support |
| [Cursor](/developer-tools/coding-agents/cursor)           |     ✅     | per-project `.cursor/rules/zeropath.mdc` | ✅ observational (beta)           |

## Installation

One installer, from the
[ZeroPathAI/agent\_install](https://github.com/ZeroPathAI/agent_install)
repository, detects which agents are present and configures all of them:

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

The installer prompts for an API token (create one in **Settings → API
Tokens** in the ZeroPath dashboard), or you can pass it non-interactively:

```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
```

Useful flags (after `bash -s --`): `--agents claude,codex,cursor`, `--org-id`,
`--base-url` (self-hosted / branch environments), `--no-hooks`, `--no-mcp`,
`--no-rules`. To uninstall, run the repo's `uninstall.sh` the same way.

What the installer does:

1. Installs the `zeropath` CLI to `~/.zeropath/bin/` and stores credentials at
   `~/.config/zeropath/credentials.json`.
2. Registers the ZeroPath MCP server with each detected agent (run via `uvx`;
   the installer warns if [uv](https://docs.astral.sh/uv/) is missing).
3. Installs the stop-hook scripts to `~/.zeropath/hooks/` and registers them
   with agents that support hooks.
4. Adds the rules/guidance blocks described below.
5. Writes default settings to `~/.zeropath/config.env`
   (see [Configuration](/developer-tools/coding-agents/configuration)).

## How the integration works

The integration uses two deliberately different mechanisms.

### 1. MCP tools — agent-initiated, context-rich

Each agent is configured with the [ZeroPath MCP server](/mcp/overview), which
exposes ZeroPath's API as tools the agent can call itself — issue queries,
scan management, and crucially the
[On-Demand Code Scan](/developer-tools/async-code-scans) tools:

| Tool                     | Endpoint                                | Purpose                                            |
| ------------------------ | --------------------------------------- | -------------------------------------------------- |
| `asyncCodeScans.submit`  | `POST /api/v2/async-code-scans/submit`  | Submit a diff, files, or snippets for scanning     |
| `asyncCodeScans.status`  | `POST /api/v2/async-code-scans/status`  | Poll job state                                     |
| `asyncCodeScans.results` | `POST /api/v2/async-code-scans/results` | Fetch structured vulnerabilities + suggested fixes |

What makes this surface valuable is **context**: the agent knows what it was
asked to build, which inputs are attacker-controlled, and what assumptions it
made. The `submit` tool's `additionalContext` field (up to 20 KiB) carries
that knowledge into the scan, where ZeroPath treats it as untrusted background
information — not as scanner instructions.

The installer adds guidance so agents actually use these tools (the rules
files in the table above): scan after non-trivial changes, fix critical/high
findings before declaring a task done, surface the rest to the user.

The limitation is inherent: MCP calls happen at the model's discretion. An
agent under a misleading prompt — or just a lazy one — can skip the scan.
That is what the second surface is for.

### 2. Stop hooks — deterministic, harness-enforced

Agent harnesses with lifecycle hooks run the ZeroPath stop hook **every time
the agent finishes a turn**, regardless of what the model decides. The 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
```

Properties worth knowing:

* **Fail open.** Network errors, auth problems, and scan timeouts never block
  the agent; they surface as a warning and are logged.
* **No redundant scans.** The diff's SHA-256 is cached per workspace; a turn
  that produced no code changes costs nothing.
* **Bounded remediation loops.** Blocking mode spends a per-session budget
  (default 3 blocks). An agent that cannot fix a finding eventually stops and
  the findings fall through to the user instead of looping forever.
* **Severity-gated.** Only findings at or above the configured threshold
  (default `high`) block; everything found is still reported and logged.

Hook support varies by agent: Claude Code Stop hooks can block (full
remediation loop); Cursor stop hooks are observational; Codex has no
cross-platform hook mechanism and relies entirely on the MCP surface plus
`AGENTS.md` guidance.

<Note>
  Scans triggered by these integrations are
  [On-Demand Code Scans](/developer-tools/async-code-scans): they analyze only
  the submitted diff/files (limits: 256 KiB code, 20 files/snippets, 20 KiB
  additional context), run asynchronously (typically tens of seconds), and
  results expire after 7 days. With `target.kind: "auto"` and a Git remote URL,
  ZeroPath resolves the workspace to a linked repository and enriches the
  analysis with persisted repository, application, and threat-model context.
  They complement — not replace — full repository scans and PR scanning.
</Note>

## Verifying the setup

* **Claude Code:** run `/mcp` — a `zeropath` server should be listed and
  connected. `claude --debug` shows the Stop hook firing at the end of a turn.
* **Codex:** run `/mcp` in the Codex TUI, or check `~/.codex/config.toml` for
  an `[mcp_servers.zeropath]` block.
* **Cursor:** open **Settings → MCP** — `zeropath` should be listed with its
  tools.
* **End to end:** ask the agent to "scan my uncommitted changes with
  ZeroPath", or run the same scan the hook runs:

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

## Telemetry: the `agent` caller

Scans submitted by these integrations are tagged with
`metadata.caller = "agent"` (hooks) or `"mcp"` (agent-initiated MCP calls), so
you can distinguish point-of-generation scans from CLI, IDE, and pre-commit
usage when reviewing scan activity.