> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getmonocle.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Setup

> Connect monocle to Claude Code, OpenCode, Codex CLI, Gemini CLI, or Pi.

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

```bash theme={"dark"}
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:

```bash theme={"dark"}
monocle register claude --global
```

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

```bash theme={"dark"}
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](/reference/cli#monocle-register) for a full list of flags and config paths per mode.

## Set up each agent

<Tabs>
  <Tab title="Claude Code">
    ### Register via CLI

    ```bash theme={"dark"}
    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`:

    ```bash theme={"dark"}
    monocle register claude --integration-mode skills
    ```

    ### Enable push notifications

    Claude Code supports [MCP channels](https://code.claude.com/docs/en/channels-reference), 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:

    ```bash theme={"dark"}
    claude --dangerously-load-development-channels plugin:monocle@monocle
    ```

    <Note>
      The `--dangerously-load-development-channels` flag is required during the [channels research preview](https://code.claude.com/docs/en/channels-reference).
    </Note>

    <Tip>
      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.
    </Tip>
  </Tab>

  <Tab title="OpenCode">
    ### Register via CLI

    ```bash theme={"dark"}
    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.
  </Tab>

  <Tab title="Codex CLI">
    ### Register via CLI

    ```bash theme={"dark"}
    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.
  </Tab>

  <Tab title="Gemini CLI">
    ### Register via CLI

    ```bash theme={"dark"}
    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.
  </Tab>

  <Tab title="Pi">
    ### Register via CLI

    ```bash theme={"dark"}
    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`:

    ```bash theme={"dark"}
    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.
  </Tab>

  <Tab title="All agents">
    Register monocle for every supported agent at once:

    ```bash theme={"dark"}
    monocle register all
    ```

    Use `--global` to install at the user level:

    ```bash theme={"dark"}
    monocle register all --global
    ```
  </Tab>

  <Tab title="Other agents">
    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:

    ```bash theme={"dark"}
    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](https://github.com/josephschmitt/monocle/releases/latest) and extract the skill files into wherever your agent expects its skills:

    ```bash theme={"dark"}
    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.
  </Tab>
</Tabs>

## Verify the connection

Start monocle in a terminal alongside your agent:

```bash theme={"dark"}
monocle
```

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