cc-watch

A terminal dashboard for coding-agent sessions running inside tmux. Claude Code, Codex, Gemini CLI, opencode and pi are watched out of the box; other agents can be added.

When you have several agents working in parallel across tmux windows and panes, it is hard to tell which one is still thinking, which one is waiting for your input, and which one has quit. cc-watch polls tmux, classifies every agent pane, and lets you jump straight to the one that needs you.

  cc-watch  15:04:05

    SESSION                   STATE      LAST PROMPT
    ──────────────────────────────────────────────────────────────────────────
    CL notes                  running    rewrite the parser to accept trailing...
  > GM api:0.1                waiting    add rate limiting to the /search endpoint
    CX api:1.0                waiting    why is the integration suite flaky?
    CL docs                   idle       document the new --serve flag
    GM scratch                error      $


  ━━ GM api:0.1 · waiting ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  │ ● Edited src/search/handler.go (+42 −3)
  │ ╭──────────────────────────────────────────────────────────────────╮
  │ │ >                                                                │
  │ ╰──────────────────────────────────────────────────────────────────╯

How it works

Every 2 seconds the cc-watch daemon (see Daemon mode) runs tmux list-panes -a to enumerate every pane in every session, keeps the ones running a configured agent (claude, codex, gemini, opencode and pi by default), and inspects each of them:

  • the pane title, via tmux display-message -p '#{pane_title}'
  • the last 80 lines of output, via tmux capture-pane -p

Finding the agent behind its process name

A pane’s command is not always the agent’s name. Claude Code renames its own process, so tmux reports claude and matching it is enough. Gemini CLI does not: its executable is a plain #!/usr/bin/env node script, so every Gemini pane shows up as node — and behind a wrapper script, a pane can report the wrapper or the shell instead. No agent_commands entry can match any of those.

So when a pane’s command names no agent, cc-watch takes one ps snapshot per poll and walks the processes below that pane, looking for one whose program names a configured agent — either as the executable itself (.../bin/gemini) or as the installed package it was exec’d from (.../node_modules/@google/gemini-cli/dist/index.js).

Codex lands on both sides of this. Installed from Homebrew, cargo or the install script it is a native binary that renames nothing, so its pane already reports codex; installed from npm it is the same #!/usr/bin/env node shim story as Gemini, with node running .../node_modules/@openai/codex/bin/codex.js and that spawning the platform binary underneath (.../node_modules/@openai/codex-linux-x64/vendor/<target>/bin/codex). Both of those are found by the same walk.

opencode is a native binary whichever way it is installed, so it usually needs no walk at all: its pane reports opencode and matching that is enough. The one exception is an npm install, which lays the binary down under its own package directory (.../node_modules/opencode-ai/bin/opencode.exe) — that path is matched the same way an installed package is for the agents above.

pi is installed from npm and run by node, the same shape as Gemini CLI: a pane may report node, and the walk finds either the .../bin/pi shim or the script it runs, .../node_modules/@mariozechner/pi-coding-agent/dist/cli.js.

An argument only counts if it is an agent’s executable or an installed agent package, so a pane running node server.js from a directory named codex-experiments, or passing a gemini.json config, is not mistaken for an agent. The snapshot is lazy — panes that name their own agent never trigger it — and taken at most once per poll.

From those two signals it derives a state:

StateColourMeaning
...greyPane seen for the first time; held until enough output has been observed to classify
runningyellowThe agent is working — a braille spinner in the pane title, or output still changing
waitinggreenThe agent is sitting at its input and nothing has changed for 5 seconds. Two shapes are recognised: the box Gemini CLI and older Claude Code builds draw around the input, and the bare marker line Codex and newer Claude Code builds use instead
idleyellowOutput has been unchanged for 5 seconds with no input on screen
errorredThe tail of the pane is a bare shell prompt — the agent exited
unknowngreyThe pane is empty

“Output” here means the agent’s own: the transcript above its input. What you type into the input box, and the hints the footer shows as you type, are left out, so typing a prompt does not make a waiting agent look like it is running (or, once you stop, set off its bell).

