Agent Setup - o_(◉) monocle

monocle connects to your agent through one of two integration modes: MCP tools or skills. Run monocle register to configure the connection.

MCP tools mode configures an MCP server that exposes monocle’s review operations as tools the agent can call directly. This is the default for Claude Code. Pi uses this path only when pi-mcp-adapter is already configured, or when you explicitly request --integration-mode mcp.
Skills mode installs skill files — small instruction files that tell the agent which CLI commands to run. This is the default for OpenCode, Codex CLI, and Gemini CLI.

Register monocle with your agent

monocle register          # interactive picker
monocle register claude   # or: opencode, codex, gemini, pi, all

Add --global to install at the user level instead of the current project:

monocle register claude --global

Override the default integration mode with --integration-mode:

monocle register claude --integration-mode skills   # force skills mode
monocle register opencode --integration-mode mcp    # force MCP tools mode
monocle register pi --integration-mode skills       # force Pi skills/prompts mode

See the CLI reference for a full list of flags and config paths per mode.

Set up each agent

Register via CLI

monocle register claude

By default, this configures an MCP server in .mcp.json that exposes monocle’s review tools directly, and installs slash commands in .claude/commands/. Claude Code calls the MCP tools (review_status, get_feedback, send_artifact, add_files) instead of running CLI commands.To use skills mode instead (the previous default), pass --integration-mode skills:

monocle register claude --integration-mode skills

Enable push notifications

Claude Code supports MCP channels, which deliver your review feedback directly into the agent’s context the moment you submit — no polling needed. Start Claude Code with the channel flag to enable this:

claude --dangerously-load-development-channels plugin:monocle@monocle

The --dangerously-load-development-channels flag is required during the channels research preview.

If you start or restart monocle while Claude Code is already running, the MCP channel may need to reconnect. Type /mcp in Claude Code and select monocle to reconnect.

Register via CLI

monocle register opencode

This installs skills into .opencode/skills/. OpenCode uses pull-based feedback — the agent retrieves your reviews by running the /get-feedback skill.

Register via CLI

monocle register codex

This installs skills into .codex/skills/. Codex uses pull-based feedback — the agent retrieves your reviews by running the /get-feedback skill.

Register via CLI

monocle register gemini

This installs skills into .gemini/skills/. Gemini CLI uses pull-based feedback — the agent retrieves your reviews by running the /get-feedback skill.

Register via CLI

monocle register pi

By default, this uses MCP mode only if pi-mcp-adapter is already configured in Pi at the project or user level. In that case, monocle registers itself in .pi/mcp.json and installs prompt templates in .pi/prompts/; project registration can reuse a global adapter without adding a project package. Pi calls monocle through the adapter’s MCP gateway or direct monocle_* tools when available. If the adapter is not already configured, monocle falls back to skills/prompts and does not add the adapter package.Restart Pi or run /reload after registering so the package, MCP config, and prompt templates are loaded.To force CLI-based skills, pass --integration-mode skills:

monocle register pi --integration-mode skills

Skills mode installs SKILL.md files in .pi/skills/ plus the same prompt templates in .pi/prompts/. To add the pinned npm:pi-mcp-adapter@2.9.0 package and use MCP tools explicitly, pass --integration-mode mcp. Pi still uses pull-based feedback; Claude MCP channels are not involved.

monocle register all

Use --global to install at the user level:

monocle register all --global

If your agent isn’t listed above, you can set up monocle manually using either MCP tools or skills.

MCP tools (recommended)

If your agent supports MCP servers via stdio, point it at monocle’s built-in MCP server:

monocle serve-mcp

This exposes the review_status, get_feedback, send_artifact, and add_files tools over stdio. Add this as an MCP server in your agent’s config, the same way you would any other stdio-based MCP server.

Skills

Download the skills.tar.gz archive from the latest release and extract the skill files into wherever your agent expects its skills:

curl -Lo skills.tar.gz https://github.com/josephschmitt/monocle/releases/latest/download/skills.tar.gz
tar xzf skills.tar.gz -C /path/to/your/agent/skills/

The archive contains SKILL.md files that instruct the agent to run monocle review CLI commands for sending artifacts, retrieving feedback, and checking review status.

Verify the connection

Start monocle in a terminal alongside your agent:

monocle

Press I in the TUI to see the socket path and confirm your agent is connected.

​Register monocle with your agent

​Set up each agent

​Register via CLI

​Enable push notifications

​Register via CLI

​Register via CLI

​Register via CLI

​Register via CLI

​MCP tools (recommended)

​Skills

​Verify the connection

Register monocle with your agent

Set up each agent

Register via CLI

Enable push notifications

Register via CLI

Register via CLI

Register via CLI

Register via CLI

MCP tools (recommended)

Skills

Verify the connection