o_(◉) monocle

Review your AI agent's code as it writes it. Leave comments on diffs, submit structured feedback, and watch the agent fix things in real time — all from your terminal.

More screenshots →

Monocle is a TUI that runs alongside your AI coding agent. You review diffs in real time as the agent writes code, leave line-level comments — issues, suggestions, notes — and submit a structured review in one batch. The agent receives your feedback and starts fixing things immediately, just like a PR review but live.

Monocle connects to your agent via MCP tools or CLI commands over a Unix socket. With Claude Code and MCP channels, it pushes feedback directly into the agent's context the moment you submit. Other agents — OpenCode, Codex CLI, Gemini CLI, and Pi — retrieve feedback on demand. MCP channels just make the process smoother.

Why

Without something 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. The agent receives your feedback immediately and starts addressing it. You see the updated diffs, review again, and iterate — like PR reviews, but in real time.

Requirements

• A coding agent: Claude Code, OpenCode, Codex CLI, Gemini CLI, Pi, or any MCP-compatible agent
• A terminal with 256-color or true color support
• A Nerd Font for file icons (optional but recommended)

Installation

Homebrew (macOS/Linux)

brew install --cask josephschmitt/tap/monocle

Upgrading from a previous (formula) install? monocle is now distributed as a Homebrew cask rather than a formula. If you previously ran brew install josephschmitt/tap/monocle, uninstall the old formula first, then reinstall as a cask:

brew uninstall monocle        # remove the old formula
brew install --cask josephschmitt/tap/monocle

See Why a cask? for the rationale.

Other installation methods

Pre-built Binaries

Download from GitHub Releases:

macOS:

# Apple Silicon
# x-release-please-start-version
curl -Lo monocle.tar.gz https://github.com/josephschmitt/monocle/releases/download/v0.48.1/monocle_darwin_arm64.tar.gz
# x-release-please-end
tar xzf monocle.tar.gz
sudo mv monocle /usr/local/bin/

# Intel
# x-release-please-start-version
curl -Lo monocle.tar.gz https://github.com/josephschmitt/monocle/releases/download/v0.48.1/monocle_darwin_amd64.tar.gz
# x-release-please-end
tar xzf monocle.tar.gz
sudo mv monocle /usr/local/bin/

Linux:

# x86_64
# x-release-please-start-version
curl -Lo monocle.tar.gz https://github.com/josephschmitt/monocle/releases/download/v0.48.1/monocle_linux_amd64.tar.gz
# x-release-please-end
tar xzf monocle.tar.gz
sudo mv monocle /usr/local/bin/

# ARM64
# x-release-please-start-version
curl -Lo monocle.tar.gz https://github.com/josephschmitt/monocle/releases/download/v0.48.1/monocle_linux_arm64.tar.gz
# x-release-please-end
tar xzf monocle.tar.gz
sudo mv monocle /usr/local/bin/

From Source

git clone https://github.com/josephschmitt/monocle.git
cd monocle
devbox run -- make build
# Binaries are in bin/

Quick Start

1. Register Monocle with your agent

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

This configures MCP tools or skills depending on the agent. Claude Code gets an MCP server and slash commands. Pi uses existing project or global pi-mcp-adapter setups automatically, otherwise it falls back to skills plus prompt templates; pass --integration-mode mcp to add the pinned adapter explicitly. Other agents get skill files by default. Use --global to write to the user-level config directory instead of the project. If Pi is already running, restart it or run /reload after registering.

Other agents

If your agent isn't natively supported, you can set up Monocle manually:

• MCP tools: If your agent supports MCP servers via stdio, point it at monocle serve-mcp. This exposes review tools (review_status, get_feedback, send_artifact, add_files) over stdio.
• Skills: Download skills.tar.gz from the latest release and extract the skill files into wherever your agent expects its skills.

2. Start reviewing

Start your agent and Monocle in separate terminals:

monocle

For Claude Code, Monocle registers an MCP server that exposes review tools directly — no bash permissions or skills needed. For Pi, Monocle uses pi-mcp-adapter only when it is already configured, or when you explicitly request MCP mode; otherwise Pi uses prompts and skills that run CLI commands. Other agents get skills that instruct them to run CLI commands.

Push notifications (Claude Code only)

