A live sidecar UI for Claude Code — and any other AI coding CLI — that shows what's being edited, what's being built, and what just changed, in real time.
When you run Claude Code (or Codex CLI, Cursor, Windsurf, Aider, or just yourself
in vim), claude-watch shows a separate terminal window with:
- A live spinner with elapsed time, in Claude's signature orange — so you can see what it's doing right now, not just that it's doing something.
- A scrollable list of every file that's been touched, with icons and line
counts (
✎ Edit src/foo.ts +12 -3). - A side panel with rich, colored diffs rendered by delta.
- A build/test panel that captures the output of build-like Bash commands
(
pnpm build,cargo test,docker build, etc.). - A status bar that updates every second with totals: events, line changes, per-tool counts, time since last activity.
Each project gets its own logs and its own tmux session — run two agents in two different projects simultaneously without their events mixing.
Claude Code's TUI is great, but when it's churning through a long task you only see scrolling text. You can't easily tell:
- "Wait, did it actually edit the file I thought it would?"
- "How long has this build been running?"
- "What changed in the last 5 minutes — can I scroll back?"
claude-watch answers all three at a glance.
It also works with any tool that touches your filesystem, not just Claude Code. If you alternate between Claude, Codex CLI, Cursor, and manual edits, they all show up in the same timeline (with a different icon).
| Tool | Why | macOS | Linux |
|---|---|---|---|
tmux |
The split-pane layout | brew install tmux |
apt install tmux |
jq |
Hook payload parsing | brew install jq |
apt install jq |
delta |
Pretty diffs | brew install git-delta |
releases |
bat |
Syntax-highlighted log viewing | brew install bat |
apt install bat |
fswatch |
Capturing edits from other CLIs | brew install fswatch |
apt install fswatch |
git clone https://github.com/leninejunior/claude-watch.git
cd claude-watch
./install.shThe installer copies the CLI scripts to ~/bin/, copies the hook scripts to
~/.claude/hooks/, and registers them in ~/.claude/settings.json. It backs
up your settings before patching.
If you'd rather see what goes where, the install does exactly three things:
- Copies
bin/*→~/bin/ - Copies
hooks/*.sh→~/.claude/hooks/ - Appends two entries to
~/.claude/settings.json:{ "hooks": { "PreToolUse": [{ "matcher": "Edit|MultiEdit|Write|NotebookEdit|Bash", "hooks": [{ "type": "command", "command": "$HOME/.claude/hooks/pre-tool-tracker.sh" }] }], "PostToolUse": [{ "matcher": "Edit|MultiEdit|Write|NotebookEdit|Bash", "hooks": [{ "type": "command", "command": "$HOME/.claude/hooks/post-tool-tracker.sh" }] }] } }
cd ~/dev/your-project
claude-watchThis opens a tmux session with four panes:
┌── ⠋ in-flight ────────────┬──────────────────────────────┐
│ ✱ Editing src/foo.ts 3s ▌│ │
├── touched files ──────────┤ live diffs (delta) │
│ [11:32:14] ✎ Edit ... │ diff --git a/foo b/foo │
│ [11:32:18] ✚ Write ... │ -const x = 1 │
│ [11:32:25] ⚡ pnpm build │ +const x = 10 │
├── build/test ─────────────┤ │
│ ✓ Compiled in 12.3s │ │
└───────────────────────────┴──────────────────────────────┘
⌘ your-project │ ● 47 events │ ✎32 ✚8 ⟳7 ⚡3 │ +234 -89 │ last 2s
Scroll with the mouse wheel in any pane (50k lines of history).
Ctrl+B then [ enters tmux copy mode for vi-style navigation; q exits.
claude-watch listShows every project with logs, when the last event happened, total events, and a
● marker for projects with an active tmux session:
PROJETO ATIVIDADE EVENTOS PATH
---------------------------------------- ---------- -------- ----------------------------------------
● flying-fox-bob 14:32 147 /Users/you/dev/flying-fox-bob
op-vende-td 09:01 23 /Users/you/dev/op-vende-td
monitora yesterday 8 /Users/you/dev/monitora
claude-watch # attach the panel for $PWD
claude-watch attach [path] # attach (path optional)
claude-watch list # show all tracked projects
claude-watch reset [path] # zero out logs for a project
claude-watch tail [path] # touched-files only, no tmux
claude-watch diff [path] # diffs only, no tmux
claude-watch build [path] # builds only, no tmux
claude-watch kill [path] # stop tmux session + watcher for a project
claude-watch nuke # destroy ALL logs (asks first)
claude-watch --help # full help
When Claude uses Edit, MultiEdit, Write, NotebookEdit, or Bash, the
PostToolUse hook writes a colored event to the touched-files log and a unified
diff to the diff log:
| Tool | Icon | Color | Captured |
|---|---|---|---|
Edit |
✎ |
yellow | Path, +N/-N, unified diff |
Write |
✚ |
green | Path, line count, full content |
MultiEdit |
⟳ |
cyan | Path, # of edits, combined diff |
NotebookEdit |
♪ |
magenta | Path |
Bash |
⚡ |
red | Command + output (build-ish only) |
The PreToolUse hook updates a current.txt file so the spinner pane can
show "Editing src/foo.ts (3s)" with elapsed time, in real time, before the
Edit completes.
A separate fswatch process runs alongside the tmux session and watches the
project directory. Any file modified by Codex CLI, Cursor, Windsurf, Aider, vim,
or your build system shows up as:
[11:32:14] ✦ External src/foo.ts
If the project is a git repo, the diff panel shows git diff output for the
file. The hook and the FS watcher deduplicate within a 3-second window so a
Claude edit doesn't appear twice.
┌──────────────────────────┐
Claude Code session ───────▶ │ PreToolUse hook │ writes current.txt
│ PostToolUse hook │ writes touched/diffs/builds + stats
└──────────┬───────────────┘
│
▼
Codex / Cursor / vim ──▶ fswatch ──▶ external-watcher.sh ──▶ touched + diffs
│
▼
~/.claude/watch-logs/<project-key>/
├── touched.log
├── diffs.log
├── builds.log
├── stats.json
├── current.txt
├── recent-files.txt (dedup window)
└── watcher.pid (fswatch process)
│
▼
┌───────────────────────────────┐
│ tmux session "cw-<key>" │
│ • spinner pane (animation) │
│ • touched log pane │
│ • diff pane (via delta) │
│ • build pane │
│ • status bar (per-second) │
└───────────────────────────────┘
Project key = <basename>-<sha1[0:8] of absolute path>. So
~/dev/foo and ~/old/foo get distinct buckets even though they share a name.
| Env var | Default | What it does |
|---|---|---|
CLAUDE_WATCH_DIR |
$HOME/.claude/watch-logs |
Where logs live |
CLAUDE_WATCH_SESSION |
cw-<project-key> |
tmux session name |
CLAUDE_PROJECT_DIR |
(set by Claude Code) | Used as project root if not in payload |
- Build output is post-completion only. Hooks fire after a Bash command finishes, so you don't see streaming progress in the build pane. The full output is captured once it's done. (True streaming would need to intercept Claude Code's tool execution, which hooks can't do.)
- External-only diffs need git. Without a git repo, the
✦ Externalevent shows the path but not what changed. - FS watcher needs
fswatch. If it's not installed, only Claude Code events are tracked. The launcher prints a warning.
PRs welcome. Some ideas:
- Linux-native install path (currently assumes Homebrew on macOS for caveats).
- Sound effects / system notifications on build failure.
- A web dashboard that aggregates multiple projects.
- Adapters for tools beyond Claude Code (Aider events, OpenCode hooks).
MIT — see LICENSE.