A long thinking phase can leave a braille spinner as the only thing moving on screen, sometimes in the status lines under the input, which are left out above. And a spinner whose turn takes exactly a second shows the same frame at every 2-second poll, so it looks frozen. So when a pane shows a spinner and nothing else has changed, cc-watch looks again 150ms later: a frame that has moved on means the agent is working. A spinner frozen by a crashed agent does not, and neither does braille that is part of the output.

Each row is marked with the agent running in it — CL for Claude Code, CX for Codex, GM for Gemini CLI, OC for opencode — so a screen of mixed sessions stays readable. The mark rides at the front of the session column rather than taking a column of its own, so it costs the LAST PROMPT text nothing. An agent with no mark of its own is marked with its uppercased initial, and agent_icons overrides any of them.

The marks are two-letter ASCII codes, which is exactly two columns in every monospace terminal — so the rows always line up, and each mark names its agent outright. A single glyph per agent was tried first and dropped: the “agent star” dingbats render at different weights and widths from one font to the next (some draw them double-width), and four near-identical stars were hard to tell apart. If you would rather have a glyph, set one — agent_icons takes any string:

{ "agent_icons": { "claude": "✻", "opencode": "◆" } }

The LAST PROMPT column shows the last thing you asked that agent to do. A pane’s tail tells you little — mid-turn it is a spinner, and at rest it is the mode-hint footer, which reads the same for every agent — whereas the prompt is what actually distinguishes one session from another when four of them are idle at once.

It is read from the transcript, where a submitted prompt is a line opening with a prompt glyph at column 0 — ASCII > in older Claude Code builds, a chevron in the newer borderless UI, › in Codex — so a small family of glyphs is matched rather than one. The two-space-indented continuations both Claude Code and Codex wrap long prompts onto are joined back on, so a multi-line prompt survives as far as the column width.

Text typed but not yet sent is deliberately excluded. In the borderless UI the live input carries the same glyph as a submitted prompt, so shape cannot separate them — the same is true of Codex, whose composer is a › carrying placeholder text — but it is always the bottom-most one on screen, which is anchor enough: above it is transcript, below it is only the footer. The older UI walls its input off inside a box instead, so whichever turns up first scanning up from the footer, a box border or a bare glyph, marks the bottom of the input region. pi has neither: its editor sits between two horizontal rules, above a cwd line and a token/cost/model statusline, so when no box or glyph is found the upper rule of the bottom-most pair is taken as the bottom of the transcript instead. pi marks a submitted prompt only by its background colour, which a plain capture does not carry, so for pi the column shows the last line of the transcript.

Once seen, a prompt is kept: a long turn pushes it out of the captured window well before the agent is done, and blanking the column for the rest of the turn would defeat the point. When a pane is first noticed cc-watch does one deeper capture (promptScrollback, 400 lines) looking for the prompt of a turn already in flight, so agents that were running before you started the dashboard are not blank either.

If no prompt can be found at all, the column falls back to the last non-decorative line of the pane, with ANSI escapes and box-drawing characters stripped.

Panes that disappear are dropped from the list on the next refresh. When a single tmux session contains more than one agent pane, the display switches from the bare session name to the full session:window.pane key so the rows stay unambiguous.

Requirements

  • tmux
  • Go 1.25 or newer (to build)

Install

go install github.com/clobrano/cc-watch@latest

Or build from a clone:

git clone https://github.com/clobrano/cc-watch
cd cc-watch
go build -o cc-watch .

Usage

cc-watch
KeyAction
↑ / ↓Move the selection
↵ (Enter)Attach to the selected pane’s session
bTurn the bell on or off for the selected session
pShow or hide the preview
q / Ctrl-CQuit

Below the list, the dashboard previews the last lines of the selected pane (30 by default, see preview_lines), input box and footer included, in the pane’s own colours. An empty input box at the bottom is the quickest way to tell that an agent is done. The preview’s rule and left gutter take the colour of the selected row’s state, which sets it apart from the list. The preview shrinks to fit the terminal height, and is left out when fewer than 3 lines fit.

The session column widens to fit the longest name, from 24 up to 40 columns, but never so far that the prompt column drops below 30 columns.

Attaching adapts to where you are running from:

  • Inside tmux, it uses tmux switch-client, so the jump is instant and cc-watch keeps running in the pane you left.
  • Outside tmux, it suspends the TUI, runs tmux attach-session, and resumes the dashboard once you detach.