Claude Code supports MCP channels, which deliver feedback automatically. When you submit a review, a push notification prompts the agent to retrieve your feedback immediately instead of waiting for the next poll.

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

The review loop

Navigate with j/k, add comments with c, and use v for visual (multi-line) selections. Press ? to see all keybindings, or see the full Keybindings reference.

Submit (S): Your review is formatted and queued for delivery. With Claude Code channels, a push notification prompts the agent to retrieve it immediately. With other agents, the review waits in the queue until the agent runs /get-feedback or calls monocle review get-feedback. Multiple reviews can accumulate in the queue — the agent receives them all combined when it pulls. If there are no comments, the review is treated as an approval. Toggle the "Copy to clipboard" checkbox with Shift+Tab in the submit modal to also copy the formatted review when submitting.

External editor (Ctrl+g): In the comment or submit modal, opens the current text in your $VISUAL or $EDITOR (falls back to vi). Edit in your preferred editor, save and quit, and the text is brought back into the modal.

Yank (Ctrl+y): In the submit modal, copies the formatted review to your system clipboard without submitting, then closes the modal.

Pause (P): The agent receives a push notification to stop and wait. It runs monocle review get-feedback --wait and blocks until you submit your review. This is for when you want to review before the agent moves on. Pause requires MCP channel support (currently Claude Code only).

Plan review and focus mode

Monocle isn't limited to reviewing file changes. Your agent can submit plans, architecture decisions, summaries, and other content directly to Monocle for review using monocle review send-artifact. These show up alongside your file diffs in the sidebar, and you can leave line-level comments on them the same way. You can also trigger this yourself with /review-plan or /review-plan-wait — useful when you want to send the agent's plan to Monocle without waiting for the agent to do it on its own.

This means you can review the agent's thinking before it writes code — not just the output. Ask the agent to submit its content first, review it, leave feedback, and only then let it proceed.

/review-plan-wait submits content to your TUI and blocks until you respond with feedback. If you approve, the agent continues. If you request changes, the agent updates and submits again — iterating across as many rounds as it takes until you're satisfied.

Note: Monocle's operations are available to your agent but the agent decides when to use them on its own. If you want the agent to automatically submit plans for review, add instructions to your agent's project configuration. See Automatic content review below for a suggested prompt.

Features

• Works with any coding agent — Claude Code, OpenCode, Codex CLI, Gemini CLI, Pi, or any MCP-compatible agent
• Push notifications — With Claude Code channels, feedback is pushed directly into the agent's context the moment you submit
• Pull-based feedback — Agents without channel support retrieve feedback via /get-feedback or monocle review get-feedback; multiple reviews queue up and are delivered together
• Plan & architecture review — Your agent can submit plans, architecture decisions, and other content for review with markdown rendering. When iterating, Monocle shows diffs between plan versions so you can see exactly what changed. Use focus mode (F) for distraction-free reading
• Review gating — /review-plan-wait blocks the agent until you approve the submitted content before it proceeds
• Pause flow — Ask your agent to stop and wait while you review, then release it when ready (requires MCP channel support)
• Live diff viewer — Unified and split (side-by-side) views with syntax highlighting and intra-line diffs
• Structured comments — Tag feedback as issues, suggestions, notes, or praise with line-level or file-level precision
• Suggested edits — Press s to propose exact code changes with GitHub-style suggestion blocks
• Visual selection — Select line ranges for comments with vim-style visual mode
• Markdown rendering — Plans and changed .md files render with styled headings, bold, italic, lists, and code blocks
• Horizontal scrolling & line wrapping — Navigate wide diffs with h/l or toggle wrapping with w
• Responsive layout — Automatically stacks panes vertically in narrow terminals
• Ref picker — Change the base ref on the fly to compare against any branch or commit
• Version history — Browse all versions of a plan or artifact and diff any version against the latest
• Comment resolution — Mark individual comments as resolved (x); resolved comments are excluded from submitted reviews
• Submission history — View past review submissions with :history
• Mouse support — Click to focus panes, scroll with the wheel, click files to select, drag to make visual selections, and interact with modal controls
• External editor — Open comment or submit text in $VISUAL/$EDITOR with Ctrl+g for full editing power
• Configurable keybindings — Override any navigation or action key via config
• Feedback queue — Submit reviews while the agent is working; delivered when the agent next runs /get-feedback
• Connection indicator — See at a glance whether your agent is connected, with manual socket override for troubleshooting
• Review tracking — Mark files as reviewed with r (auto-advances to next), filter sidebar with /. When you submit feedback, monocle snapshots file state so it can automatically detect what changed on the next round — filter to unreviewed to see only what's new
• Session persistence — Reviews survive restarts via SQLite

