Skip to main content

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.

A monocle session holds your comments, plans, and reviewed states for a given working directory. Sessions are stored on disk, so your work survives restarts.

​
Starting a session

monocle                        # start a new session
monocle --continue             # resume the most recent session
monocle --resume               # open a picker to choose a previous session
monocle --session <ID>         # resume a specific session by ID

​
Adding files to review

By default, monocle reviews the git diff in your working directory. To include files outside the diff — or files from other paths — you can add them explicitly. At startup, use --additional-path (repeatable): 
monocle --additional-path ./docs --additional-path ./scripts
While running, use the agent-facing command: 
monocle review add-files <paths...>
Your agent can also call this via a skill to add files mid-session.

​
Tracking review progress

Mark a file as reviewed by pressing r when it’s selected. monocle automatically advances to the next unreviewed file. Filter the sidebar with / to cycle through views:
  • All — every file in the session
  • Unreviewed — only files you haven’t marked reviewed
  • Reviewed — only files you’ve already reviewed
To mark every file at once, use the command palette:
  • :mark-all-reviewed — mark all files as reviewed
  • :mark-all-unreviewed — mark all files as unreviewed
When you submit a review with Request Changes, monocle creates a snapshot of all file states. On the next round, files that changed since the snapshot are automatically marked as unreviewed, so you can filter to just what’s new. See Review State for the full details on how snapshots, rounds, and change detection work.

​
Submission history

To see past review submissions for the current session, run: 
:history
This opens a list of previous submissions with their comments and timestamps.

​
Clearing a review

To remove all comments, plans, and reviewed states from the current session, press D or run: 
:clear
This is useful when you want to start fresh after a major round of changes.

​
Connection info and troubleshooting

Press I in the TUI to see the current socket path and subscriber count — useful for confirming your agent is connected. If monocle and your agent are running in different working directories, auto-pairing may fail. Override the socket path manually: Start monocle with a specific socket: 
monocle --socket /tmp/monocle-abc123.sock
Point agent commands at the same socket: 
MONOCLE_SOCKET=/tmp/monocle-abc123.sock monocle review status
For Claude Code’s MCP channel, set MONOCLE_SOCKET in the env section of your .mcp.json.