# Connect a coding agent

> Wire Claude Code, Codex, OpenCode or any MCP client to Blop so the agent's sessions are captured and it can query the collector.

Connect a coding agent so Blop captures its prompts, tool calls and errors through [hooks](/reference/glossary/#agents), and the agent can read issues and audits over MCP.

## Agent connection prerequisites

- The Blop CLI on your `PATH` ([Quickstart](/quickstart/)).
- The coding agent installed. A missing binary exits 127 with an install hint.
- A Git repository. Blop binds capture to its root and names the project after its directory, for example `my-app`.

## Connect an agent to Blop in one launch

1. Change to your repository:

   ```bash
   cd my-app
   ```

2. Start your agent through Blop with the command in its tab below, for example `blop claude`.

On the first launch Blop starts or reuses the collector, installs the agent's hooks, adds Blop's MCP server and enables capture for this repository (project scope). It lists every file it changed on stderr and ends with a `To undo:` line. Later launches change nothing.

Arguments after `--` go to the agent, for example `blop claude -- --resume abc`. `--no-connect` starts the agent without wiring anything. The launcher exits with the agent's exit code. It fails open: if wiring is refused (for example a [symlinked path](/troubleshooting/#blop-claude-says-a-path-is-a-symlink-so-blop-will-not-edit-it)) or the collector cannot start, it prints one warning with the fix and starts the agent without capture.

**Claude Code**

```bash
blop claude
```

Writes the hooks to `~/.claude/settings.json` and the MCP entry to the project's `.mcp.json`. Approve `blop` when Claude Code asks, or run `/mcp` inside it.

Undo, from the repository root. The last command removes Blop's entry from the project's `.mcp.json`; it names `pi` because Claude Code reads the same file:

```bash
blop agents install-hooks claude-code --project my-app --remove --apply && blop agents setup claude-code --project my-app --remove && blop setup mcp pi --scope project --remove
```

**Codex**

```bash
blop codex
```

Writes the hooks to `~/.codex/config.toml` and `~/.codex/hooks.json` (or under `CODEX_HOME`), and adds the MCP entry with `codex mcp add` at user scope. Codex runs new hooks only after you trust them: run `/hooks` in Codex and trust Blop's entries.

Undo, from the repository root. The last command removes Blop's MCP entry for every Codex project:

```bash
blop agents install-hooks codex --project my-app --remove --apply && blop agents setup codex --project my-app --remove && blop setup mcp codex --scope user --remove
```

**OpenCode**

```bash
blop opencode
```

Registers Blop's plugin in `~/.config/opencode/opencode.jsonc` (comments kept), turns on OpenCode's own OpenTelemetry export, and adds the MCP entry to the project's `opencode.json`. The collector endpoint is set only for the OpenCode process Blop starts.

Undo, from the repository root:

```bash
blop setup opencode --remove && blop agents install-hooks opencode --project my-app --remove --apply && blop agents setup opencode --project my-app --remove && blop setup mcp opencode --scope project --remove
```

**Any agent (MCP)**

```bash
blop setup mcp cursor
```

Clients: `claude`, `codex`, `cursor`, `vscode`, `opencode`, `pi` (needs `pi-mcp-adapter`), `gemini`, `windsurf` and `claude-desktop`. Blop first checks that `blop mcp` starts and answers; if it would not, nothing is written and the command exits 6. Windsurf and Claude Desktop entries are only printed. `--scope local|project|user` picks where the entry goes, `--print` writes nothing, `--force` replaces a different `blop` entry, and a second run changes nothing. Edited files are backed up first (last 5 kept). With no client, it lists agents and stale `blop` entries.

Undo:

```bash
blop setup mcp cursor --remove
```

For hooks in every directory, `blop setup agents` covers every detected agent (`--capture metadata-only` keeps bodies out). For one agent, run `blop agents setup <id>`, preview `blop agents install-hooks <id>`, then repeat with `--apply`. IDs: `claude-code`, `omp`, `pi`, `opencode`, `hermes`, `gemini-cli`, `codex`, `goose`, `amp`, `cursor-agent`, `crush`. Undo with `blop agents install-hooks <id> --scope global --remove --apply && blop agents setup <id> --scope global --remove`.

Restart a running agent to load the hooks; host trust and approval settings always apply. Undo deletes files Blop created and restores those it edited; the collector keeps running until `blop stop`.

To also send an agent's own OpenTelemetry export, `blop agents env <id>` prints the variables, or for Codex the `[otel]` block for `~/.codex/config.toml`. That block sets `metrics_exporter = "none"`, so Codex does not send metrics to OpenAI. It enables nothing by itself.

## What the MCP server gives the agent

`blop mcp` is a local, read-only stdio server. Its tools return status, audits, issues, runs, sessions and [local memory](/guides/local-memory/). It reads the collector of the client's project (`BLOP_PROJECT_DIR`, else `CLAUDE_PROJECT_DIR`, else its working directory); `--url` or `BLOP_MONITOR_URL` pins one. When several collectors run and none matches, it names them instead of guessing.

## What is captured

New bindings capture full exposed content locally: prompts, public replies, tool input, output and errors. Hidden thinking and attachment bytes are never captured. Text parts are capped at 16 KiB, events at 64 KiB, and bodies are kept 30 days. Redaction is best effort. Nothing is uploaded.

Narrow capture for future events:

```bash
blop agents capture-policy set claude-code --project my-app --mode metadata-only
```

| Option | Effect |
| --- | --- |
| `--mode full \| conversation-only \| metadata-only` | All exposed content; prompts and replies only; no bodies |
| `--exclude <class>` | Drop a class such as `prompt` or `tool-output` (repeatable) |
| `--retention-hours <n>` | Body retention, 1 to 720 |
| `--enabled false` | Pause capture without removing setup |

The Inspector's **Capture and privacy** settings edit the same policy. Policy changes and removal never delete retained history; removal restores each file's pre-install bytes and refuses a file edited since. Expired bodies are removed logically, so backups can still hold them.

The collector's routes have no authentication. Keep it on loopback and never expose its port.

## Global and project connection scope

Without `--project`, `blop agents` commands use global scope: one binding for every working directory. `--project <id>` selects project scope, which wins over global capture at its exact root, even when disabled. A drifted project installation fails closed instead of falling back to global.

A hook never fails the agent when the collector is down: events queue locally and drain when it answers.

## Check the agent connection worked

```bash
blop agents doctor claude-code --project my-app
```

Doctor is read-only: it names each blocking problem with a fix and counts accepted events per content class. An installed hook (`native_hooks.installed: "hooks"` in `blop agents status --json`) is configuration, not proof that callbacks arrived: run one real prompt, then check that doctor's counts are above 0.

## Next steps after connecting

- [Investigate](/guides/investigate/): query what the agent and your app recorded.
- [`blop agents` reference](/reference/cli/#blop-agents).