Agent Operations

Monocle exposes review operations via MCP tools (default for Claude Code, and for Pi when pi-mcp-adapter is already configured) or skills (default for other agents, and Pi's fallback). Both are configured automatically by monocle register.

Operation	MCP tool	Skill	Description
Get feedback	get_feedback	/get-feedback	Retrieve pending review 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

Keybindings

Key	Action
j/k	Move up/down
J/K	Scroll diff up/down (any pane)
Ctrl+d/u	Scroll diff half page (any pane)
g/G	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 (any pane)
$	Scroll to line end (any pane)
[/]	Previous/next file (any pane)
{/}	Previous/next sidebar section (any pane)
Enter	Focus diff pane / toggle dir
Tab	Switch pane focus
\	Toggle sidebar visibility
1/2	Jump to pane
w	Toggle line wrapping (any pane)
f	Toggle flat/tree view
z/e	Collapse/expand all (tree)
b	Change base ref
B	Base artifact version to diff against
c	Add comment at cursor (edit if on a comment)
s	Suggest edit at cursor (pre-fills suggestion block)
C	Add file-level comment
v	Visual select (multi-line comments)
x	Toggle comment resolved (on a comment line)
d	Delete comment (on a comment line)
r	Toggle file reviewed (auto-advances to next unreviewed)
/	Cycle sidebar filter (all -> unreviewed -> reviewed)
t	Cycle diff style (unified/split/file) (any pane)
T	Cycle layout (auto/side-by-side/stacked)
R	Force reload files
S / :submit	Submit review
Ctrl+g	Open external editor (comment/submit modal)
Ctrl+y	Copy review to clipboard
P / :pause	Pause the agent (wait for your review)
D / :clear	Clear review (all comments, plans, reviewed states)
x	Dismiss focused artifact (sidebar, confirm required)
F	Toggle focus mode (hide sidebar, enable wrap)
:mark-all-reviewed	Mark all files as reviewed
:mark-all-unreviewed	Mark all files as unreviewed
:discard	Discard all pending comments
:history	View past review submissions
:base-artifact-version	Base artifact version to diff against
:base-ref	Base ref to diff against (same as b)
I	Connection info (socket path, subscriber count)
?	Show all keybindings

Comment editor

The comment editor supports standard emacs-style shortcuts:

Key	Action
<-/-> or Ctrl+B/Ctrl+F	Move cursor left/right
up/down or Ctrl+P/Ctrl+N	Move cursor up/down (multiline)
Home/Ctrl+A	First non-whitespace, then start of line
End/Ctrl+E	End of line
Ctrl+D or Delete	Delete character at cursor
Ctrl+K	Kill to end of line
Ctrl+U	Kill 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 newline
Ctrl+G	Open in external editor ($VISUAL/$EDITOR)
Tab	Cycle comment type
Enter	Save comment
Esc	Cancel

CLI

monocle [--socket PATH]              Start a review session (auto-spawns monocle serve)
monocle serve [--idle-timeout DUR]   Run a headless engine for this repo (socket server, no TUI)
monocle stop                         Stop the running monocle serve for this repo
monocle register [agent] [--global]  Register Monocle for an agent
monocle unregister [agent] [--global] Remove Monocle registration
monocle --version                    Print version

The agent argument is one of claude, opencode, codex, gemini, pi, or all. If omitted, an interactive picker lets you select which agents to register. The --global flag writes to the user-level config directory instead of the project.

How the engine runs

Monocle 0.46+ splits the engine from the frontend. monocle serve owns the SQLite database, the review session, and the Unix socket; the monocle TUI, agent CLI commands, and future frontends all attach as thin socket clients. You don't usually need to run monocle serve yourself — launching monocle auto-spawns one in the background for the current repo. It exits on its own 60 seconds + --idle-timeout (default 30 min) after the last client disconnects.

Agent-Facing Commands

These commands are used by agents (via MCP tools or skills) to interact with a running Monocle session:

monocle review status [--json]                          Check review status
monocle review get-feedback [--wait] [--json]            Retrieve review feedback
monocle review send-artifact --title T [--file F] [--id ID] [--type EXT] [--wait] [--json]
                                                         Send content for review
monocle review add-files <paths...> [--json]             Add files to review session

• --wait blocks until the reviewer responds (used by /review-plan-wait)
• --json outputs structured JSON for programmatic use
• send-artifact reads from --file or stdin

Manual Socket Override

If auto-pairing fails (e.g., the agent's working directory differs from Monocle's), you can manually specify the socket path:

• Monocle: monocle --socket /tmp/monocle-abc123.sock
• Agent commands: MONOCLE_SOCKET=/tmp/monocle-abc123.sock monocle review status
• MCP channel (Claude): Set MONOCLE_SOCKET in .mcp.json env

Press I in the TUI to see the current socket path and connection status.

Configuration

Monocle loads settings from JSON config files:

1. Global: ~/.config/monocle/config.json (or $XDG_CONFIG_HOME/monocle/config.json)
2. Project: .monocle/config.json in the working directory (overrides global)

Note: Config is read once when the background engine (monocle serve) starts, not each time the TUI launches. To apply config changes, run monocle stop and then start monocle again to restart the engine and reload the config.

{
  "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
  }
}

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" for terminals with a light bg)
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 on hover
comment_expand_delay	integer (ms)	2000	Delay before auto-expanding a selected comment (0 = instant)
review_tracking	true, false	true	Enable review state tracking, snapshots, and change detection. Set to false to get 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)
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 --idle-timeout.
keybindings	object	{}	Custom key overrides (see below)
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.

