jeremyinthebay/claude-watcher — explained in plain English
Analysis updated 2026-05-18
Check at a glance whether a long-running Claude Code session is stuck or still working.
Watch multiple agent sessions and their subagents from a single dashboard.
Get a menu bar signal when a background session needs your attention.
| jeremyinthebay/claude-watcher | 0xallam/my-recipe | 0xhassaan/nn-from-scratch | |
|---|---|---|---|
| Stars | 0 | — | 0 |
| Language | Python | Python | Python |
| Last pushed | — | 2022-11-22 | — |
| Maintenance | — | Dormant | — |
| Setup difficulty | easy | moderate | moderate |
| Complexity | 2/5 | 2/5 | 4/5 |
| Audience | developer | general | developer |
Figures from each repo's GitHub metadata at analysis time.
Mac only, the optional menu bar icon needs the free SwiftBar app.
Claude Watcher is a small tool for Mac users who run Claude Code or Cowork sessions and want to know, at a glance, whether those sessions are actually working or stuck. Instead of asking a session how it is doing, which can be unreliable since a stalled session cannot answer for itself, the tool watches from the outside. Every sixty seconds it checks two things: whether a session's files are still being written, and what the latest line in that session's on disk transcript says. From that it can tell you what each agent, and any of its subagents, is doing right now, who it is, how long it has been running, and how many tokens it has used. The project gives you three ways to see this information. A dashboard, saved as a local HTML file, shows one card per session with filters for working, quiet, idle, or command line sessions, along with an hourly activity chart. A menu bar icon, built with the free SwiftBar app, shows a simple colored dot so you can check status without opening anything. A status.json file exposes the same data in machine readable form for anyone who wants to build their own view. It covers both Cowork desktop agent sessions and Claude Code command line runs. Sessions that run in Anthropic's own cloud sandbox are not visible, since they leave no files on your local disk. Setup requires a Mac and takes two commands: cloning the repository and running the install script, which sets up a background job and prints the dashboard's file path. The menu bar piece is optional and needs SwiftBar installed separately. The tool itself is a short, roughly 250 line Python script with no external dependencies, and it spends no AI tokens because it only reads files that already exist on disk. The project also ships a set of written prompts that can rebuild the same dashboard and menu bar system from scratch inside a Claude session, along with notes on mistakes to avoid while doing so. It is released under the MIT license and is part of a larger set of tools called relay skills by the same author.
A zero-dependency Mac tool that watches Claude Code and Cowork sessions from outside, showing live status in a dashboard and menu bar icon.
Mainly Python. The stack also includes Python, Bash, SwiftBar.
Use freely for any purpose, including commercial use, as long as you keep the copyright notice.
Setup difficulty is rated easy, with roughly 5min to a first successful run.
Mainly developer.
This repo across BitVibe Labs
Verify against the repo before relying on details.