The TUI uses the alternate screen buffer, so your scrollback is left intact, and it adapts to terminal resizes.

The dashboard does no polling of its own: it is a client of the daemon, and if none is running it starts one first. It receives the daemon’s current view the moment it connects, so it opens on the real state rather than a screen of ... rows, and any number of dashboards can be open at once on the same poller. Quitting a dashboard leaves the daemon running.

Flags

FlagAction
(none)Run the interactive dashboard, starting the daemon if it is not running
--serveStart the background daemon without opening a dashboard
--stop-serverStop the running daemon
--doctorReport what cc-watch sees in every pane, then exit — see Troubleshooting
--notify-testSend a test desktop notification the way the daemon would, and report any error

Notifications

Press b on a session to turn on its bell; the row is marked with a dim ◇ in the left margin (see Icons for other symbols). When a session with the bell on finishes a turn, going from running to waiting, you get a desktop notification titled after the session — “notes is waiting”, or “notes:0.1 is waiting” when that tmux session has more than one agent pane — with its last prompt as the body.

The notification waits until the session has stayed waiting for notify_after seconds (10 by default). That comes on top of the 5 seconds of unchanged output the classifier already needs before it calls a pane waiting, so a pause in the middle of a turn does not set off the bell for an agent that is about to carry on. Each turn sends one notification. Turning the bell on for a session that has been waiting for a while does not send one; the next finished turn does.

Until you get to it, the session is flagged in the dashboard: the mark turns into a bold ◆.

◇   CL api                    running    add rate limiting to the /search endpoint
◆ > CL notes                  waiting    fix the parser

The flag clears as soon as you have been to the session: when it is on screen in tmux (the active pane of the active window of an attached session), when you attach to it from the dashboard, when it starts running again because you answered it from elsewhere, or when you turn its bell off.

The bell belongs to the daemon, not the dashboard, so the notification arrives whether or not a dashboard is open. Bells last as long as the daemon and the pane: restarting the daemon, or closing the pane, turns them off.

Icons

The icons setting picks the symbols the margin is drawn with:

iconsBell onNot seen yetNeeds
unicode (default)◇◆Nothing: DejaVu Sans Mono (and Hack and Menlo, which derive from it), JetBrains Mono, Liberation Mono and FreeMono all have them, and DejaVu is the fallback font on nearly every Linux system
nerd````A Nerd Font, or the symbols-only Nerd Font installed as a fallback. These are Font Awesome’s bell outline (U+F0A2) and bell (U+F0F3), which kept their codepoints from Nerd Fonts v2 to v3
asciio!Nothing at all

cc-watch cannot bring a font of its own: the terminal draws with the fonts of the machine it runs on, and no terminal can tell an application whether a symbol actually rendered, so a missing glyph would just be a box. cc-watch --doctor draws all three sets, so you can see which ones your font has before you pick.

Notifiers

The daemon sends notifications with the first of these it finds:

NotifierWhere
notify_commandYour own command, if configured — see Configuration
osascriptmacOS
notify-sendLinux and BSD: the freedesktop notification service, which KDE Plasma, GNOME, XFCE, dunst, mako and others provide
gdbusThe same service, called directly, for systems without notify-send (part of GLib, so almost always present)
tmux display-messageLast resort: a message in the tmux status line

Run cc-watch --notify-test to check that notifications reach your desktop, and cc-watch --doctor to see which notifier was picked. The daemon has to reach your desktop’s session bus: started from a terminal in your desktop session it inherits DBUS_SESSION_BUS_ADDRESS, but a daemon started some other way (an SSH login, a service without the user’s session environment) may not, and then logs the failure to daemon.log.

notify_command covers anything else — a phone push through ntfy, WSL, a sound:

{ "notify_command": ["ntfy", "publish", "--title", "{title}", "my-topic", "{body}"] }

tmux status bar

While it runs, the cc-watch daemon publishes a compact strip of every agent it has found to the tmux user option @cc_watch_agents — one number per agent, coloured by the same states as the dashboard. It is nothing but an option until you reference it, so add it wherever you want in your .tmux.conf:

set -ag status-right ' #{@cc_watch_agents}'
set -g  status-right-length 60

