ccwatch

🚦 ccwatch

Glanceable status tracker for concurrent Claude Code sessions.

I run a lot of Claude Code sessions in parallel. I need a way to track what each session is doing and jump to the ones that need my attention.

ccwatch uses hooks to associate a claude session with my terminal tabs and and tmux panes. It regularly updates a tweet-length summary of the session conversation so I can see at a glance what the session is doing.

Hammerspoon provides a menubar widget that reads ccwatch output files and renders session names and color-coded status:

• 🔴: waiting for user input (permission prompt, AskUserQuestion, etc.)
• 🟡: idle session, waiting for next user prompt
• 🟢: actively working

Clicking a session jumps me to the corresponding iTerm tab and tmux pane.

Quick start

1. Install the hooks.

   claude plugin marketplace add xdg/ccwatch
   claude plugin install ccwatch@ccwatch
   

2. Pick a renderer from example-renderers/ and follow its README. Each is self-contained and copy-pasteable:

   • tmux/ -- a status-right line for tmux.
   • hammerspoon-generic/ -- a terminal-agnostic menubar (display-only rows).
   • hammerspoon-iterm-tmux/ -- the menubar plus click-to-focus for iTerm2 + tmux.

3. Open a new Claude Code session and watch your renderer light up.

How it works

Claude Code hooks write state to ~/.claude/state/; tmux and Hammerspoon read it. Liveness and status come from the harness's own ~/.claude/sessions/; ccwatch adds the launch context and rolling summaries. Full design in docs/design.md.

To build your own renderer, see docs/renderers.md.

License

Apache-2.0.