CLI Reference

`monocle`

Start a review session in the current directory.

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.

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.

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.

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.

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]

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 for a step-by-step walkthrough.

`monocle --version`

Print the installed monocle version and exit.

monocle --version

Get Started

Core Concepts

Guides

Configuration

Reference

`monocle`

Flags

Session flags

`monocle register`

Arguments

Flags

Plan-mode hooks (Claude Code)

What the hooks do

Integration modes

Agent config paths

`monocle unregister`

Arguments

Flags

`monocle hooks`

Common flags

`monocle serve`

Flags

Idle shutdown

`monocle stop`

Flags

`monocle serve-mcp`

Flags

`monocle --version`

​monocle

​Flags

​Session flags

​monocle register

​Arguments

​Flags

​Plan-mode hooks (Claude Code)

​What the hooks do

​Integration modes

​Agent config paths

​monocle unregister

​Arguments

​Flags

​monocle hooks

​Common flags

​monocle serve

​Flags

​Idle shutdown

​monocle stop

​Flags

​monocle serve-mcp

​Flags

​monocle --version

`monocle`

Flags

Session flags

`monocle register`

Arguments

Flags

Plan-mode hooks (Claude Code)

What the hooks do

Integration modes

Agent config paths

`monocle unregister`

Arguments

Flags

`monocle hooks`

Common flags

`monocle serve`

Flags

Idle shutdown

`monocle stop`

Flags

`monocle serve-mcp`

Flags

`monocle --version`