A single Go daemon that watches every coding-agent CLI you run (Claude Code, Codex, Cursor, opencode, cursor-agent), gives you one web dashboard to see all of them live, and lets you drive their tmux panes from the browser — including answering permission prompts, sending text, and routing messages between agents.
Headlines: Claude (one tmux pane) asks Codex (another pane) to code-review
a file via the talk_to_agent MCP tool; the same daemon also serves a live
web dashboard with talk-to picker, mobile layout, and per-session detail.
┌────────────────────────────┐ ┌────────────────────────────────┐
│ Browser (desktop / phone) │ <───ws/http──> │ agent-monitor daemon (Go) │
│ ─ session list │ │ :7777 │
│ ─ live tmux pane viewer │ │ │
│ ─ Send / Cancel / Keys │ │ ┌──────────────────────────┐ │
│ ─ Allow / Deny prompts │ │ │ adapters │ │
│ ─ Talk-to picker │ │ │ Claude Codex Cursor │ │
│ ─ Inbox banners │ │ │ opencode cursor-agent │ │
└────────────────────────────┘ │ └──────────────────────────┘ │
│ ┌──────────────────────────┐ │
┌────────────────────────────┐ │ │ pane registry │ │
│ CLIs (claude/codex/…) │ │ │ agentId → paneId │ │
│ inside tmux panes │ <──tmux send-> │ │ aliases, persisted to │ │
│ ─ launched via │ keys / cap- │ │ ~/.agent-monitor/ │ │
│ `agent-monitor run X` │ ture-pane │ └──────────────────────────┘ │
│ ─ identity recorded by │ │ ┌──────────────────────────┐ │
│ SessionStart hook OR │ │ │ talk store │ │
│ wrapper announcement │ │ │ request + (allow/deny + │ │
│ ─ MCP client of daemon ◄──┼──── stdio ────►│ │ reply) channels + │ │
│ (talk_to_agent, │ JSON-RPC │ │ audit log │ │
│ reply_to_talk, …) │ │ └──────────────────────────┘ │
└────────────────────────────┘ │ ┌──────────────────────────┐ │
│ │ MCP server │ │
│ │ permission_prompt │ │
│ │ who_am_i / list_agents │ │
│ │ read_pane / talk_to_… / │ │
│ │ reply_to_talk │ │
│ └──────────────────────────┘ │
└────────────────────────────────┘
Three rails of agent → daemon traffic:
- Adapter ingest (one-way, daemon ← filesystem) — adapters tail JSONL / scan chat dirs / read processes to populate the session store.
- Pane control (two-way, daemon ⇄ tmux) —
tmux send-keysfor input andtmux capture-panefor the live viewer. Routed through pane registry. - MCP (two-way, daemon ⇄ agent CLI) — stdio JSON-RPC. Claude / Codex
call the daemon's MCP tools to coordinate with each other; the daemon
calls back into Claude only for
permission_prompt(a Claude-specific protocol).
Every coding agent leaves a trail:
| Tool | Trail |
|---|---|
| Claude Code | ~/.claude/projects/*/<id>.jsonl + hooks |
| Codex | ~/.codex/sessions/*/<id>.jsonl |
| opencode | ~/.local/share/opencode/storage/ |
| Cursor IDE | ~/.cursor/chats/<wsHash>/<chatId>/store.db |
| cursor-agent | a cursor-agent process scanned via ps |
agent-monitor reads them all into one in-memory store, broadcasts changes
over a WebSocket, and serves a single-page web app that shows the unified
timeline. From there you can drive each agent's tmux pane (view, type, send
keys, cancel) and route messages between agents.
# 1. build
go build -o agent-monitor .
# 2. wire it into Claude Code + Codex (idempotent; backs up edited files)
./agent-monitor install
# 3. run the daemon (foreground)
./agent-monitor
# Or in background, listening on every interface (Tailscale / LAN reachable)
AGENT_MONITOR_BIND=0.0.0.0 nohup ./agent-monitor >> agent-monitor.log 2>&1 &agent-monitor install patches three files (each gets a daily .bak-YYYY-MM-DD
sibling on first edit):
| File | Adds |
|---|---|
~/.claude/settings.json |
SessionStart / Notification / PreToolUse hooks |
~/.claude.json |
mcpServers.agent-monitor (so Claude exposes the new tools) |
~/.codex/config.toml |
[mcp_servers.agent-monitor] (skipped if Codex isn't installed) |
agent-monitor # foreground daemon
agent-monitor stop # kill ONLY the daemon (by listen-port owner)
agent-monitor restart # stop + startDon't
pkill -f /agent-monitor/agent-monitor. That pattern matches everyagent-monitor mcp-perm-serverchild too — those are the MCP servers that codex/claude spawned and rely on for thetalk_to_agent/read_pane/list_agents/reply_to_talktools. Killing them closes the MCP transport, and codex/claude won't auto-reconnect — you have to restart the agent CLI itself. Useagent-monitor stopinstead.
Open http://localhost:7777. To reach the dashboard from another device, use
Tailscale (or a LAN IP). The daemon prints every reachable URL on startup:
agent-monitor listening on http://0.0.0.0:7777
⚠ exposed beyond localhost — anyone who can reach 0.0.0.0 on port 7777 controls every registered tmux pane.
Reachable URLs:
http://localhost:7777
http://192.168.1.16:7777
http://100.68.125.93:7777 (Tailscale)
Don't bind to
0.0.0.0on untrusted networks — anyone who can reach the port can write into your tmux panes. Bind to a specific Tailscale IP (e.g.AGENT_MONITOR_BIND=100.68.125.93) to expose tailnet-only.
Heuristic matching ("which pane is this Claude session in?") is fundamentally guesswork — multiple Claude panes in similar cwds will collide. The daemon deletes that approach entirely; instead, every drivable pane is registered explicitly at launch time. There are three paths in:
bin/claude-hook.sh POSTs to /api/pane/register whenever Claude fires its
SessionStart hook. The hook payload i
9798
ncludes session_id; the script
appends $TMUX_PANE and $TMUX from the surrounding shell.
agent-monitor install-hooks # patches ~/.claude/settings.jsonAfter install, every new Claude session inside tmux is registered automatically. Sessions started outside tmux simply have no pane bridge.
For Codex / cursor-agent / opencode (or even Claude if you prefer uniform launch), wrap the agent:
tmux new -s work
agent-monitor run codex
agent-monitor run cursor-agent
agent-monitor run opencode
agent-monitor run claude # also worksThe wrapper:
- Reads
$TMUX_PANE. Errors clearly if not in tmux. - POSTs
/api/pane/announcewith{tool, paneId, cwd, …}. The daemon stores it in a 60-second pending list. execs the real agent — wrapper process vanishes.- When a new session of that tool from that cwd appears in the store (via the JSONL adapter), the daemon pairs it with the pending entry and publishes a registration.
If a session was already running before you set up the hook, the bridge shows a picker of every live tmux pane. Cwd-matches float to the top with a green badge. One click registers; if there's exactly one cwd-exact match, it auto-registers. The "forget" button removes the registration and suppresses auto-register for that session until you pick again — so unpinning actually unpins.
Once a session is registered, the bridge appears above the detail panel:
LIVE PANE ↳ %3 · backend (manual) tick 12 · 18ms ☑auto-scroll ↻ name… talk to → forget
┌───────────────────────────────────────────────────────────────────────────────────────────┐
│ > Working on the auth refactor… │
│ ⏵ (tool: Bash) │
│ … │
└───────────────────────────────────────────────────────────────────────────────────────────┘
[ Type a prompt to send into the tmux pane running this session… ]
[ Send + Enter ] [ Send (no Enter) ] [ Cancel (Ctrl-C) ]
quick keys: [1 ↵] [2 ↵] [3 ↵] [y] [n] [↵] [esc] [↑] [↓] [⇥]
- Live viewer: polls
tmux capture-pane~every 1.2 s, ANSI → HTML. - Send + Enter / Send (no Enter): types text, optionally presses Enter.
- Cancel: sends Ctrl-C.
- Quick keys: answers menu prompts (
1 ↵= "Allow once",3 ↵= "Deny", arrows / Esc / Tab for navigation). When the session is inawaiting-permission, the row gets a yellow halo. - name…: assigns a human-friendly alias (used by
agent-monitor send). - talk to →: opens the agent-to-agent picker (see below).
- forget: removes the registration; bridge collapses to the empty-state picker. Auto-register is suppressed until you pick manually again.
Any agent can message any other registered agent. The recipient's web view gets a confirmation banner; if the user clicks ✓ Deliver to my pane, the message is typed into the recipient's tmux pane wrapped in a fenced block:
[from claude/abc123 — agent-monitor talk]
hey - what's your status on the auth refactor?
(Then Enter is pressed so the receiving CLI sees a fresh prompt.)
agent-monitor send <recipient> "your message"<recipient> accepts any of:
- alias (e.g.
backend) - exact agent id (e.g.
claude:abc123-…) - tmux pane id (e.g.
%3) - session-id prefix (≥ 6 chars)
Sender is auto-discovered from $TMUX_PANE unless --from <id> is given.
The CLI long-polls until the recipient allows / denies / times out, then
prints the outcome and exits with a status code (0 = delivered, 3 = denied,
4 = timed out).
Click "talk to →" on any registered session, pick a recipient from the list, type your message. Recipient sees the banner the next time they have their session selected.
If you've used smux, the same surface is available — backed by the registry instead of pane labels:
agent-monitor list # every registered agent
agent-monitor id # who am I (uses $TMUX_PANE)
agent-monitor resolve backend # echo canonical agent id
agent-monitor read <recipient> [lines] # capture-pane content
agent-monitor type <recipient> "text" # type, no Enter
agent-monitor keys <recipient> Enter Escape # tmux key names
agent-monitor name <recipient> backend # set alias
agent-monitor send <recipient> "msg" # type+Enter, with confirmThese talk to the daemon over HTTP — agents written in any language (bash, Python, …) can shell out and participate.
agent-monitor ships an MCP (stdio JSON-RPC) server that both Claude Code
and Codex load, exposing six tools. Once agent-monitor install has
patched the configs, an agent can call these by name — no Bash shell-out.
| Tool | What it does |
|---|---|
who_am_i |
Returns my agent id, alias, tool, pane, cwd |
list_agents |
Lists every other registered agent (alias, tool, cwd) |
read_pane |
Captures the visible buffer of another agent's pane |
talk_to_agent |
Types a message into another agent's pane. 3 modes — see below. |
reply_to_talk |
Recipient-side: send back the answer to a wait_for_reply talk |
permission_prompt |
Routes Claude's tool-use permission prompts to the web UI |
talk_to_agent(recipient, message, confirm=false, wait_for_reply=false, wait_seconds=600)
| Mode | What happens |
|---|---|
| default | Fire-and-forget. Message lands instantly. Returns delivered. |
| wait_for_reply | Synchronous request/reply (recommended for "ask another agent a question") — see below |
| confirm | Recipient's web UI shows Allow/Deny banner; sender blocks until click |
When a model in pane B sees a message arrive in its tmux scroll like:
[talk from <sender> · REPLY-EXPECTED · talk_id=ab12cd · use reply_to_talk(talk_id="ab12cd", message=...) when done]
<the question>
…the model should: (a) actually answer the question by doing whatever work
is asked, and then (b) call the reply_to_talk MCP tool with that
exact talk_id and its answer. The sender's talk_to_agent call is
literally blocked on a Go channel waiting for that one call to fire.
If the model just types its answer normally in its own pane and never
calls reply_to_talk, the sender hangs until wait_seconds (default
600 s) expires and then sees status: timeout.
The MCP tool descriptions for talk_to_agent and reply_to_talk both
spell this out, so models that read tool docs handle it automatically.
For models that don't (or that haven't picked up the new tool yet),
include a brief instruction in the message itself:
"Please use reply_to_talk(talk_id=..., message=...) to send your answer back."
The polling-based approach ("send and watch the pane stabilize") is brittle. Use the explicit reply protocol instead:
1. SENDER calls talk_to_agent(
recipient="frontend",
message="Need the API contract for /users",
wait_for_reply=true)
2. agent-monitor types into recipient's pane:
[talk from backend · REPLY-EXPECTED · talk_id=ab12cd
· use reply_to_talk(talk_id="ab12cd", message=...) when done]
Need the API contract for /users
3. RECIPIENT (frontend agent) reads the prefix, does the work,
then calls:
reply_to_talk(talk_id="ab12cd", message="GET /users → [{id, name}]")
4. SENDER's talk_to_agent call unblocks, result contains:
"Reply from frontend (talk_id=ab12cd):
GET /users → [{id, name}]"
No polling, no stability heuristic — the recipient signals "done" themselves.
wait_seconds defaults to 600 (10 min). Multiple in-flight talks coexist
fine — each gets its own talk_id.
A typical model-driven loop:
1. who_am_i() → I'm "backend" (claude:abc…)
2. list_agents() → "frontend" (codex), "infra" (opencode)
3. talk_to_agent(recipient="frontend",
message="API contract for /users?",
wait_for_reply=true) ← blocks until they answer
4. (use the returned reply directly in subsequent reasoning)
Some recipients can't call back: a stripped-down agent without MCP, an
older session that hasn't picked up the new tool, or a model that
ignores the protocol prefix. There is no automatic polling fallback —
use read_pane(recipient=...) after a fire-and-forget talk_to_agent
to capture their output manually.
# ~/.codex/config.toml
[mcp_servers.agent-monitor]
command = "/Users/you/agent-monitor/agent-monitor"
args = ["mcp-perm-server"]To use the web-UI permission flow with Claude, also pass:
claude --permission-prompt-tool mcp__agent-monitor__permission_prompt …For Codex / opencode there's no permission-prompt-tool flag, so the bridge's
quick-key buttons (1 ↵ / y / etc.) are the answer path. The
awaiting-permission state is detected from JSONL and the row is highlighted
to point you to the right buttons.
Mostly internal, but useful if you're scripting:
| Method | Path | Notes |
|---|---|---|
| GET | /api/sessions |
snapshot of every session |
| GET | /api/session/{id}/full |
full detail (messages, tools) |
| GET | /api/health |
liveness |
| WS | /ws |
session/perm/pane/talk events |
| POST | /api/session/send/{id} |
{text, enter} → tmux |
| POST | /api/session/keys/{id} |
{keys: ["1","Enter"]} |
| POST | /api/session/cancel/{id} |
sends Ctrl-C |
| GET | /api/session/pane-view/{id} |
?lines=200 → captured buffer |
| GET | /api/session/pane/{id} |
registration info |
| POST | /api/pane/register |
hook / wrapper / manual |
| POST | /api/pane/announce |
wrapper-pending |
| GET | /api/panes |
every registered pane |
| GET | /api/tmux/panes |
every live tmux pane on system |
| DELETE | /api/pane/registration/{id} |
forget |
| POST | /api/pane/name/{id} |
{alias} set / clear |
| POST | /api/talk/request |
{fromAgent, toAgent, message} |
| POST | /api/talk/{id}/respond |
{behavior: "allow"|"deny"} (confirm flow) |
| GET | /api/talk/{id}/await |
sender long-poll (confirm flow) |
| POST | /api/talk/{id}/reply |
{message} — recipient's reply |
| GET | /api/talk/{id}/await-reply |
sender long-poll (reply flow) |
| POST | /api/permission/request |
MCP server uses this |
| POST | /api/permission/{id}/respond |
UI uses this |
Persistent state lives in ~/.agent-monitor/:
| File | Purpose |
|---|---|
panes.json |
pane registrations (so they survive daemon restart) |
talks.log |
append-only NDJSON of every talk request + outcome |
In-memory only:
| Store | Backed by |
|---|---|
| Sessions | Tail / scan adapters (see claude.go, codex.go, …) |
| Permissions | MCP server registers; UI responds; channel delivers result |
Registry vs. session store — they're decoupled on purpose. The session
store auto-decays entries (running → idle after a few minutes, idle →
completed after an hour) so the live UI stays clean. The pane registry
doesn't decay — once a registration exists, it stays drivable until the
underlying tmux pane disappears OR the user explicitly forgets it. So you
can talk_to_agent an agent whose session has aged out of the live view
as long as its tmux pane is still alive; the bridge / send / keys / talk
endpoints all consult the registry directly, never the session store.
Two optional native macOS shells around the same daemon. Both are thin
WKWebView wrappers — the UI lives in web/, so changing a page needs a daemon
rebuild, not a recompile. Neither installs a LaunchAgent; run them by hand.
AgentMonitor.app |
AgentTV.app |
|
|---|---|---|
| Page | / — the full dashboard |
/tv — compact glance board |
| Window | standard, resizable, position remembered | small, borderless, always on top, all Spaces |
| Toggle | ⌥⌘A from any app, menu-bar icon, Dock, ⌘Tab | menu-bar icon |
| For | working in | watching out of the corner of your eye |
| Daemon | bundled — the app starts it | needs one running |
| Build | ./mac/build.sh --run |
./tv/build.sh --run |
| Docs | mac/README.md | tv/README.md |
AgentMonitor.app exists because a browser tab is hard to find among thirty
others. ⌥⌘A brings the dashboard forward from anywhere and puts it away again.
The shortcut uses Carbon's RegisterEventHotKey, so macOS never asks for
Accessibility or Input Monitoring permission. Change it with
AGENT_MONITOR_HOTKEY="ctrl+opt+cmd+a", or point either app at a remote daemon
with AGENT_MONITOR_APP_URL / AGENT_TV_URL.
AgentMonitor.app also ships the daemon inside its bundle: on launch it adopts
a daemon that is already listening, or starts its own and stops it on quit. So
opening the app is the whole workflow — no terminal. It starts the daemon on
loopback only and ignores AGENT_MONITOR_BIND; use AGENT_MONITOR_APP_BIND to
expose it deliberately, or start the daemon by hand and let the app adopt it.
The remaining one-time step, agent-monitor install, is an app menu item that
asks before it edits any config.
Caveat: desktop notifications do not fire inside these shells. WKWebView does not implement the Web Notification API the dashboard uses, so it degrades to silence. Sound alerts still work; use a browser tab if you need system notifications.
The web UI collapses to single-pane navigation on phones (≤ 600 px). The top bar gets ☰ (slide-in tools rail) and ← back (return to list). Tap any session to drill into the detail + bridge view.
Tested on iOS Safari. Uses 100dvh for viewport-height so content doesn't
get clipped behind the URL bar.
agent-monitor/
├── main.go # HTTP server, subcommand routing
├── store.go # in-memory session store + WS broadcasts
├── types.go # Tool / State / Session / ServerEvent
├── claude.go # Claude hook ingest + JSONL tail
├── claude_detail.go # Per-session detail builder for Claude
├── codex.go # Codex JSONL adapter
├── codex_detail.go
├── cursor.go # Cursor IDE chat scanner
├── cursor_detail.go
├── cursoragent.go # cursor-agent process scanner
├── opencode.go # opencode JSONL adapter
├── opencode_detail.go
├── tmux.go # listTmuxPanes, send-keys helpers, capture-pane
├── pane_registry.go # pane registration + aliases + persistence
├── talk.go # talk store + delivery formatting
├── perm.go # permission request store + long-poll
├── mcp_perm.go # MCP stdio server (Claude permission prompt)
├── install_hooks.go # patches ~/.claude/settings.json
├── tail.go # tiny line-by-line file tailer
├── detail.go # session-detail dispatcher
├── util.go # path helpers
├── wrapper.go # `agent-monitor run / send / list / read / type / keys / id / name / resolve`
├── bin/
│ └── claude-hook.sh # SessionStart hook script
├── web/
│ ├── index.html # single-page web app (vanilla JS, no build step)
│ └── tv.html # compact glance board served at /tv
├── mac/ # AgentMonitor.app — dashboard as a Mac app (Swift)
│ ├── main.swift # window, menu bar, navigation policy
│ ├── hotkey.swift # Carbon global hotkey (no TCC permission needed)
│ └── build.sh # swiftc + bundle + ad-hoc codesign
├── tv/ # AgentTV.app — always-on-top glance widget (Swift)
│ ├── main.swift
│ └── build.sh
└── ios/ # SwiftUI iPhone client (Xcode project)
Something killed the agent-monitor mcp-perm-server child process the
agent CLI spawned at startup. That child is what hosts the MCP tools;
once it dies the agent CLI doesn't reconnect.
Most common cause: someone ran pkill -f /agent-monitor/agent-monitor
to restart the daemon — that pattern matches the MCP child too. Use
agent-monitor stop (kills only the listen-port owner), or restart
the agent CLI itself if the MCP child has already died.
You're on an MCP server build before commit db93449. Restart the
Claude CLI inside tmux (exit then agent-monitor run claude) to
pick up the schema-fixed binary. Codex was lenient and accepted the
old shape, which is why the bug was Claude-only.
The pane is registered but the underlying session has aged out of the
live store (~60 min idle). Pre-1f72fa4 builds gated the send
endpoints on the session store; new builds consult the registry only.
Restart the daemon to load the fix:
agent-monitor stop
AGENT_MONITOR_BIND=0.0.0.0 nohup ./agent-monitor >> agent-monitor.log 2>&1 &
The recipient never called reply_to_talk. Three possible reasons:
- The recipient agent's MCP server pre-dates
reply_to_talk(commitd0b86d0). Restart the recipient's CLI inside tmux. - The recipient model didn't recognize the REPLY-EXPECTED prefix and
just answered in its own pane. Add an instruction to the
messageitself:"Use reply_to_talk(talk_id=..., message=...) to send back." - The recipient is genuinely still working. Bump
wait_seconds.
For recipients that simply can't run reply_to_talk, fall back to a
fire-and-forget talk_to_agent followed by read_pane to capture
their output manually.
The agent was launched before the SessionStart hook deployed. Use the
empty-state picker in the bridge — it lists every live tmux pane with
cwd-matches at the top. One click registers; if there's exactly one
cwd-exact match, it auto-registers. forget cleans up a wrong pick.
Another daemon is holding the port. pkill may not have killed it
(slow signal, or you matched the wrong process). Use:
lsof -ti :7777 -sTCP:LISTEN | xargs kill…or just agent-monitor stop.
For the why behind these decisions — registered-not-inferred panes, the two-channel Talk struct, the separate-process MCP server, the failure-mode catalogue — see DESIGN.md. It's the companion document to this one: README answers "what / how to use," DESIGN answers "why is it shaped this way."
MIT.