-a appends rather than replacing, so your existing clock and hostname survive. The length bump matters: status-right-length defaults to 40 and tmux truncates past it silently, so on a busy status line the agent digits are exactly what falls off the end — which looks like the feature not working. Put it on the left instead if you prefer, but raise the limit there too, as status-left-length defaults to just 10:

set -ag status-left ' #{@cc_watch_agents}'
set -g  status-left-length 40

Reload with tmux source-file ~/.tmux.conf. You do not need to touch status-interval — cc-watch redraws clients itself when the strip changes.

You then get an at-a-glance indicator from any session:

                                              AGENTS 1 2 3
                                                     │ │ └─ green:  waiting on you
                                                     │ └─── grey:   idle
                                                     └───── yellow: running

The numbers are positional over the same sorted list the dashboard renders, so agent 2 in the status bar is row 2 in the TUI — the TUI is the legend that tells you which session that is. Because they are positional, they renumber whenever an agent pane appears or dies: a number is a pointer to a row, not a durable handle on a session.

The strip is pushed on each 2-second poll, but the option is only rewritten (and clients only redrawn, via refresh-client -S) when the rendered string actually changes. When the daemon stops it unsets the option, so a frozen strip never lingers in your status bar — which also means the indicator is live only while the daemon is running. Opening the dashboard once starts it; to have it from the moment tmux comes up, see Daemon mode.

To check the strip is live while the daemon is running, read the raw option:

$ tmux show-options -gqv @cc_watch_agents
#[fg=yellow]1 #[fg=green]2#[default]

Empty output means either cc-watch is not running or it found no agents.

Why it has to work this way: classification is history-dependent. idle and waiting mean “unchanged for 5 seconds”, which is only knowable by comparing consecutive polls. A one-shot #(cc-watch --status) invoked by tmux would start cold every time and could only ever distinguish running from error.

Daemon mode

All the polling happens in one background process, the daemon. It publishes the tmux status strip and serves every open dashboard over a Unix socket. Running cc-watch starts it on demand; --serve starts it without opening a dashboard, which is all the status strip needs.

$ cc-watch --serve
cc-watch daemon started (pid 48213)
$ cc-watch --stop-server
cc-watch daemon stopped (pid 48213)

--serve re-executes cc-watch in a new session (setsid), so the daemon outlives the shell that started it, and returns only once the child is accepting connections — if it fails to start you get an error instead of a silent no-op. --stop-server sends SIGTERM and waits for it to exit; the daemon unsets @cc_watch_agents on the way out, so the strip disappears with it.

Only one daemon runs at a time. A second --serve reports the running pid and exits non-zero rather than starting a rival poller.

Put it in your .tmux.conf to have the strip come up with tmux itself:

run-shell -b 'cc-watch --serve'

-b keeps tmux from blocking on it, and starting it twice is harmless — the second call sees the first daemon and exits.

Dashboards connect to the daemon’s socket and receive one JSON snapshot per line: the latest one immediately on connect, then a fresh one after every poll. The stream is one-way and fans out to every client, so ten open dashboards cost tmux no more than one. A dashboard that stops reading is dropped after a few seconds rather than holding the daemon up. If the daemon goes away underneath a dashboard, the dashboard exits with lost connection to the daemon.

After upgrading cc-watch, restart a daemon left over from an older build with cc-watch --stop-server: one that predates dashboard support has no socket, and the dashboard says so rather than starting a second poller beside it.

State lives in $XDG_RUNTIME_DIR/cc-watch/ (falling back to $TMPDIR/cc-watch-$UID/):

FileContents
daemon.pidThe daemon’s pid, and the lock file that makes “running” knowable
daemon.sockThe socket dashboards connect to
daemon.logDaemon start/stop lines — the first place to look if --serve fails

Liveness is an advisory lock (flock) on the pid file, not the pid itself. The kernel drops the lock when the holder dies, so a daemon that is SIGKILLed leaves nothing stale to clean up: the next --serve just starts, and --stop-server correctly reports that nothing is running instead of signalling whatever process happens to have inherited that pid.

systemd

The daemon is per-user and needs $XDG_RUNTIME_DIR, so it belongs in a user unit, not a system one. Write ~/.config/systemd/user/cc-watch.service:

[Unit]
Description=cc-watch tmux status daemon