Custom Keybindings

Override any action key by mapping the action name to a new key string:

{
  "keybindings": {
    "quit": "Q",
    "submit": "ctrl+s",
    "scroll_down": "ctrl+j"
  }
}

Available action names: up, down, top, bottom, half_up, half_down, prev_file, next_file, select, focus_swap, toggle_sidebar, scroll_down, scroll_up, scroll_left, scroll_right, scroll_home, scroll_first_char, scroll_end, wrap, toggle_diff, tree_mode, collapse_all, expand_all, prev_section, next_section, comment, file_comment, suggest, visual, reviewed, submit, pause, dismiss_outdated, base_ref, cycle_layout, refresh, help, quit, command_mode.

The help overlay (?) dynamically reflects your custom bindings. Modal keys (Enter, Esc, Tab in overlays) are not configurable.

Automatic content review

By default, Monocle's operations are available to your agent but the agent decides when to use them on its own. If you want the agent to automatically submit plans or other content for review, add instructions to your agent's project configuration (e.g. CLAUDE.md, AGENTS.md, etc.):

## 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 manually at any time.

How it works

┌─────────────┐                ┌───────────────┐              ┌──────────┐
│   Agent     │<--stdio/MCP--->│  serve-mcp    │<---socket--->│ monocle  │
│             │                │ (MCP server)  │              │  (TUI)   │
└─────────────┘                └───────────────┘              └──────────┘

1. You leave line-level comments on diffs — issues, suggestions, notes, praise
2. You press S to submit your review
3. Monocle queues the review for delivery
4. The agent picks up the feedback — automatically via push notification (Claude Code with channels) or when you trigger /get-feedback — and starts addressing your comments
5. You see the updated diffs in real time, review again, and iterate

Feedback is always queued for reliability. How the agent learns about it depends on the integration:

• Claude Code with channels: A push notification is sent through the MCP channel with a summary of the review (e.g., "Your reviewer requested changes — 2 issues, 1 suggestion"). The agent runs /get-feedback to retrieve the full review. If the push fails silently (channels not enabled), the review stays in the queue.
• Any agent: The agent calls get_feedback (MCP tool) or monocle review get-feedback (CLI), either via a /get-feedback slash command or on its own. Multiple reviews accumulate in the queue and are delivered together.

If you want the agent to pause and wait for you to finish reviewing, press P — the agent receives a pause notification and blocks until your review is ready.

License

MIT