> ## 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. # CLI Reference > 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 ```