Summary
Proposal to standardise claude-watch as a estate-tool spec under the claude-integrations umbrella, with the current implementation at `~/.local/bin/claude-watch` (installed 2026-05-28) as the reference.
Problem
When a Claude (or any AI) session spawns a long-running background task (batch fix, estate scan, large refactor walker), the user has no consistent way to monitor progress in real time. They end up running ad-hoc `tail -f /tmp/...` commands per task, often after asking the assistant "is it done yet?" — wasted credit + broken flow.
Proposed solution
A single user-invokable command, `claude-watch`, that auto-discovers any active AI-session tracker files under `/tmp/` and surfaces them in a refreshing dashboard. Idempotent, no per-task registration, designed to be invoked from any terminal at any time, including a second terminal next to the assistant's primary one.
Discovery contract
`claude-watch` looks for these patterns in `/tmp/` (max-depth 2), modified within the last 10 minutes:
- `*progress.log` — line-per-event progress journals
- `*_results.tsv` / `*results.tsv` — outcome inventories (follows the canonical four-term vocabulary documented in `hyperpolymath/standards docs/BATCH-FIX-OUTCOME-CATEGORISATION.adoc` — companion PR linked below)
- `.out` — Claude Code background-task output files (matches the `/tmp/claude-/tasks/.output` convention automatically)
For `*_results.tsv` files it renders the canonical outcome breakdown (`cut -f4 | sort | uniq -c`). For everything else it shows the last 3 lines.
Modes
```
claude-watch # dashboard (default) — refreshes every 2s via watch(1)
claude-watch -t # tail mode — streams new lines from all discovered trackers
claude-watch -f PATH # watch a specific file
claude-watch -l # list candidates and exit (no follow)
claude-watch -h # help
```
What an AI session has to do to participate
Nothing manual. The patterns are common defaults. Any session that:
- writes a progress log to `/tmp/_progress.log`
- writes results to `/tmp/_results.tsv` using the canonical four-term `outcome` column
- uses Claude Code's `run_in_background` task convention
…gets surfaced automatically. No registry, no daemon, no API.
Reference implementation
Currently installed at `~/.local/bin/claude-watch` (~150 lines bash, depends on `watch`, `find`, `tail`, `stat`, `cut`, `uniq`). Will attach the file to this issue or a follow-up PR.
Suggested estate integrations
- Shell alias: `alias cw=claude-watch` in `~/.bashrc` (one-keystroke invocation).
- tmux binding: `bind-key C-w split-window -h 'claude-watch'` (Ctrl-b Ctrl-w pops a side pane).
- VS Code task: "Run Task" entry that opens `claude-watch -t` in the integrated terminal.
Companion PRs / refs
- `hyperpolymath/standards` PR — adds `docs/BATCH-FIX-OUTCOME-CATEGORISATION.adoc` defining the canonical `outcome` column vocabulary that this tool consumes. Link will be added once the PR opens.
- Memory references in user auto-memory: `reference_claude_watch_dashboard.md`, `feedback_batch_fix_outcome_categorisation.md`.
Acceptance criteria
Background
Surfaced 2026-05-28 during the BP008 phantom-context estate fix sweep. The user explicitly requested "a Claude watcher dialogue box that is a button I can press to surface for the watchers that thing and watch on loop in real time whenever I ask any Claude (or ideally any AI) when I want it." `claude-watch` is the minimum-viable terminal-side realisation of that request.
🤖 Generated with Claude Code
Summary
Proposal to standardise
claude-watchas a estate-tool spec under the claude-integrations umbrella, with the current implementation at `~/.local/bin/claude-watch` (installed 2026-05-28) as the reference.Problem
When a Claude (or any AI) session spawns a long-running background task (batch fix, estate scan, large refactor walker), the user has no consistent way to monitor progress in real time. They end up running ad-hoc `tail -f /tmp/...` commands per task, often after asking the assistant "is it done yet?" — wasted credit + broken flow.
Proposed solution
A single user-invokable command, `claude-watch`, that auto-discovers any active AI-session tracker files under `/tmp/` and surfaces them in a refreshing dashboard. Idempotent, no per-task registration, designed to be invoked from any terminal at any time, including a second terminal next to the assistant's primary one.
Discovery contract
`claude-watch` looks for these patterns in `/tmp/` (max-depth 2), modified within the last 10 minutes:
For `*_results.tsv` files it renders the canonical outcome breakdown (`cut -f4 | sort | uniq -c`). For everything else it shows the last 3 lines.
Modes
```
claude-watch # dashboard (default) — refreshes every 2s via watch(1)
claude-watch -t # tail mode — streams new lines from all discovered trackers
claude-watch -f PATH # watch a specific file
claude-watch -l # list candidates and exit (no follow)
claude-watch -h # help
```
What an AI session has to do to participate
Nothing manual. The patterns are common defaults. Any session that:
…gets surfaced automatically. No registry, no daemon, no API.
Reference implementation
Currently installed at `~/.local/bin/claude-watch` (~150 lines bash, depends on `watch`, `find`, `tail`, `stat`, `cut`, `uniq`). Will attach the file to this issue or a follow-up PR.
Suggested estate integrations
Companion PRs / refs
Acceptance criteria
Background
Surfaced 2026-05-28 during the BP008 phantom-context estate fix sweep. The user explicitly requested "a Claude watcher dialogue box that is a button I can press to surface for the watchers that thing and watch on loop in real time whenever I ask any Claude (or ideally any AI) when I want it." `claude-watch` is the minimum-viable terminal-side realisation of that request.
🤖 Generated with Claude Code