Skip to content
Blopblop docs

Connect a coding agent

Connect a coding agent so Blop captures its prompts, tool calls and errors through hooks, and the agent can read issues and audits over MCP.

Agent connection prerequisites

Section titled “Agent connection prerequisites”
  • The Blop CLI on your PATH (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

Section titled “Connect an agent to Blop in one launch”

  1. Change to your repository:

    Terminal window
    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) or the collector cannot start, it prints one warning with the fix and starts the agent without capture.

Terminal window
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:

Terminal window
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

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

Section titled “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. 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

Section titled “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:

Terminal window
blop agents capture-policy set claude-code --project my-app --mode metadata-only
OptionEffect
--mode full | conversation-only | metadata-onlyAll 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 falsePause 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

Section titled “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

Section titled “Check the agent connection worked”
Terminal window
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

Section titled “Next steps after connecting”