Skip to main content
Monocle communicates with agents over a Unix socket. Agents use skills — SKILL.md files that instruct the agent to call monocle review CLI commands — to check review status, retrieve feedback, and submit content for review.

​
Registering Monocle

Run monocle register to install skills and any required config for your agent: 
monocle register            # interactive picker — select one or more agents
monocle register claude     # register a specific agent
monocle register --global   # write to user-level config (available across all projects)
Accepted agent names: claude, opencode, codex, gemini, all. Use --global to register once and have Monocle available in every project without re-running per repo.

​
What registration writes

monocle register claude writes three things:
  • .claude/skills/ — Installs the get-feedback, get-feedback-wait, review-plan, and review-plan-wait skill files.
  • .mcp.json — Adds a monocle entry under mcpServers pointing to monocle serve-mcp-channel. This enables MCP channel push notifications.
  • .claude/settings.json — Adds permission entries so Claude Code doesn’t prompt for approval when running monocle review commands.
With --global, the same files are written to ~/.claude/ and ~/.mcp.json instead.

​
Alternative: agent plugin systems

Instead of monocle register, you can install Monocle through each agent’s built-in plugin or extension system: 
/plugin marketplace add josephschmitt/monocle
/plugin install monocle@monocle
OpenCode does not have a plugin marketplace. Use monocle register opencode to install.

​
Claude Code: MCP channels for push notifications

Claude Code supports MCP channels, which let Monocle push feedback directly into the agent’s context the moment you submit a review. To enable channels, start Claude Code with the channels flag: 
claude --dangerously-load-development-channels plugin:monocle@monocle
The --dangerously-load-development-channels flag is required during the channels research preview. Without it, the agent still receives feedback — it retrieves it on the next /get-feedback call instead of immediately.
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.

​
Socket pairing

Monocle starts a Unix socket server when it launches. Agent CLI commands (monocle review status, get-feedback, etc.) connect to that socket to communicate with the running session. Monocle auto-pairs by matching working directories. If the agent runs in the same directory as Monocle, pairing happens automatically. If auto-pairing fails — for example, if the agent’s working directory differs from Monocle’s — you can set the socket path manually: 
# Override the socket when starting Monocle
monocle --socket /tmp/monocle-abc123.sock

# Override for agent-facing commands
MONOCLE_SOCKET=/tmp/monocle-abc123.sock monocle review status

# Override in .mcp.json for Claude Code
# Add MONOCLE_SOCKET to the env block of the monocle mcpServers entry
Press I in the TUI to see the current socket path and the number of connected subscribers.

​
Session modes

By default, monocle starts a new review session. You can control session behavior with these flags:
FlagBehavior
(none)Start a new session
--continueResume the most recent session
--resumeOpen an interactive picker to choose a session
--session IDResume a specific session by ID
Sessions are persisted via SQLite, so your reviews and comments survive restarts.

​
Unregistering

To remove Monocle’s configuration for an agent: 
monocle unregister            # interactive picker
monocle unregister claude     # remove a specific agent
monocle unregister --global   # remove from user-level config
This removes skill files, the MCP config entry (for Claude Code), and any permission entries written during registration.

​
Installed skills

Registration installs four skills for all supported agents:
SkillDescription
/get-feedbackRetrieve pending review feedback from the queue
/get-feedback-waitRetrieve feedback, blocking until it’s available
/review-planFind the active plan file and submit it for review (non-blocking)
/review-plan-waitSubmit the plan and block until you approve or request changes
See Plan and architecture review for details on the plan skills.

The review loop

How feedback flows from diff to agent fix.

Configuration

Customize layout, diff style, keybindings, and more.

Build docs developers (and LLMs) love

Get started for freeTalk to us