Documentation Index
Fetch the complete documentation index at: https://docs.getmonocle.sh/llms.txt
Use this file to discover all available pages before exploring further.
monocle
Start a review session in the current directory.
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.
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, or all. If omitted, an interactive TUI wizard walks you through agent selection, integration mode, and (for Claude Code) the hook-group toggles. |
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 | 345600s | 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 | 345600s | Block turn-end on reviewer approval when the turn included file edits. |
--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.
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; all other agents use skills. |
mcp | Configures an MCP server that exposes monocle’s review tools directly. No skill files are installed. |
skills | Installs skill files that wrap monocle CLI commands. 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)
| Agent | MCP config | Commands |
|---|
| Claude Code | .mcp.json | .claude/commands/ |
| OpenCode | opencode.json | .opencode/commands/ |
| Codex CLI | .codex/config.toml | — |
| Gemini CLI | .gemini/settings.json | .gemini/commands/ |
| Agent | Skills directory | MCP config |
|---|
| Claude Code | .claude/skills/ | .mcp.json |
| OpenCode | .opencode/skills/ | — |
| Codex CLI | .codex/skills/ | — |
| Gemini CLI | .gemini/skills/ | — |
monocle unregister
Remove monocle registration from an agent. This is the inverse of monocle register.
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, 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. |
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. |
--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.
monocle serve [--workdir PATH] [--socket PATH] [--idle-timeout DURATION]
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.
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.
monocle serve-mcp [--socket PATH]
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. |
monocle --version
Print the installed monocle version and exit.