Skip to main content
Monocle creates a Unix socket based on its working directory. If your agent runs in a different directory, it looks for a socket in the wrong place and cannot connect.To diagnose: Press I inside monocle to see the active socket path and how many subscribers are connected.Solution: set MONOCLE_SOCKETCopy the socket path shown by I and pass it to your agent commands via the environment variable:
MONOCLE_SOCKET=/tmp/monocle-abc123.sock monocle review status
To start monocle on a specific socket:
monocle --socket /tmp/monocle-abc123.sock
For Claude Code MCP: Add MONOCLE_SOCKET to the env block in .mcp.json:
{
  "mcpServers": {
    "monocle": {
      "env": {
        "MONOCLE_SOCKET": "/tmp/monocle-abc123.sock"
      }
    }
  }
}
If you start or restart monocle while Claude Code is already running, the MCP channel connection may be stale and push notifications will not arrive.Solution: Type /mcp in Claude Code and select monocle from the list to trigger a reconnect. You do not need to restart Claude Code.
Push notifications require two things beyond a basic monocle installation:
  1. A JavaScript runtime — Bun, Deno, or Node.js — must be installed and on your PATH.
  2. Claude Code must be started with the --dangerously-load-development-channels flag:
claude --dangerously-load-development-channels plugin:monocle@monocle
The --dangerously-load-development-channels flag is required during the MCP channels research preview.
Also check that monocle is registered:
monocle register claude
If push notifications remain unavailable: Your feedback is not lost. It stays in the queue and will be delivered the next time the agent calls /get-feedback or runs monocle review get-feedback.
1

Confirm monocle is running in the right directory

Monocle must be running in the same Git repository as your agent. Check the title bar or press I to see the working directory monocle is using.
2

Verify the connection

Run this from the agent’s working directory:
monocle review status
If monocle is reachable, this prints the current status. If it exits with an error, the agent cannot reach the socket — see the socket mismatch section above.
3

Override the socket if needed

Press I in monocle to copy the socket path, then set MONOCLE_SOCKET for the agent:
MONOCLE_SOCKET=/tmp/monocle-abc123.sock monocle review status
Feedback is always queued for reliability — the agent does not receive it automatically unless push notifications are enabled.
  • With Claude Code and MCP channels: A push notification prompts the agent to retrieve feedback immediately. If the notification did not arrive, check the push notifications section above.
  • With other agents: The agent must run the /get-feedback skill or call monocle review get-feedback to pull the queued feedback. Trigger this manually if the agent has not done so on its own.
  • To request the agent stop and wait: Press P in monocle to send a pause notification. The agent will call monocle review get-feedback --wait and block until you submit your review. Pause requires MCP channel support (currently Claude Code only).
Multiple reviews accumulate in the queue and are delivered together as a single combined response when the agent next calls get-feedback.