Claude Code

MCP server, Stop hook, and CLAUDE.md guidance for Claude Code

The installer configures three things for Claude Code. All of them can also be set up manually as described below.

What the installer writes

File	What
~/.claude.json → mcpServers.zeropath	ZeroPath MCP server (user scope, all projects)
~/.claude/settings.json → hooks.Stop	Stop hook that scans the uncommitted diff after every turn
~/.claude/CLAUDE.md	Managed guidance block (between <!-- BEGIN/END ZEROPATH AGENT INTEGRATION --> markers) telling Claude to scan code it writes

Manual MCP setup

Equivalent to what the installer does:

claude mcp add --scope user zeropath \
  --env ZEROPATH_TOKEN_ID=your_token_id \
  --env ZEROPATH_TOKEN_SECRET=your_token_secret \
  -- uvx --from git+https://github.com/ZeroPathAI/zeropath-mcp-server zeropath-mcp-server

Optionally add --env ZEROPATH_ORG_ID=... (multi-org accounts) and --env ZEROPATH_BASE_URL=... (self-hosted).

Manual hook setup

In ~/.claude/settings.json:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/home/you/.zeropath/hooks/claude-stop-hook.sh",
            "timeout": 300
          }
        ]
      }
    ]
  }
}

The hook reads the Stop-hook payload from stdin, scans the workspace’s uncommitted diff, and responds using Claude Code’s hook protocol:

• Monitoring mode (default): emits a systemMessage summarizing findings; Claude is not interrupted. Full report in ~/.zeropath/logs/.
• Blocking mode (ZEROPATH_BLOCKING_STOP_HOOKS=true in ~/.zeropath/config.env): emits {"decision": "block", "reason": ...} for findings at or above the severity threshold. Claude receives the findings and suggested fixes as its next instruction, remediates, and the rescan on the next stop decides again. Loops are bounded by a per-session block budget (default 3).

Behavior notes

• The hook scans git diff HEAD (staged + unstaged). Untracked new files are not in that diff; Claude is guided (via CLAUDE.md) to scan those through the MCP asyncCodeScans.submit tool with input.kind: "files".
• A turn that changes no code re-uses the previous verdict (diff-hash cache) — conversational turns don’t pay scan latency.
• Scan failures fail open with a visible systemMessage, never a block.

Verify

/mcp                 # expect: zeropath — connected
claude --debug       # shows "Stop hook" execution at end of turn

Then make a code change in a Git repo and end the turn; in monitoring mode you should see a ZeroPath system message if findings exist, and a log file under ~/.zeropath/logs/ either way.