Architecture
Monocle connects to your agent over a Unix socket. For Claude Code, a lightweight MCP server (channel.ts) sits in between and enables push notifications:
/get-feedback skill or monocle review get-feedback.
How the loop works
Agent writes code
Your agent works in its own terminal, making file changes as it goes. Monocle watches the working directory and shows updated diffs as files change.
You review the diffs
Navigate the file list in the sidebar with
j/k, select a file, and inspect the diff. Add comments at any point — you don’t need to wait for the agent to finish.Leave comments
Press
c on a diff line to add a line-level comment. Press C to add a file-level comment. Use v to enter visual mode and select a range of lines before commenting. Press Tab in the comment editor to cycle through comment types.Submit your review
Press
S to open the submit modal. Your review is formatted and queued for delivery. The agent picks it up and starts addressing each comment.Diff viewer modes
Presst (or T for layout) to cycle between display modes. You can also set your preferred default in config.
| Mode | Description |
|---|---|
| Unified | Added and removed lines interleaved in a single column. Best for most terminals. |
| Split | Side-by-side view with old content on the left and new on the right. Best on wide terminals. |
| File | Shows raw file content without diff markers. Useful for reading context. |
Comment types
When you add a comment, pressTab in the comment editor to cycle through these types:
| Type | Use for |
|---|---|
| Issue | Problems that need to be fixed before you approve |
| Suggestion | Improvements that would be nice but aren’t blockers |
| Note | Observations, context, or questions |
| Praise | Things the agent did well |
Line-level vs file-level comments
- Line-level (
c): Attached to a specific diff line. Presssinstead to pre-fill asuggestionblock with the existing code, ready for you to propose an exact edit. - Visual selection (
v): Enter visual mode to select a range of lines, then presscto attach a comment spanning the entire selection. - File-level (
C): Attached to the file as a whole, not a specific line. Use for high-level feedback about a file’s structure or approach.
You can mark a comment as resolved with
x. Resolved comments are excluded from submitted reviews. To delete a comment entirely, press d while on a comment line.The feedback queue
When you submit a review, monocle doesn’t send it directly — it queues it for reliable delivery. This means:- You can submit a review even if your agent is busy working on something else.
- Multiple reviews can accumulate in the queue. When the agent next retrieves feedback, it receives all queued reviews combined.
- If the agent disconnects and reconnects, queued reviews are still waiting.
The submit flow
PressS to open the submit modal. From here:
- Submit: Formats your comments into a structured review and queues it for delivery. All reviewed states reset so you can start fresh on the next round.
- Copy to clipboard: Toggle the checkbox with
Shift+Tabto also copy the formatted review to your clipboard when submitting. - Yank without submitting: Press
Ctrl+yin the submit modal to copy the formatted review to your clipboard and close the modal without queuing it. - External editor: Press
Ctrl+gin the submit modal (or any comment modal) to open the current text in your$VISUALor$EDITOR. Edit, save, and quit — the text comes back into monocle.
Approval
If you submit a review with no comments, monocle treats it as an approval. The agent receives an approval signal and knows it can proceed.Pausing the agent
If you want the agent to stop and wait while you finish reviewing, pressP. The agent receives a pause notification and blocks on monocle review get-feedback --wait until you submit your review.
Pause requires MCP channel support and is currently only available with Claude Code.