[Service]
Type=forking
PIDFile=%t/cc-watch/daemon.pid
ExecStart=%h/go/bin/cc-watch --serve
ExecStop=%h/go/bin/cc-watch --stop-server
Restart=on-failure

[Install]
WantedBy=default.target
systemctl --user daemon-reload
systemctl --user enable --now cc-watch

Type=forking is the right description: --serve starts the daemon and exits, leaving the child behind. %t expands to $XDG_RUNTIME_DIR, which is exactly where the pid file lands, so systemd tracks the daemon rather than the launcher. Adjust %h/go/bin/cc-watch if the binary lives elsewhere.

Troubleshooting

An agent does not show up

Run cc-watch --doctor. It lists every tmux pane with the command tmux reports for it and the agent cc-watch resolved, and for each pane it did not recognise it prints the processes running underneath — so the program that should have been matched can be read straight off:

$ cc-watch --doctor
cc-watch doctor

config:  /home/u/.config/cc-watch/config.json (absent) — built-in defaults
agents:  claude, codex, gemini, opencode, pi

PANE                      COMMAND         PID       AGENT
------------------------------------------------------------------------
work:0.0                  node            1855      gemini (process tree)
work:1.0                  claude          1864      claude (pane command)
work:2.0                  node            1874      -
work:3.0                  codex           1902      codex (pane command)
work:4.0                  opencode        1918      opencode (pane command)

4 pane(s) recognised as agents.

Processes under the panes that were not recognised. ...

  work:2.0 (node):
    1874     -bash
    2301     node /home/u/app/server.js

The two usual causes:

  • A config file from before the agent was supported. agent_commands replaces the defaults rather than adding to them, so a file listing only ["claude"] keeps Codex, Gemini, opencode and pi panes out no matter what. --doctor prints the file in force and the agents it yields, and names any built-in agent the file has dropped.
  • An install layout that is not matched. If the doctor shows the agent’s process under an unrecognised pane but does not name it, its path is one cc-watch does not know: open an issue with that line.

Configuration

Configuration is optional. To override the defaults, create ~/.config/cc-watch/config.json:

{
  "agent_commands": ["claude", "codex", "gemini", "opencode", "pi", "aider"],
  "agent_icons": { "aider": "a" },
  "preview_lines": 30,
  "notify_after": 10,
  "icons": "unicode",
  "shell_prompts": ["$", "#", "%", "❯", "→", "λ"]
}
KeyDefaultDescription
agent_commands["claude", "codex", "gemini", "opencode", "pi"]Agents to watch. Matched case-insensitively against the pane command (#{pane_current_command}) and, for interpreter panes, against the program running below the pane. Add entries to watch other agent CLIs.
agent_icons{"claude": "CL", "codex": "CX", "gemini": "GM", "opencode": "OC", "pi": "PI"}The mark shown before a session name, per agent. Two-letter ASCII codes by default, so the rows line up in any terminal; set any string (a glyph, a single letter) to override. Unlike the other keys this is merged over the defaults rather than replacing them, so naming one agent leaves the rest alone. An agent with no mark of its own gets its uppercased initial.
preview_lines30How many of the selected pane’s last lines the preview shows, at most 60. The terminal height can show fewer.
notify_after10Seconds a session with the bell on must stay waiting before the notification is sent.
notify_command(none)A command to send notifications with instead of the built-in notifier, as an argument list; {title} and {body} are replaced in each argument.
icons"unicode"The symbols for a session with the bell on and one with a notification not seen yet: unicode, nerd or ascii — see Icons.
shell_prompts["$", "#", "%", "❯", "→", "λ"]Line suffixes that identify a bare shell prompt. Used to detect that an agent has exited into the shell (error state).

Any key may be omitted; a missing or empty list falls back to its default. If the file is absent or cannot be parsed, all defaults are used.

Tuning

The polling and classification constants are compile-time values at the top of main.go:

refreshInterval  = 2 * time.Second  // how often tmux is polled
idleThreshold    = 5 * time.Second  // unchanged output before idle/waiting
paneLines        = 80               // lines of scrollback captured per pane
promptScrollback = 400              // one-off deeper capture, to find the prompt
                                    // of a turn already running when a pane is
                                    // first seen

License

See the repository for license information.