# Agent Integration
Source: https://docs.getmonocle.sh/concepts/agent-integration
How monocle connects to your AI coding agent via MCP tools, skills, or CLI commands.
Monocle integrates with your agent through one of two modes: **MCP tools** or **skills**. Both expose the same operations — the difference is how the agent invokes them.
* **MCP tools mode** runs a built-in MCP server (`monocle serve-mcp`) that exposes review operations as tools. This is the default for Claude Code. Pi reaches the server through `pi-mcp-adapter` when the adapter is already configured, or when you explicitly request MCP mode.
* **Skills mode** installs `SKILL.md` instruction files ([agentskills.io](https://agentskills.io) format) that tell the agent which `monocle review` CLI commands to run. This is the default for OpenCode, Codex CLI, and Gemini CLI.
You can override the default with `--integration-mode` when registering. See [agent setup](/guides/agent-setup) for details.
## Available operations
These operations are available as both MCP tools and skills:
| Operation | MCP tool | Skill | Description |
| ------------------------ | ------------------------------------------------------ | -------------------- | ------------------------------------------------------- |
| Get feedback | `get_feedback` | `/get-feedback` | Retrieve pending review feedback |
| Get feedback (blocking) | `get_feedback` with `wait: true` | `/get-feedback-wait` | Block until the reviewer submits feedback |
| Send artifact | `send_artifact` | `/review-plan` | Submit content (plans, decisions, summaries) for review |
| Send artifact (blocking) | `send_artifact`, then `get_feedback` with `wait: true` | `/review-plan-wait` | Submit content and iterate on feedback until approved |
| Check status | `review_status` | — | Check if feedback is pending or a pause was requested |
| Add files | `add_files` | — | Add files to the current review session |
### Get feedback
Retrieves any feedback you've submitted and delivers it to the agent. If you've submitted multiple reviews since the agent last checked, they're all delivered together in one batch.
With Claude Code and MCP channels, the agent calls this automatically after receiving a push notification. With other agents, feedback is retrieved on demand — either by the agent on its own, or when you ask it to check.
### Get feedback (blocking)
Same as get feedback, but the agent blocks and waits until you submit. Use this when a pause has been requested or when the agent should hold off until you've reviewed its work.
### Send artifact
Tells the agent to send content to monocle for review using `monocle review send-artifact` (skills) or the `send_artifact` tool (MCP). The content appears in your TUI alongside file diffs, and you can leave line-level comments on it.
### Send artifact (blocking)
Same as send artifact, but the agent blocks after submitting and waits for your response. In MCP tools mode, the agent submits with `send_artifact`, then calls `get_feedback` with `wait: true`. If you request changes, the agent updates and resubmits — iterating until you approve (submit with no comments).
This is what enables [review gating](/guides/review-gating): the agent cannot move forward until you sign off.
## Registration
`monocle register` writes the appropriate config for your agent. In MCP tools mode, it configures an MCP server entry and installs slash commands or prompt templates where the agent supports them. In skills mode, it writes skill files to the agent's skill directory.
```bash Claude Code theme={"dark"}
# Default: MCP tools mode — configures .mcp.json and .claude/commands/
monocle register claude
# To use skills mode instead:
monocle register claude --integration-mode skills
```
```bash OpenCode theme={"dark"}
# Default: skills mode — installs to .opencode/skills/
monocle register opencode
```
```bash Codex CLI theme={"dark"}
# Default: skills mode — installs to .codex/skills/
monocle register codex
```
```bash Gemini CLI theme={"dark"}
# Default: skills mode — installs to .gemini/skills/
monocle register gemini
```
```bash Pi theme={"dark"}
# Auto: use existing pi-mcp-adapter when configured, otherwise skills/prompts
monocle register pi
# Force MCP tools mode and add the pinned pi-mcp-adapter package if needed:
monocle register pi --integration-mode mcp
# Force skills/prompts mode:
monocle register pi --integration-mode skills
```
```bash All agents theme={"dark"}
# Register for every supported agent at once
monocle register all
```
Run `monocle register` once per project, or with `--global` to apply across all projects.
## Making operations automatic
Operations are available to your agent, but the agent decides when to use them. If you want the agent to automatically submit plans for review or check for feedback at specific points, add instructions to your agent's project configuration file (`CLAUDE.md`, `AGENTS.md`, etc.):
```markdown theme={"dark"}
## Monocle Integration
When Monocle is running:
- Use the `/review-plan` skill to send content (plans, decisions, summaries) for the reviewer to see
- Use the content's filename as the identifier so updates replace the previous version
- In plan mode, use `/review-plan-wait` instead — it blocks until the reviewer responds.
If they request changes, update and resubmit until approved.
```
You can also invoke `/review-plan` and `/review-plan-wait` yourself at any time by asking your agent to run them.
# Push Notifications
Source: https://docs.getmonocle.sh/concepts/push-notifications
How monocle delivers your review feedback to your AI agent.
Monocle always queues your reviews for reliability. How the agent learns about queued feedback depends on the integration: Claude Code can receive push notifications the moment you submit, while all other agents retrieve feedback on demand.
## Push notifications (Claude Code only)
When you submit a review, monocle sends a push notification through the MCP channel immediately. The notification includes a brief summary — for example, "Your reviewer requested changes — 2 issues, 1 suggestion" — and prompts Claude Code to call `/get-feedback` to retrieve the full review.
This means the agent doesn't need to poll or wait for its next natural checkpoint. Feedback arrives the moment you press `S`.
### Requirements
Push notifications require:
* Claude Code with [MCP channel support](https://code.claude.com/docs/en/channels-reference)
* Monocle registered with Claude Code (`monocle register claude`)
### Starting Claude Code with channels
Launch Claude Code with the MCP channel flag to enable push notifications:
```bash theme={"dark"}
claude --dangerously-load-development-channels plugin:monocle@monocle
```
The `--dangerously-load-development-channels` flag is required during the [channels research preview](https://code.claude.com/docs/en/channels-reference).
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.
### What happens when push fails silently
If Claude Code is running without channels enabled, push notifications fail silently. Your review stays in the queue and the agent will retrieve it the next time it calls `/get-feedback` — nothing is lost.
## Pull-based feedback (all agents)
All agents can retrieve feedback by running `/get-feedback` (via a skill, prompt template, or MCP tool) or `monocle review get-feedback` directly. This works regardless of whether push notifications are enabled.
Key behaviors:
* Multiple reviews accumulate in the queue between fetches. When the agent retrieves feedback, it receives all queued reviews combined in one delivery.
* The agent can call this at any point in its workflow, or you can ask it to check.
* With Claude Code and channels, this call happens automatically after a push notification. Without channels, the agent uses the skill on its own schedule.
You submit → push notification → agent calls `/get-feedback` immediately.
You submit → review queues → agent calls `/get-feedback` when ready.
## The pause flow
The pause flow lets you stop the agent and make it wait for your review before proceeding. Press `P` in the TUI to trigger it.
The agent receives a push notification telling it to pause.
The agent runs `monocle review get-feedback --wait`, which blocks until you submit a review.
Take your time reviewing the current diffs. Add comments, then press `S` to submit.
The `--wait` call unblocks, the agent receives your feedback, and proceeds.
Pause requires MCP channel support and is currently only available with Claude Code. Pressing `P` with other agents has no effect.
This is useful when the agent is moving quickly and you want to ensure it reviews your feedback before moving on to the next task.
# Review Loop
Source: https://docs.getmonocle.sh/concepts/review-loop
Understand how monocle's review loop works between you and your AI agent.
The review loop is the core interaction pattern in monocle: your agent writes code, you review the diffs, leave comments, submit, and the agent addresses your feedback. Then you do it again — iterating until you're satisfied.
## Architecture
Monocle connects to your agent over a Unix socket. In MCP tools mode, a native MCP server sits in between and exposes review tools:
```
Agent <--stdio/MCP--> monocle serve-mcp (MCP server) <---socket---> monocle (TUI)
```
Claude Code can also use MCP channels for push notifications. Pi reaches the same MCP server through `pi-mcp-adapter`; that is pull-based and does not use Claude MCP channels.
For skills-mode agents, the connection goes directly over the socket, and feedback is retrieved on demand via the `/get-feedback` skill or `monocle review get-feedback`.
## How the loop works
Your agent works in its own terminal, making file changes as it goes. Monocle watches the working directory and shows updated diffs as files change.
Navigate the file list in the sidebar with `j`/`k`, select a file, and inspect the diff. Add comments at any point — you don't need to wait for the agent to finish.
Press `c` on a diff line to add a line-level comment. Press `C` to add a file-level comment. Use `v` to enter visual mode and select a range of lines before commenting. Press `Tab` in the comment editor to cycle through comment types.
Press `S` to open the submit modal. Your review is formatted and queued for delivery. The agent picks it up and starts addressing each comment.
After the agent makes changes, the diffs update in your TUI. Review again, leave new comments if needed, and submit. Repeat until you're satisfied.
## Diff viewer modes
Press `t` (or `T` for layout) to cycle between display modes. You can also set your preferred default in [config](/configuration/config-file).
| Mode | Description |
| ----------- | -------------------------------------------------------------------------------------------- |
| **Unified** | Added and removed lines interleaved in a single column. Best for most terminals. |
| **Split** | Side-by-side view with old content on the left and new on the right. Best on wide terminals. |
| **File** | Shows raw file content without diff markers. Useful for reading context. |
Use `w` to toggle line wrapping for wide diffs, and `h`/`l` to scroll horizontally without wrapping.
## Comment types
When you add a comment, press `Tab` in the comment editor to cycle through these types:
| Type | Use for |
| -------------- | --------------------------------------------------- |
| **Issue** | Problems that need to be fixed before you approve |
| **Suggestion** | Improvements that would be nice but aren't blockers |
| **Note** | Observations, context, or questions |
| **Praise** | Things the agent did well |
### Line-level vs file-level comments
* **Line-level** (`c`): Attached to a specific diff line. Press `s` instead to pre-fill a `suggestion` block with the existing code, ready for you to propose an exact edit.
* **Visual selection** (`v`): Enter visual mode to select a range of lines, then press `c` to attach a comment spanning the entire selection.
* **File-level** (`C`): Attached to the file as a whole, not a specific line. Use for high-level feedback about a file's structure or approach.
You can mark a comment as resolved with `x`. Resolved comments are excluded from submitted reviews. To delete a comment entirely, press `d` while on a comment line.
### Comment expansion
Comments expand automatically when you hover over them, showing the full comment text with syntax highlighting. Press `Space` on a comment line to manually toggle it expanded or collapsed. You can disable auto-expansion or adjust the delay in your [config file](/configuration/config-file) with the `comment_expand` and `comment_expand_delay` settings.
## The feedback queue
When you submit a review, monocle doesn't send it directly — it queues it for reliable delivery. This means:
* You can submit a review even if your agent is busy working on something else.
* Multiple reviews can accumulate in the queue. When the agent next retrieves feedback, it receives all queued reviews combined.
* If the agent disconnects and reconnects, queued reviews are still waiting.
How the agent learns about queued feedback depends on your setup. See [Push Notifications](/concepts/push-notifications) for details.
## The submit flow
Press `S` to open the submit modal. From here:
* **Submit**: Formats your comments into a structured review and queues it for delivery. When you submit with **Request Changes**, monocle creates a snapshot so it can track what changed on the next round. See [Review State](/concepts/review-state) for details.
* **Copy to clipboard**: Toggle the checkbox with `Shift+Tab` to also copy the formatted review to your clipboard when submitting.
* **Yank without submitting**: Press `Ctrl+y` in the submit modal to copy the formatted review to your clipboard and close the modal without queuing it.
* **External editor**: Press `Ctrl+g` in the submit modal (or any comment modal) to open the current text in your `$VISUAL` or `$EDITOR`. Edit, save, and quit — the text comes back into monocle.
### Approval
If you submit a review with no comments, monocle treats it as an approval. The agent receives an approval signal and knows it can proceed.
## Pausing the agent
If you want the agent to stop and wait while you finish reviewing, press `P`. The agent receives a pause notification and blocks on `monocle review get-feedback --wait` until you submit your review.
Pause requires MCP channel support and is currently only available with Claude Code.
# Review State
Source: https://docs.getmonocle.sh/concepts/review-state
How monocle tracks what you've reviewed, detects changes between rounds, and helps you focus on what's new.
Review state tracking is **on by default**. If you'd rather see raw git diffs with no reviewed indicators, snapshots, or change detection, set `"review_tracking": false` in your [config file](/configuration/config-file).
When you review code with monocle, you're not just reading diffs — you're building up a picture of the codebase as the agent modifies it. Monocle tracks this picture so that when the agent makes more changes, you can see exactly what's new since you last looked.
## Sessions, reviews, and rounds
A **session** holds all of your review state for a working directory: comments, reviewed marks, plans, and submission history. Sessions persist to disk so your work survives restarts.
A **review** is the full arc from when you start looking at code to when you approve it. Within a review, you go through multiple **rounds** of back-and-forth feedback:
1. You review the diffs and leave comments
2. You submit with **Request Changes** — this creates a snapshot of the current state
3. The agent addresses your feedback and makes more changes
4. You review just the new changes (round 2) and submit again
5. Repeat until you're satisfied, then submit with **Approve**
Each round builds on the last. Monocle remembers what the code looked like when you last reviewed it, so you don't have to re-examine everything from scratch.
## Reviewed state
Every file in the sidebar has a reviewed state: either reviewed (green checkmark) or unreviewed (empty circle). You toggle this with `r`, and filter the sidebar with `/` to show only unreviewed or reviewed files.
There are two layers to reviewed state:
* **Draft** — while you're working through files, pressing `r` is a working indicator. It helps you track your progress during a round. The sidebar filter works with it immediately.
* **Committed** — when you submit a review, monocle captures a snapshot. This snapshot is the "real" reviewed state that drives automatic change detection on the next round.
Until you submit, reviewed marks are ephemeral. They help you work, but they don't affect what happens next round.
## Snapshots and change detection
When you submit a review with **Request Changes**, monocle creates a **snapshot** — a record of every file's content at that moment. On the next round, monocle compares each file against the snapshot:
* **File changed** since the snapshot — automatically marked as unreviewed
* **File unchanged** since the snapshot — stays marked as reviewed
* **New file** not in the snapshot — marked as unreviewed
* **Deleted file** — removed from reviewed state
Content items (plans, artifacts, and other non-file content) are also tracked. If a content item is updated after the snapshot was created, it is automatically marked as unreviewed so you can review the new version.
This happens automatically during file refresh. You don't need to do anything — just open monocle and the sidebar shows you exactly what needs your attention.
Filter to **Unreviewed** with `/` to see only the files that changed since your last review. This is the fastest way to focus on what's new.
### How snapshots are stored
Monocle uses git's object store to efficiently track file state. When a snapshot is created, each file's content is written to git's object store via `git hash-object`, and the resulting SHA is stored in monocle's database. This means:
* Only a 40-character hash is stored per file, not the full content
* Git handles compression and deduplication automatically
* Works with both committed and uncommitted files — the snapshot captures whatever is on disk
### What marks files as reviewed on submit
You can control which files are marked as reviewed when you submit a review with the `mark_reviewed_on_submit` config option:
| Value | Behavior |
| ----------------- | ------------------------------------------------------------------ |
| `"all"` (default) | All files are marked as reviewed. Assumes you've seen everything. |
| `"commented"` | Only files you left comments on are marked as reviewed. |
| `"manual"` | Only files you explicitly toggled with `r` are marked as reviewed. |
## Snapshot lifecycle
Snapshots accumulate across rounds within a review:
* **Request Changes** — creates a new snapshot for the current round
* **Approve** — wipes all snapshots. The review is complete.
* **Change base ref** — wipes all snapshots. You've changed context, so old snapshots are no longer meaningful. Monocle shows a confirmation dialog if you have active snapshots.
Snapshots are preserved when the base ref auto-advances (HEAD moves because the agent made new commits). This is the normal flow — the agent pushes code, and you want to see what changed since your last review.
## Viewing changes since a prior round
Open the ref picker with `b` and you'll see a **Since Review** section listing your prior review rounds:
```
Select Base Ref
Since Review
Round 3 (2h ago)
Round 2 (1d ago)
Working Tree ✓
Recent Commits
abc1234 Fix the widget
def5678 Add new feature
```
Snapshots appear at the top of the picker. Select a round to view only the changes since that review. The status bar updates to show which round you're diffing against. Select **Working Tree** or a specific commit to return to normal git-based diffing.
Snapshots only appear in the ref picker after you've submitted at least one review with **Request Changes**. If you haven't submitted yet, you'll only see commits.
## Walkthrough: a two-round review
Here's what a typical review looks like with review tracking on. Assume
the agent just modified three files: `auth.go`, `router.go`, and
`handlers.go`.
**Round 1 — first look**
You open monocle and the sidebar shows:
```
Files 0 / 3
○ auth.go M
○ router.go M
○ handlers.go M
```
You read each diff. `auth.go` looks good, so you press `r` to mark it
reviewed. You notice a bug in `router.go` and leave a comment. You mark
it reviewed too, so you can track that you've seen it:
```
Files 2 / 3
✓ auth.go M
✓ router.go M 1 comment
○ handlers.go M
```
`handlers.go` has a small nit. You comment and leave it unreviewed —
you'll come back to it after you see the agent's response. You press
`S`, submit with **Request Changes**. Monocle captures a snapshot and
sends your review to the agent.
**Round 2 — focusing on what's new**
The agent fixes the bug in `router.go` and touches up `handlers.go` to
address your nit. The sidebar updates:
```
Files 1 / 3
✓ auth.go M
○ router.go M 1 comment
○ handlers.go M
```
`auth.go` is still marked reviewed because its content didn't change
since the snapshot. `router.go` and `handlers.go` are back to
unreviewed because the agent changed them — exactly the two files that
need your attention this round.
Press `/` to filter to **Unreviewed** and you see only those two files.
You review the fixes, resolve the comments, and submit again — this
time with **Approve**. Monocle clears the snapshot history; the review
is complete.
This is the loop: submit **Request Changes** each round to lock in a
snapshot, let monocle auto-unmark what changed, filter to
**Unreviewed**, and repeat.
## Edge cases
* **Rebases and force-pushes** — snapshots store content hashes, not commit references. They are completely immune to rebases, unlike GitHub's "changes since last review" which breaks on force-push.
* **File renames** — the old path shows as deleted, the new path shows as new. Both are marked as unreviewed so you can review the rename.
* **Binary files** — content hashes detect changes, but monocle shows "binary file changed" instead of a diff.
# Config File
Source: https://docs.getmonocle.sh/configuration/config-file
Customize monocle's layout, diff style, and behavior with a JSON config file.
Monocle loads settings from JSON config files at startup. You can maintain a global config for personal preferences and a project config for repository-specific settings.
Config is read once when the background engine (`monocle serve`) starts, not
each time the TUI launches. Because the engine is long-lived and shared across
TUI sessions, editing a config file and relaunching `monocle` alone will not
pick up the change. To apply config changes, run `monocle stop` and then start
`monocle` again — this restarts the engine and reloads the config.
## File locations
Monocle loads config files in this order, with the project config taking precedence over the global one:
1. **Global:** `~/.config/monocle/config.json` (or `$XDG_CONFIG_HOME/monocle/config.json`)
2. **Project:** `.monocle/config.json` in your working directory
Create either or both files — you only need to include the settings you want to override.
## Example config
```json theme={"dark"}
{
"layout": "auto",
"diff_style": "unified",
"sidebar_style": "flat",
"theme": "dark",
"wrap": false,
"tab_size": 4,
"context_lines": 3,
"ignore_patterns": [],
"keybindings": {},
"mouse": true,
"min_diff_width": 80,
"auto_focus_mode": false,
"comment_expand": true,
"comment_expand_delay": 2000,
"review_tracking": true,
"mark_reviewed_on_submit": "all",
"idle_timeout": "30m",
"review_format": {
"include_snippets": true,
"max_snippet_lines": 10,
"include_summary": true
}
}
```
## Settings
| Setting | Values | Default | Description |
| --------------------------------- | --------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `layout` | `"auto"`, `"side-by-side"`, `"stacked"` | `"auto"` | Pane arrangement (`auto` switches based on terminal width) |
| `diff_style` | `"unified"`, `"split"`, `"file"` | `"unified"` | Diff display mode (`file` shows raw content) |
| `sidebar_style` | `"flat"`, `"tree"` | `"flat"` | File list display mode |
| `theme` | `"dark"`, `"light"` | `"dark"` | Color scheme for the TUI. Use `"light"` if your terminal has a light background. |
| `wrap` | `true`, `false` | `false` | Word-wrap long lines in diffs |
| `tab_size` | integer | `4` | Spaces per tab character |
| `context_lines` | integer | `3` | Unchanged lines shown around diff hunks |
| `ignore_patterns` | string array | `[]` | Glob patterns for files to exclude |
| `min_diff_width` | integer | `80` | Minimum character width for the diff viewer in side-by-side layout |
| `mouse` | `true`, `false` | `true` | Enable mouse interactions (click, scroll, drag) |
| `auto_focus_mode` | `true`, `false` | `false` | Auto-enter focus mode (hide sidebar, enable wrap) when reviewing plans |
| `comment_expand` | `true`, `false` | `true` | Auto-expand comments when the cursor hovers over them |
| `comment_expand_delay` | integer (ms) | `2000` | Delay in milliseconds before a comment auto-expands on hover |
| `review_tracking` | `true`, `false` | `true` | Enable review state tracking, snapshots, and change detection between rounds. Set to `false` for raw diffs with no reviewed indicators. |
| `mark_reviewed_on_submit` | `"all"`, `"commented"`, `"manual"` | `"all"` | Which files to mark as reviewed when submitting (requires `review_tracking`, see [Review State](/concepts/review-state)) |
| `idle_timeout` | duration string (e.g. `"30m"`, `"1h"`) | `"30m"` | How long `monocle serve` stays alive after the last client disconnects (plus a 60s grace window). Overridden by the `--idle-timeout` flag. Use `"0s"` or a negative value to disable. |
| `keybindings` | object | `{}` | Custom key overrides (see [Keybindings](/configuration/keybindings)) |
| `review_format.include_snippets` | `true`, `false` | `true` | Include code snippets in formatted reviews |
| `review_format.max_snippet_lines` | integer | `10` | Truncate snippets longer than this |
| `review_format.include_summary` | `true`, `false` | `true` | Include comment count summary in formatted reviews |
Toggle keybindings (`T`, `t`, `w`, `f`) change settings for the current session only. Edit the config file to persist your preferences.
# Keybindings
Source: https://docs.getmonocle.sh/configuration/keybindings
Override any monocle keybinding with your preferred keys.
Monocle lets you remap any action to a key of your choice. Add a `keybindings` object to your [config file](/configuration/config-file) and map action names to key strings.
## How to configure
Add entries to the `keybindings` object in your config file:
```json theme={"dark"}
{
"keybindings": {
"quit": "Q",
"submit": "ctrl+s",
"scroll_down": "ctrl+j"
}
}
```
Each key in the object is an action name; the value is the key string to bind. Only include the actions you want to override — unspecified actions keep their defaults.
Press `?` in monocle to see the current effective keybindings, including any overrides you've applied.
## Available actions
| Action | Default key | Description |
| ------------------- | ----------- | ------------------------------------------------------------------- |
| `up` | `k` | Move cursor up |
| `down` | `j` | Move cursor down |
| `top` | `g` | Jump to top |
| `bottom` | `G` | Jump to bottom |
| `half_up` | `ctrl+u` | Scroll up half a page |
| `half_down` | `ctrl+d` | Scroll down half a page |
| `prev_file` | `[` | Go to previous file |
| `next_file` | `]` | Go to next file |
| `select` | `enter` | Focus diff pane / toggle directory |
| `focus_swap` | `tab` | Switch pane focus |
| `toggle_sidebar` | `\` | Toggle sidebar visibility |
| `scroll_down` | `J` | Scroll diff down |
| `scroll_up` | `K` | Scroll diff up |
| `scroll_left` | `H` | Scroll diff left |
| `scroll_right` | `L` | Scroll diff right |
| `scroll_home` | `0` | Scroll to column 0 |
| `scroll_first_char` | `^` | Scroll to first non-space character |
| `scroll_end` | `$` | Scroll to end of line |
| `wrap` | `w` | Toggle line wrapping |
| `toggle_diff` | `t` | Cycle diff style (unified / split / file) |
| `tree_mode` | `f` | Toggle flat / tree view |
| `collapse_all` | `z` | Collapse all tree nodes |
| `expand_all` | `e` | Expand all tree nodes |
| `prev_section` | `{` | Go to previous sidebar section |
| `next_section` | `}` | Go to next sidebar section |
| `filter_reviewed` | `/` | Cycle sidebar filter (all → unreviewed → reviewed) |
| `comment` | `c` | Add comment at cursor |
| `file_comment` | `C` | Add file-level comment |
| `suggest` | `s` | Suggest edit at cursor |
| `visual` | `v` | Start visual (multi-line) selection |
| `reviewed` | `r` | Toggle file reviewed |
| `submit` | `S` | Submit review |
| `pause` | `P` | Pause the agent |
| `clear_review` | `D` | Clear all comments, plans, and reviewed states |
| `dismiss_artifact` | `x` | Dismiss the focused artifact from the sidebar (confirm required) |
| `dismiss_outdated` | — | Dismiss outdated comments |
| `toggle_focus_mode` | `F` | Toggle focus mode (hide sidebar, enable wrap) |
| `open_in_editor` | `ctrl+g` | Open current text in `$VISUAL`/`$EDITOR` |
| `base_ref` | `b` | Change base ref |
| `artifact_versions` | `B` | Browse artifact version history and diff against a previous version |
| `cycle_layout` | `T` | Cycle layout (auto / side-by-side / stacked) |
| `refresh` | `R` | Force reload files |
| `help` | `?` | Show keybindings overlay |
| `quit` | `q` | Quit monocle |
| `command_mode` | `:` | Enter command mode |
| `wizard_advance` | `enter` | Advance to the next step in the register wizard |
| `wizard_back` | `shift+tab` | Go back to the previous step in the register wizard |
| `wizard_toggle` | `space` | Toggle the current option in the register wizard |
Modal keys — Enter, Esc, and Tab inside overlays — are not configurable.
# Agent Setup
Source: https://docs.getmonocle.sh/guides/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
### 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
```
The `--dangerously-load-development-channels` flag is required during the [channels research preview](https://code.claude.com/docs/en/channels-reference).
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
```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.
### 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.
### 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.
### 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.
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
```
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.
## 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.
# Plan Review
Source: https://docs.getmonocle.sh/guides/plan-review
Review your agent's plans and architecture decisions before it writes code.
monocle isn't limited to reviewing file changes. Your agent can submit plans, architecture decisions, summaries, and other content for you to review before writing any code. These appear in the sidebar alongside your file diffs, and you leave comments on them the same way.
## How plan review works
Your agent submits content using `monocle review send-artifact`. The plan appears in the sidebar — select it to read it in the diff pane. Leave line-level comments, then submit your review. The agent receives your feedback and can revise before proceeding.
When a plan is updated, monocle shows a diff between the old and new versions so you can see exactly what changed.
Plans render with styled markdown: headings, bold, italic, lists, and code blocks all display properly.
## Version history
Monocle keeps track of every version of a plan or artifact. Press `B` (or run `:base-artifact-version`) to browse the version history and select an older version to diff against the current one. This is useful for seeing how a plan has evolved across multiple review rounds.
## Focus mode
Press `F` to toggle focus mode. This hides the sidebar and enables line wrapping — useful for reading long plans without distraction. Press `F` again to return to the normal layout.
You can also set `"auto_focus_mode": true` in your config file to enter focus mode automatically whenever you open a plan.
## Sending a plan manually
Use the `/review-plan` skill to instruct your agent to find its active plan file and submit it to monocle:
```
/review-plan
```
If you want to block the agent until you respond, use `/review-plan-wait` instead:
```
/review-plan-wait
```
With `/review-plan-wait`, the agent submits the plan and then waits. Once you leave comments (or none — an empty review counts as approval) and submit, the agent continues. If you request changes, the agent updates the plan and resubmits — this loop repeats until you approve.
## Automatic plan review
By default, monocle's skills are available to your agent but the agent decides on its own when to use them. To make plan review automatic, add instructions to your agent's project configuration file (`CLAUDE.md`, `AGENTS.md`, etc.):
```markdown theme={"dark"}
## Monocle Integration
When Monocle is running:
- Use the `/review-plan` skill to send content (plans, decisions, summaries) for the reviewer to see
- Use the content's filename as the identifier so updates replace the previous version
- In plan mode, use `/review-plan-wait` instead — it blocks until the reviewer responds. If they request changes, update and resubmit until approved.
```
With these instructions in place, the agent will submit its plan each time it starts a new task.
You can also trigger `/review-plan` and `/review-plan-wait` manually at any time, even if the agent hasn't added them to its workflow automatically.
# Review Gating
Source: https://docs.getmonocle.sh/guides/review-gating
Block your agent until you approve its plan or current work.
Review gating lets you pause your agent's progress until you've had a chance to review. monocle provides three mechanisms: plan gating via hooks or skills, a per-turn review gate that blocks after file edits, and manual pause flow.
## Plan gating with `/review-plan-wait`
The `/review-plan-wait` skill submits a plan to your TUI and blocks the agent until you respond.
Your agent runs `/review-plan-wait`, which calls `monocle review send-artifact --wait` under the hood. The plan appears in the monocle sidebar.
Read the plan, leave any line-level comments (issues, suggestions, notes), and press `S` to submit your review. An empty review with no comments counts as an approval.
If you approve, the agent unblocks and continues. If you request changes, the agent updates the plan and resubmits — the loop repeats until you're satisfied.
This is content-level gating: you're reviewing a specific piece of content (the plan) before the agent acts on it.
## Pause flow with `P`
Pause flow lets you stop the agent at any point during a session — not just at a plan submission.
Press `P` in the monocle TUI to send a pause notification. The agent receives it, runs `monocle review get-feedback --wait`, and blocks until you submit your review.
Use this when:
* The agent is mid-task and you want to catch up on its current diffs before it continues
* You want to redirect the agent before it moves to the next step
* You need the agent to stop while you review something it's already written
Once you've reviewed and pressed `S` to submit, the agent unblocks and receives your feedback.
Pause flow requires MCP channel support and is currently only available with Claude Code. Other agents (OpenCode, Codex CLI, Gemini CLI, Pi) do not support the push notification needed to trigger the pause.
## Turn-end review gate (Claude Code hooks)
When you register Claude Code with the review-gate hooks enabled (the default), monocle automatically blocks the agent at the end of any turn that edited files. You don't need to press anything — the gate triggers whenever the agent's turn included write-tool calls (Edit, Write, NotebookEdit, MultiEdit).
Each time a write-tool fires, the `PostToolUse` hook marks the session as having unreviewed changes.
The `Stop` hook fires and checks for unreviewed activity. If write-tools fired during the turn, the hook blocks and waits for your review.
Open monocle and review the diffs. Press `S` to submit. If you approve, the agent's next turn starts. If you request changes, the feedback is sent back and the agent continues working to address it.
If no file edits happened during the turn (for example, a pure-chat response), the hook exits immediately and the turn ends normally.
To opt out of the turn-end review gate, pass `--no-review-gate` when registering or uncheck the option in the TUI wizard. See the [CLI reference](/reference/cli#monocle-register) for details.
Hooks don't fire when Claude is launched with `--dangerously-load-development-channels`. If you rely on MCP channels for push notifications, the hook toggles are no-ops at runtime.
## Choosing the right mechanism
| | Plan gating | Turn-end gate | Pause flow |
| -------------------- | ------------------------------------------------------------ | ------------------------------------------------------------- | ----------------------------------------------- |
| **What it gates** | A specific plan or artifact | Every turn that edits files | The agent's entire session |
| **When it triggers** | Agent calls `/review-plan-wait` or `ExitPlanMode` hook fires | Automatically at turn-end | You press `P` in the TUI |
| **Agent support** | All agents (skills/prompts); Claude Code (hooks) | Claude Code only | Claude Code only |
| **Use when** | You want to review the plan before the agent writes code | You want automatic review checkpoints after every code change | You want to pause everything while you catch up |
# Sessions
Source: https://docs.getmonocle.sh/guides/sessions
Manage review sessions, track files, and persist your work across restarts.
A monocle session holds your comments, plans, and reviewed states for a given working directory. Sessions are stored on disk, so your work survives restarts.
## Starting a session
```bash theme={"dark"}
monocle # start a new session
monocle --continue # resume the most recent session
monocle --resume # open a picker to choose a previous session
monocle --session # resume a specific session by ID
```
## Adding files to review
By default, monocle reviews the git diff in your working directory. To include files outside the diff — or files from other paths — you can add them explicitly.
**At startup**, use `--additional-path` (repeatable):
```bash theme={"dark"}
monocle --additional-path ./docs --additional-path ./scripts
```
**While running**, use the agent-facing command:
```bash theme={"dark"}
monocle review add-files
```
Your agent can also call this via a skill to add files mid-session.
## Tracking review progress
Mark a file as reviewed by pressing `r` when it's selected. monocle automatically advances to the next unreviewed file.
Filter the sidebar with `/` to cycle through views:
* **All** — every file in the session
* **Unreviewed** — only files you haven't marked reviewed
* **Reviewed** — only files you've already reviewed
To mark every file at once, use the command palette:
* `:mark-all-reviewed` — mark all files as reviewed
* `:mark-all-unreviewed` — mark all files as unreviewed
When you submit a review with **Request Changes**, monocle creates a snapshot of all file states. On the next round, files that changed since the snapshot are automatically marked as unreviewed, so you can filter to just what's new. See [Review State](/concepts/review-state) for the full details on how snapshots, rounds, and change detection work.
## Submission history
To see past review submissions for the current session, run:
```
:history
```
This opens a list of previous submissions with their comments and timestamps.
## Clearing a review
To remove all comments, plans, and reviewed states from the current session, press `D` or run:
```
:clear
```
This is useful when you want to start fresh after a major round of changes.
## Connection info and troubleshooting
Press `I` in the TUI to see the current socket path and subscriber count — useful for confirming your agent is connected.
If monocle and your agent are running in different working directories, auto-pairing may fail. Override the socket path manually:
**Start monocle with a specific socket:**
```bash theme={"dark"}
monocle --socket /tmp/monocle-abc123.sock
```
**Point agent commands at the same socket:**
```bash theme={"dark"}
MONOCLE_SOCKET=/tmp/monocle-abc123.sock monocle review status
```
For Claude Code's MCP channel, set `MONOCLE_SOCKET` in the `env` section of your `.mcp.json`.
# Installation
Source: https://docs.getmonocle.sh/installation
Install monocle on macOS or Linux.
## Requirements
Before installing monocle, make sure you have:
* A coding agent: [Claude Code](https://claude.com/claude-code), [OpenCode](https://opencode.ai), [Codex CLI](https://github.com/openai/codex), [Gemini CLI](https://github.com/google/gemini-cli), or [Pi](https://pi.dev)
* A terminal with 256-color or true color support
* A [Nerd Font](https://www.nerdfonts.com/) for file icons (optional but recommended)
## Homebrew (recommended)
The simplest way to install monocle on macOS or Linux:
```bash theme={"dark"}
brew install --cask josephschmitt/tap/monocle
```
monocle is distributed as a Homebrew **cask**, not a formula — note the
`--cask` flag.
### Upgrading from a formula install
Earlier releases shipped monocle as a Homebrew **formula**
(`brew install josephschmitt/tap/monocle`). It's now a **cask**. If you
installed the old formula, uninstall it before installing the cask —
otherwise Homebrew reports a conflict between the two:
```bash theme={"dark"}
brew uninstall monocle # remove the old formula
brew install --cask josephschmitt/tap/monocle
```
Homebrew **formulae** are intended to build software from source (or install
official precompiled "bottles" from homebrew-core). monocle's old formula did
neither — it just downloaded the prebuilt release binary and dropped it in
`bin`. Homebrew's `brew audit` rules increasingly discourage that pattern for
third-party taps, and [GoReleaser deprecated formula generation for
prebuilt binaries in v2.10](https://goreleaser.com/deprecations#brews) in
favor of **casks**, which are the modern home for any prebuilt artifact you
download rather than compile — including CLI tools. Switching keeps monocle's
release tooling on a supported path. (Because the release binaries aren't
code-signed/notarized, the cask also strips the macOS quarantine attribute on
install so Gatekeeper doesn't block the binary.)
## Pre-built binaries
Download and install a pre-built binary for your platform from [GitHub Releases](https://github.com/josephschmitt/monocle/releases/latest).
```bash macOS (Apple Silicon) theme={"dark"}
curl -Lo monocle.tar.gz https://github.com/josephschmitt/monocle/releases/latest/download/monocle_darwin_arm64.tar.gz
tar xzf monocle.tar.gz
sudo mv monocle /usr/local/bin/
```
```bash macOS (Intel) theme={"dark"}
curl -Lo monocle.tar.gz https://github.com/josephschmitt/monocle/releases/latest/download/monocle_darwin_amd64.tar.gz
tar xzf monocle.tar.gz
sudo mv monocle /usr/local/bin/
```
```bash Linux (x86_64) theme={"dark"}
curl -Lo monocle.tar.gz https://github.com/josephschmitt/monocle/releases/latest/download/monocle_linux_amd64.tar.gz
tar xzf monocle.tar.gz
sudo mv monocle /usr/local/bin/
```
```bash Linux (ARM64) theme={"dark"}
curl -Lo monocle.tar.gz https://github.com/josephschmitt/monocle/releases/latest/download/monocle_linux_arm64.tar.gz
tar xzf monocle.tar.gz
sudo mv monocle /usr/local/bin/
```
## Verify the installation
After installing, confirm monocle is available:
```bash theme={"dark"}
monocle --version
```
## Uninstall
To remove monocle and its agent registrations:
```bash theme={"dark"}
monocle unregister all
brew uninstall --cask monocle
```
If you installed from source, run `make uninstall` from the repo directory.
## Next steps
Once monocle is installed, follow the [quick start guide](/quickstart) to register it with your agent and begin reviewing code.
# Introduction
Source: https://docs.getmonocle.sh/introduction
monocle is a terminal-based code review companion for AI coding agents.
monocle is a TUI (terminal UI) that runs alongside your AI coding agent. As the agent writes code, you review diffs in real time, leave line-level comments, and submit structured feedback in one batch. The agent receives your review and starts fixing things immediately — just like a pull request review, but live.
## The problem
Without a tool like monocle, reviewing agent-written code means rubber-stamping diffs you didn't read, copy-pasting feedback into a chat window, or just hoping the agent got it right. There's no way to say "fix these three issues and show me again."
monocle gives you a proper review loop without slowing the agent down. It doesn't gate each file change behind an approval — your agent keeps working while you review at your own pace. When you're ready, leave line-level comments and submit. You see the updated diffs, review again, and iterate.
## Supported agents
monocle works with any coding agent that supports [agent skills](https://agentskills.io), MCP tools, or can call CLI commands:
* [Claude Code](https://claude.com/claude-code)
* [OpenCode](https://opencode.ai)
* [Codex CLI](https://github.com/openai/codex)
* [Gemini CLI](https://github.com/google/gemini-cli)
* [Pi](https://pi.dev)
## Key capabilities
Watch diffs appear as your agent writes code. Unified and split views with syntax highlighting and intra-line diffs.
Tag feedback as issues, suggestions, notes, or praise — at the line or file level. Propose exact code changes with suggestion blocks.
Submit all comments in one batch. Your agent receives the formatted review immediately and starts addressing your feedback.
Review your agent's plans and architecture decisions before it writes code. Browse version history to see how plans evolved.
With Claude Code and MCP channels, feedback is pushed directly into the agent's context the moment you submit.
Block the agent until you approve submitted content using the `/review-plan-wait` skill.
## How it works
1. Your agent writes code — monocle shows you the diffs in real time.
2. You navigate with `j`/`k`, add comments with `c`, and submit with `S`.
3. monocle queues your review for delivery.
4. The agent picks up your feedback — immediately via push notification (Claude Code with MCP channels) or on the next poll — and starts making fixes.
5. You see the updated diffs, review again, and iterate.
## Next steps
Install monocle via Homebrew or pre-built binaries.
Register monocle with your agent and start your first review session.
# Quick Start
Source: https://docs.getmonocle.sh/quickstart
Get monocle running alongside your AI coding agent in minutes.
Follow the [installation guide](/installation) to install monocle via Homebrew or a pre-built binary.
Run `monocle register` from your project directory to configure MCP tools or skills for your agent:
```bash theme={"dark"}
monocle register # interactive picker
monocle register claude # or: opencode, codex, gemini, pi, all
```
The interactive picker lets you select which agents to register. Pass a named agent — `claude`, `opencode`, `codex`, `gemini`, `pi`, or `all` — to skip the picker. Use `--global` to write to your user-level config directory instead of the current project.
Claude Code defaults to MCP tools. Pi uses MCP tools when `pi-mcp-adapter` is already configured; otherwise it falls back to skills plus prompt templates and does not add the adapter package. OpenCode, Codex CLI, and Gemini CLI default to skills. If Pi is already running, restart it or run `/reload` after registering.
| Agent | Skills/prompts | MCP/prompts config |
| ----------- | ---------------------------------------------------- | --------------------------------------------------- |
| Claude Code | `.claude/skills/` when forced to skills | `.mcp.json` |
| OpenCode | `.opencode/skills/` | `opencode.json` when forced to MCP |
| Codex CLI | `.codex/skills/` | `.codex/config.toml` when forced to MCP |
| Gemini CLI | `.gemini/skills/` | `.gemini/settings.json` when forced to MCP |
| Pi | `.pi/skills/` + `.pi/prompts/` when forced to skills | `.pi/settings.json`, `.pi/mcp.json`, `.pi/prompts/` |
Open a separate terminal in your project directory and run:
```bash theme={"dark"}
monocle
```
Keep this terminal open alongside the terminal where your agent is running. monocle connects to your agent automatically using Unix sockets.
As your agent writes code, diffs appear in the monocle TUI. Use the following keys to review:
* `j` / `k` — move up and down through the file list and diff
* `c` — add a comment at the cursor (tag it as an issue, suggestion, note, or praise)
* `v` — start a visual selection for multi-line comments
* `S` — submit your review
When you submit, monocle formats your comments and queues the review for delivery. The agent receives your feedback and starts addressing it. You see the updated diffs, review again, and iterate.
Press `?` at any time to see the full list of keybindings.
By default, your agent retrieves feedback by running `/get-feedback` on its own. With Claude Code and MCP channels, monocle can push feedback directly into the agent's context the moment you submit.
To enable push notifications, start Claude Code with the channel flag:
```bash theme={"dark"}
claude --dangerously-load-development-channels plugin:monocle@monocle
```
The `--dangerously-load-development-channels` flag is required because MCP channel support is currently in a research preview. See the [Claude Code channels reference](https://code.claude.com/docs/en/channels-reference) for details.
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.
## What happens when you submit
When you press `S`:
1. monocle formats your comments into a structured review and queues it for delivery.
2. **Claude Code with MCP channels** — a push notification prompts the agent to retrieve your feedback immediately.
3. **Other agents** — the review waits in the queue until the agent runs `/get-feedback` or calls `monocle review get-feedback`. Multiple reviews accumulate and are delivered together.
4. If there are no comments, the review is treated as an approval.
## Pause the agent
If you want the agent to stop and wait while you review, press `P`. The agent receives a pause notification and blocks until you submit your review.
Pause requires MCP channel support and is currently available for Claude Code only.
# Agent Commands
Source: https://docs.getmonocle.sh/reference/agent-commands
CLI commands for agents to interact with a running monocle session.
These commands are used by agents — via installed skills, MCP tools, or directly from the command line — to communicate with a running monocle session.
When registered in **MCP tools mode**, agents call these operations as MCP tools (`review_status`, `get_feedback`, `send_artifact`, `add_files`) instead of CLI commands. The behavior is identical — the MCP server connects to the same Unix socket internally.
When registered in **skills mode**, agents invoke the corresponding CLI commands below.
When the agent's working directory differs from monocle's, use `--workdir` (`-C`) to point commands at the correct repository. Alternatively, set `MONOCLE_SOCKET` or `MONOCLE_WORKDIR` to achieve the same effect via environment variables. Without one of these, commands look for a socket based on the current directory and may not find a running session. Press `I` in the monocle TUI to see the active socket path.
***
## `monocle review status`
Check the current review status of the running monocle session.
```bash theme={"dark"}
monocle review status [--json] [--workdir PATH] [--socket PATH]
```
### Flags
| Flag | Short | Description |
| ---------------- | ----- | ------------------------------------------------------------------ |
| `--json` | | Output the result as structured JSON instead of plain text. |
| `--workdir PATH` | `-C` | Override the working directory. Also reads from `MONOCLE_WORKDIR`. |
| `--socket PATH` | | Override the Unix socket path. Also reads from `MONOCLE_SOCKET`. |
### Output
Without `--json`, prints a status string or summary. The status reflects whether feedback is pending, a pause has been requested, or the session is idle.
### MCP tool equivalent
In MCP tools mode, call the `review_status` tool with no parameters.
***
## `monocle review get-feedback`
Retrieve pending review feedback from the queue.
```bash theme={"dark"}
monocle review get-feedback [--wait] [--json] [--workdir PATH] [--socket PATH]
```
When the reviewer submits a review, it is placed in a queue. Multiple queued reviews are combined and delivered together as a single response.
Without `--wait`, the command returns immediately. If no feedback is pending it prints `No feedback pending.` and exits.
### Flags
| Flag | Short | Description |
| ---------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `--wait` | | Block until feedback is available. The command does not return until the reviewer submits a review. Used by the `/review-plan-wait` skill. |
| `--json` | | Output the result as structured JSON. |
| `--workdir PATH` | `-C` | Override the working directory. Also reads from `MONOCLE_WORKDIR`. |
| `--socket PATH` | | Override the Unix socket path. Also reads from `MONOCLE_SOCKET`. |
### MCP tool equivalent
In MCP tools mode, call the `get_feedback` tool:
| Parameter | Type | Required | Description |
| --------- | ------- | -------- | ------------------------------------------------ |
| `wait` | boolean | No | When `true`, blocks until feedback is available. |
***
## `monocle review send-artifact`
Send content to the reviewer — a plan, architecture document, summary, or any other text — so it appears in the monocle sidebar alongside file diffs.
```bash theme={"dark"}
monocle review send-artifact --title TEXT [--file PATH] [--id ID] [--type EXT] [--wait] [--json] [--workdir PATH] [--socket PATH]
```
If you run the command again with the same `--id`, monocle updates the existing entry and shows a diff between the old and new versions.
When `--file` is not provided, the command reads content from stdin.
### Flags
| Flag | Short | Description |
| ---------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--title TEXT` | | **(Required)** Title displayed in the monocle sidebar. |
| `--file PATH` | | Path to the file to submit. When omitted, reads from stdin. |
| `--id ID` | | Identifier for the artifact. Use the same ID on subsequent calls to update the content in place. Defaults to the filename when `--file` is used. |
| `--type EXT` | | File extension used for syntax highlighting (e.g. `md`, `go`, `py`, `ts`). |
| `--wait` | | Block until the reviewer responds with feedback. Used by the `/review-plan-wait` skill. |
| `--json` | | Output the result as structured JSON. |
| `--workdir PATH` | `-C` | Override the working directory. Also reads from `MONOCLE_WORKDIR`. |
| `--socket PATH` | | Override the Unix socket path. Also reads from `MONOCLE_SOCKET`. |
### Reading from stdin
```bash theme={"dark"}
echo "## Plan\n- Step 1\n- Step 2" | monocle review send-artifact --title "My plan" --type md
```
### Reading from a file
```bash theme={"dark"}
monocle review send-artifact --title "Architecture" --file docs/architecture.md --id architecture.md
```
### MCP tool equivalent
When using MCP tools mode, the `send_artifact` tool accepts these parameters:
| Parameter | Type | Required | Description |
| -------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | string | No | Identifier for the artifact. Use the same ID on subsequent calls to update the content in place. Defaults to the filename when `file_path` is provided. |
| `title` | string | Yes | Title displayed in the monocle sidebar. |
| `content` | string | No | The artifact content. Either `content` or `file_path` must be provided. |
| `file_path` | string | No | Absolute path to a file to read as the artifact content. If `id` is empty, defaults to the filename. |
| `content_type` | string | No | File extension for syntax highlighting (e.g. `md`, `go`, `py`). |
***
## `monocle review add-files`
Add one or more files or directories to the current review session so they appear in the monocle diff viewer.
```bash theme={"dark"}
monocle review add-files [--json] [--workdir PATH] [--socket PATH]
```
### Arguments
| Argument | Description |
| -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `paths` | **(Required)** One or more file or directory paths to add. Paths are resolved to absolute paths before being sent to monocle. |
### Flags
| Flag | Short | Description |
| ---------------- | ----- | ------------------------------------------------------------------ |
| `--json` | | Output the result as structured JSON. |
| `--workdir PATH` | `-C` | Override the working directory. Also reads from `MONOCLE_WORKDIR`. |
| `--socket PATH` | | Override the Unix socket path. Also reads from `MONOCLE_SOCKET`. |
### MCP tool equivalent
In MCP tools mode, call the `add_files` tool:
| Parameter | Type | Required | Description |
| --------- | ------------ | -------- | ---------------------------------------------- |
| `paths` | string array | Yes | File or directory paths to add to the session. |
### Example
```bash theme={"dark"}
monocle review add-files src/feature.go tests/
```
# CLI Reference
Source: https://docs.getmonocle.sh/reference/cli
Complete reference for all monocle command-line commands.
## `monocle`
Start a review session in the current directory.
```bash theme={"dark"}
monocle [flags]
```
Monocle detects the Git repository root from the current working directory and opens the TUI. By default it starts a new session; use the session flags below to resume a previous one.
### Flags
| Flag | Short | Description |
| ------------------------ | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--workdir PATH` | `-C` | Override the working directory. Monocle pairs with the repository at this path instead of the current directory. Also reads from the `MONOCLE_WORKDIR` environment variable. |
| `--socket PATH` | | Override the Unix socket path. Also reads from the `MONOCLE_SOCKET` environment variable. |
| `--additional-path PATH` | `-a` | Add an extra file or directory path to include in the review. Repeatable. |
| `--continue` | `-c` | Resume the most recent session for this repository. |
| `--resume` | `-r` | Show an interactive picker to resume a previous session. |
| `--session ID` | `-s` | Resume a specific session by its ID. |
| `--version` | | Print the monocle version and exit. |
### Session flags
`--continue`, `--resume`, and `--session` are mutually exclusive — only one may be used at a time.
***
## `monocle register`
Register monocle with an agent. Depending on the integration mode, this either configures an MCP server with tools or installs skill files into the agent's skill directory.
```bash theme={"dark"}
monocle register [agent] [--global] [--integration-mode MODE] [--no-plan-hook] [--no-review-gate] [--no-tui]
```
### Arguments
| Argument | Description |
| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agent` | The agent to register. One of `claude`, `opencode`, `codex`, `gemini`, `pi`, or `all`. If omitted, an interactive TUI wizard walks you through agent selection, scope, and (for Claude Code) the hook-group toggles. Use `--integration-mode` to override the selected agents' default mode. |
### Flags
| Flag | Description |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `--global` | Write configuration to the user-level config directory instead of the current project directory. |
| `--integration-mode MODE` | Override the default integration mode. One of `auto`, `mcp`, or `skills`. Defaults to `auto`. |
| `--no-plan-hook` | Skip installation of the Claude Code plan-mode hooks (`PreToolUse` + `PermissionRequest` on `ExitPlanMode`). |
| `--no-review-gate` | Skip installation of the Claude Code turn-end review-gate hooks (`PostToolUse` on write-tools + `Stop`). |
| `--no-tui` | Skip the interactive wizard and run headlessly. Combined with an empty `agent` argument, registers every supported agent with defaults. |
### Plan-mode hooks (Claude Code)
When registering Claude Code, monocle adds up to four hook entries to `.claude/settings.json`:
| Hook event | Matcher | Command | Timeout | Purpose |
| ------------------- | -------------------------------------- | -------------------------------------------- | ------- | ------------------------------------------------------------------------------------------- |
| `PreToolUse` | `ExitPlanMode` | `monocle hooks enter-plan --agent claude` | 5s | Inject review context before Claude drafts its plan. |
| `PermissionRequest` | `ExitPlanMode` | `monocle hooks exit-plan --agent claude` | 3600s | Route the plan through the Monocle reviewer; convert approve/request-changes to allow/deny. |
| `PostToolUse` | `Edit\|Write\|NotebookEdit\|MultiEdit` | `monocle hooks mark-activity --agent claude` | 5s | Mark the session as having unreviewed changes. |
| `Stop` | — | `monocle hooks on-stop --agent claude` | 3600s | Block turn-end on reviewer approval when the turn included file edits. |
The first two form the plan-review flow; opt out with `--no-plan-hook`. The last two form the per-turn review gate; opt out with `--no-review-gate`. Each subset can be toggled independently in the register wizard. If Monocle isn't running, every hook exits silently so Claude's default behavior kicks in — the hooks never hard-block the agent.
The `exit-plan` and `on-stop` hooks block on the reviewer, but the engine bounds that wait so it fails fast (within \~10s) when no reviewer is actively engaged — only blocking longer when you've explicitly requested a pause. The `3600s` settings.json timeout is just a backstop. This prevents the agent from appearing hung between turns when Monocle's engine is still running but you've stepped away.
### What the hooks do
* **Plan-mode hooks** route `ExitPlanMode` through Monocle so any plan Claude produces needs your sign-off before it runs.
* **Turn-end review gate** forcibly pauses Claude at the end of any turn that edited files, and waits for you to submit a review before the next turn starts.
Heads up: hooks don't fire when Claude is launched with `--dangerously-load-development-channels` (the flag needed for MCP channel push notifications). If you rely on channels, the hook toggles are no-ops at runtime.
### Integration modes
| Mode | Description |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `auto` | Uses the recommended default for each agent. Claude Code uses `mcp`; Pi uses `mcp` only when `pi-mcp-adapter` is already configured and otherwise uses `skills`; OpenCode, Codex CLI, and Gemini CLI use `skills`. |
| `mcp` | Configures an MCP server that exposes monocle's review tools. Pi uses `pi-mcp-adapter` and prompt templates for this path. |
| `skills` | Installs skill files that wrap monocle CLI commands. For Pi, also installs prompt templates. For Claude Code, also configures MCP channels for push notifications. |
### Agent config paths
The files written by `register` depend on the integration mode:
**MCP tools mode** (default for Claude Code; default for Pi only when `pi-mcp-adapter` is already configured)
| Agent | MCP config | Commands/prompts |
| ----------- | ------------------------------------ | --------------------- |
| Claude Code | `.mcp.json` | `.claude/commands/` |
| OpenCode | `opencode.json` | `.opencode/commands/` |
| Codex CLI | `.codex/config.toml` | — |
| Gemini CLI | `.gemini/settings.json` | `.gemini/commands/` |
| Pi | `.pi/settings.json` + `.pi/mcp.json` | `.pi/prompts/` |
**Skills mode** (default for OpenCode, Codex CLI, Gemini CLI)
| Agent | Skills directory | MCP config / prompts |
| ----------- | ------------------- | -------------------- |
| Claude Code | `.claude/skills/` | `.mcp.json` |
| OpenCode | `.opencode/skills/` | — |
| Codex CLI | `.codex/skills/` | — |
| Gemini CLI | `.gemini/skills/` | — |
| Pi | `.pi/skills/` | `.pi/prompts/` |
***
## `monocle unregister`
Remove monocle registration from an agent. This is the inverse of `monocle register`.
```bash theme={"dark"}
monocle unregister [agent] [--global] [--keep-plan-hook] [--keep-review-gate] [--no-tui]
```
### Arguments
| Argument | Description |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agent` | The agent to unregister. One of `claude`, `opencode`, `codex`, `gemini`, `pi`, or `all`. If omitted, an interactive TUI wizard shows only the agents that are actually registered at the chosen scope and asks whether to keep or remove each hook group. |
### Flags
| Flag | Description |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `--global` | Remove configuration from the user-level config directory instead of the current project directory. |
| `--keep-plan-hook` | Leave the Claude Code `ExitPlanMode` hook entries in `settings.json` even after the MCP server entry is removed. |
| `--keep-review-gate` | Leave the `PostToolUse` + `Stop` review-gate hook entries in `settings.json` even after the MCP server entry is removed. |
| `--no-tui` | Skip the interactive wizard and run headlessly. |
For Pi, `unregister` removes Monocle's MCP server entry, Monocle-managed prompt templates, and Monocle skills. It leaves the pinned `npm:pi-mcp-adapter@2.9.0` package in Pi settings because other MCP servers may depend on the same adapter package.
***
## `monocle hooks`
Handlers for agent lifecycle events. These subcommands are invoked by the agent's hook runner, not by humans — they read a JSON payload on stdin and emit the agent's expected decision JSON on stdout. `monocle register` wires them up automatically for Claude Code; this section documents the command surface for users who want to install them manually.
| Subcommand | Description |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `monocle hooks exit-plan` | Block on the Monocle reviewer and emit a Claude Code `PermissionRequest` `allow`/`deny` decision. |
| `monocle hooks enter-plan` | Emit a Claude Code `PreToolUse` `additionalContext` string pointing the agent at Monocle's review loop. |
| `monocle hooks mark-activity` | Notify the Monocle engine that a write-tool just fired, marking the session as having unreviewed changes. |
| `monocle hooks on-stop` | On Claude's `Stop` event, block the turn-end until the reviewer responds if (and only if) the turn included file edits. Emits a Claude Code Stop-hook `{"decision":"block","reason":...}` on "request changes"; exits 0 empty on "approve" or on a pure-chat turn. |
### Common flags
Every hooks subcommand accepts the same flags:
| Flag | Short | Description |
| ---------------- | ----- | ------------------------------------------------------------------------------------------------------ |
| `--agent AGENT` | | **(Required)** Agent whose hook runner is invoking this command. Currently only `claude` is supported. |
| `--workdir PATH` | `-C` | Override the working directory used to locate the engine socket. Also reads from `MONOCLE_WORKDIR`. |
| `--socket PATH` | | Override the Unix socket path directly. Also reads from `MONOCLE_SOCKET`. |
The `--agent` flag is required on every subcommand, even though `claude` is currently the only supported value. This keeps `settings.json` entries self-describing and makes future agents additive rather than breaking.
Error-handling philosophy: these hooks degrade gracefully. If stdin is malformed, the engine socket is unreachable, or any intermediate call fails, the command exits 0 with no stdout so the agent falls back to its built-in behavior — the hook never hard-blocks the agent.
***
## `monocle serve`
Run a headless monocle engine for the current repository. This process owns the socket, the SQLite database, and the review session; the `monocle` TUI, Desktop app, and future frontends connect as thin clients over the socket.
```bash theme={"dark"}
monocle serve [--workdir PATH] [--socket PATH] [--idle-timeout DURATION]
```
You don't normally run `monocle serve` yourself — launching `monocle` auto-spawns one in the background for the current repo if none is running. Run it manually when you want the engine up without a UI (for example, to accept `monocle review ...` calls from agents before the TUI starts), or to inspect the engine from multiple frontends at once.
### Flags
| Flag | Short | Description |
| ------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--workdir PATH` | `-C` | Override the working directory; serve attaches to the repo at this path. Also reads from `MONOCLE_WORKDIR`. |
| `--socket PATH` | | Override the Unix socket path. Also reads from `MONOCLE_SOCKET`. |
| `--idle-timeout DURATION` | | Exit after this idle interval past the 60s grace window (for example, `30m`, `1h`). Defaults to 30 minutes. Use `0` via `config.json` to disable. |
### Idle shutdown
`monocle serve` exits automatically when every connected client has been gone for 60 seconds plus `--idle-timeout`. A TUI the user leaves idle still holds a socket open, so only a genuinely-abandoned serve exits. If the serve has already idled out when the user next runs `monocle`, autospawn brings up a fresh one — there's nothing to clean up by hand.
***
## `monocle stop`
Shut down a running `monocle serve` for the current repository. Reads the PID file written by `serve`, sends `SIGTERM`, and waits for clean exit. No-op when no serve is running.
```bash theme={"dark"}
monocle stop [--workdir PATH] [--socket PATH] [--timeout DURATION]
```
### Flags
| Flag | Short | Description |
| -------------------- | ----- | -------------------------------------------------------------------------------------- |
| `--workdir PATH` | `-C` | Override the working directory. Also reads from `MONOCLE_WORKDIR`. |
| `--socket PATH` | | Override the Unix socket path. Also reads from `MONOCLE_SOCKET`. |
| `--timeout DURATION` | | Maximum time to wait for the server to exit after sending `SIGTERM`. Defaults to `5s`. |
***
## `monocle serve-mcp`
Start the built-in MCP server over stdio. This exposes monocle's review operations (`review_status`, `get_feedback`, `send_artifact`, `add_files`) as MCP tools that any stdio-compatible agent can call.
```bash theme={"dark"}
monocle serve-mcp [--socket PATH]
```
Use this command when your agent isn't natively supported by `monocle register`. Add it as an MCP server in your agent's config, pointing at `monocle serve-mcp` as the stdio command.
### Flags
| Flag | Description |
| --------------- | ---------------------------------------------------------------- |
| `--socket PATH` | Override the Unix socket path. Also reads from `MONOCLE_SOCKET`. |
See [agent setup for unsupported agents](/guides/agent-setup#other-agents) for a step-by-step walkthrough.
***
## `monocle --version`
Print the installed monocle version and exit.
```bash theme={"dark"}
monocle --version
```
# Keybindings
Source: https://docs.getmonocle.sh/reference/keybindings
Complete keyboard shortcut reference for monocle.
Press `?` inside monocle to see the current effective keybindings, including any custom overrides you have configured.
## Navigation
| Key | Action |
| ------------------- | ---------------------------------------------- |
| `j` / `k` | Move up / down |
| `J` / `K` | Scroll diff up / down (any pane) |
| `Ctrl+d` / `Ctrl+u` | Scroll diff half page (any pane) |
| `g` / `G` | Jump to top / bottom |
| `h` / `l` | Scroll diff left / right |
| `H` / `L` | Scroll diff left / right (any pane) |
| `0` | Scroll to column 0 (any pane) |
| `^` | Scroll to first non-space character (any pane) |
| `$` | Scroll to end of line (any pane) |
| `[` / `]` | Previous / next file (any pane) |
| `{` / `}` | Previous / next sidebar section (any pane) |
## View and layout
| Key | Action |
| --------- | ----------------------------------------------------------- |
| `Enter` | Focus the diff pane / toggle directory open |
| `Tab` | Switch pane focus |
| `\` | Toggle sidebar visibility |
| `1` / `2` | Jump directly to pane 1 or 2 |
| `w` | Toggle line wrapping (any pane) |
| `f` | Toggle flat / tree view |
| `z` / `e` | Collapse all / expand all (tree view) |
| `t` | Cycle diff style: unified → split → file (any pane) |
| `T` | Cycle layout: auto → side-by-side → stacked |
| `F` | Toggle focus mode (hides sidebar and enables line wrapping) |
| `R` | Force reload files |
## Commenting
| Key | Action |
| ------- | ---------------------------------------------------------------------- |
| `c` | Add a comment at the cursor line (opens editor on an existing comment) |
| `s` | Suggest an edit at the cursor (pre-fills a `suggestion` block) |
| `C` | Add a file-level comment |
| `v` | Enter visual select mode for multi-line comments |
| `x` | Toggle a comment resolved / unresolved (when on a comment line) |
| `d` | Delete a comment (when on a comment line) |
| `Space` | Toggle expand / collapse on a comment under the cursor |
## Review actions
| Key | Action |
| --------------- | ------------------------------------------------------------------------------- |
| `b` | Change the base ref |
| `B` | Browse artifact version history and diff against a previous version |
| `r` | Toggle the current file as reviewed (auto-advances to the next unreviewed file) |
| `/` | Cycle the sidebar filter: all → unreviewed → reviewed |
| `S` / `:submit` | Submit your review |
| `Ctrl+g` | Open the current text in your `$VISUAL` / `$EDITOR` (comment or submit modal) |
| `Ctrl+y` | Copy the formatted review to the clipboard without submitting |
| `P` / `:pause` | Send a pause notification to the agent (requires MCP channel support) |
| `D` / `:clear` | Clear the review: removes all comments, plans, and reviewed states |
| `x` | Dismiss the focused artifact from the sidebar (confirm required) |
## Commands
| Key | Action |
| ------------------------ | ------------------------------------------------------ |
| `:mark-all-reviewed` | Mark every file in the session as reviewed |
| `:mark-all-unreviewed` | Mark every file in the session as unreviewed |
| `:discard` | Discard all pending (unsaved) comments |
| `:history` | View past review submissions |
| `:base-artifact-version` | Browse artifact version history (same as `B`) |
| `:base-ref` | Change the base ref (same as `b`) |
| `I` | Show connection info: socket path and subscriber count |
| `?` | Show all keybindings |
## Register wizard
These keys are active inside the `monocle register` / `monocle unregister` TUI wizard.
| Key | Action |
| ------------------------- | ----------------------------------- |
| `Enter` | Advance to the next step |
| `Shift+Tab` / `Backspace` | Go back to the previous step |
| `Space` | Toggle the current option on or off |
## Comment editor
The comment editor uses standard Emacs-style shortcuts.
| Key | Action |
| -------------------------------- | ---------------------------------------------------- |
| `←` / `→` or `Ctrl+B` / `Ctrl+F` | Move cursor left / right |
| `↑` / `↓` or `Ctrl+P` / `Ctrl+N` | Move cursor up / down (multiline) |
| `Home` / `Ctrl+A` | Jump to first non-whitespace, then to start of line |
| `End` / `Ctrl+E` | Jump to end of line |
| `Ctrl+D` or `Delete` | Delete character at cursor |
| `Ctrl+K` | Kill (delete) to end of line |
| `Ctrl+U` | Kill (delete) to start of line |
| `Ctrl+W` or `Alt+Backspace` | Delete word before cursor |
| `Alt+D` | Delete word after cursor |
| `Alt+←` or `Alt+B` | Move cursor back one word |
| `Alt+→` or `Alt+F` | Move cursor forward one word |
| `Shift+Enter` or `Alt+Enter` | Insert a newline |
| `Ctrl+G` | Open in external editor (`$VISUAL` / `$EDITOR`) |
| `Tab` | Cycle comment type (issue, suggestion, note, praise) |
| `Enter` | Save the comment |
| `Esc` | Cancel without saving |
# Troubleshooting
Source: https://docs.getmonocle.sh/reference/troubleshooting
Solutions for common monocle issues.
Monocle creates a Unix socket based on its working directory. If your agent runs in a different directory, it looks for a socket in the wrong place and cannot connect.
**To diagnose:** Press `I` inside monocle to see the active socket path and how many subscribers are connected.
**Solution: set `MONOCLE_SOCKET`**
Copy the socket path shown by `I` and pass it to your agent commands via the environment variable:
```bash theme={"dark"}
MONOCLE_SOCKET=/tmp/monocle-abc123.sock monocle review status
```
**To start monocle on a specific socket:**
```bash theme={"dark"}
monocle --socket /tmp/monocle-abc123.sock
```
**For Claude Code MCP:** Add `MONOCLE_SOCKET` to the `env` block in `.mcp.json`:
```json theme={"dark"}
{
"mcpServers": {
"monocle": {
"env": {
"MONOCLE_SOCKET": "/tmp/monocle-abc123.sock"
}
}
}
}
```
If you start or restart monocle while Claude Code is already running, the MCP channel connection may be stale and push notifications will not arrive.
**Solution:** Type `/mcp` in Claude Code and select monocle from the list to trigger a reconnect. You do not need to restart Claude Code.
Push notifications require:
1. Claude Code with [MCP channel support](https://code.claude.com/docs/en/channels-reference)
2. Claude Code must be started with the `--dangerously-load-development-channels` flag:
```bash theme={"dark"}
claude --dangerously-load-development-channels plugin:monocle@monocle
```
The `--dangerously-load-development-channels` flag is required during the MCP channels research preview.
**Also check that monocle is registered:**
```bash theme={"dark"}
monocle register claude
```
**If push notifications remain unavailable:** Your feedback is not lost. It stays in the queue and will be delivered the next time the agent calls `/get-feedback` or runs `monocle review get-feedback`.
Monocle must be running in the same Git repository as your agent. Check the title bar or press `I` to see the working directory monocle is using.
Run this from the agent's working directory:
```bash theme={"dark"}
monocle review status
```
If monocle is reachable, this prints the current status. If it exits with an error, the agent cannot reach the socket — see the socket mismatch section above.
Press `I` in monocle to copy the socket path, then set `MONOCLE_SOCKET` for the agent:
```bash theme={"dark"}
MONOCLE_SOCKET=/tmp/monocle-abc123.sock monocle review status
```
Feedback is always queued for reliability — the agent does not receive it automatically unless push notifications are enabled.
* **With Claude Code and MCP channels:** A push notification prompts the agent to retrieve feedback immediately. If the notification did not arrive, check the push notifications section above.
* **With other agents:** The agent must run the `/get-feedback` skill or call `monocle review get-feedback` to pull the queued feedback. Trigger this manually if the agent has not done so on its own.
* **To request the agent stop and wait:** Press `P` in monocle to send a pause notification. The agent will call `monocle review get-feedback --wait` and block until you submit your review. Pause requires MCP channel support (currently Claude Code only).
Multiple reviews accumulate in the queue and are delivered together as a single combined response when the agent next calls `get-feedback`.