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:
| State | Colour | Meaning |
|---|---|---|
... | grey | Pane seen for the first time; held until enough output has been observed to classify |
running | yellow | The agent is working — a braille spinner in the pane title, or output still changing |
waiting | green | The 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 |
idle | yellow | Output has been unchanged for 5 seconds with no input on screen |
error | red | The tail of the pane is a bare shell prompt — the agent exited |
unknown | grey | The 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
| Key | Action |
|---|---|
↑ / ↓ | Move the selection |
↵ (Enter) | Attach to the selected pane’s session |
b | Turn the bell on or off for the selected session |
p | Show or hide the preview |
q / Ctrl-C | Quit |
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 andcc-watchkeeps 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
| Flag | Action |
|---|---|
| (none) | Run the interactive dashboard, starting the daemon if it is not running |
--serve | Start the background daemon without opening a dashboard |
--stop-server | Stop the running daemon |
--doctor | Report what cc-watch sees in every pane, then exit — see Troubleshooting |
--notify-test | Send 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:
icons | Bell on | Not seen yet | Needs |
|---|---|---|---|
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 |
ascii | o | ! | 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:
| Notifier | Where |
|---|---|
notify_command | Your own command, if configured — see Configuration |
osascript | macOS |
notify-send | Linux and BSD: the freedesktop notification service, which KDE Plasma, GNOME, XFCE, dunst, mako and others provide |
gdbus | The same service, called directly, for systems without notify-send (part of GLib, so almost always present) |
tmux display-message | Last 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.
idleandwaitingmean “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 distinguishrunningfromerror.
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/):
| File | Contents |
|---|---|
daemon.pid | The daemon’s pid, and the lock file that makes “running” knowable |
daemon.sock | The socket dashboards connect to |
daemon.log | Daemon 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_commandsreplaces the defaults rather than adding to them, so a file listing only["claude"]keeps Codex, Gemini, opencode and pi panes out no matter what.--doctorprints 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": ["$", "#", "%", "❯", "→", "λ"]
}
| Key | Default | Description |
|---|---|---|
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_lines | 30 | How many of the selected pane’s last lines the preview shows, at most 60. The terminal height can show fewer. |
notify_after | 10 | Seconds 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.