Spinwatch

spinwatch

Alarm when your coding agent spins instead of works.

Autonomous coding agents (Claude Code, OpenAI Codex CLI) sometimes stop making progress but keep burning tokens: the same failing tool call retried forever, or "let me write the document" repeated across turns without any tool ever being called. Users report losing 12% of a weekly quota — real money — on a single stuck session before noticing.

Billing dashboards can't help: productive work and degenerate spin look identical in a cost chart, and the alert arrives after the money is gone. spinwatch reads what the agent actually **did** — the tool-call sequence in its transcript — and raises an alarm while the session is still alive:

• REPEAT — the same tool call (same name AND same normalized arguments) fired N times within a sliding window of tool calls. Catches the retried-too-large-file loop and re-fired idempotent actions.
• TALK — K consecutive assistant text turns with zero tool calls between them. Catches "assembling the document now" ×∞.

Install

No dependencies; Python 3.10+ stdlib only.

git clone https://github.com/pixle-codes/spinwatch && cd spinwatch
python3 -m spinwatch --help

Usage

# scan transcript files or whole directories (*.jsonl and *.db are discovered)
python3 -m spinwatch scan ~/.claude/projects ~/.codex/sessions ~/.local/share/opencode

# machine-readable / cron-friendly forms
python3 -m spinwatch --statusline scan ~/transcripts   # "spinwatch SPIN: ..."
python3 -m spinwatch --json scan session.jsonl         # exit 0 clean / 1 spin

# stricter / looser detection
python3 -m spinwatch scan --window 12 --repeat-threshold 3 --talk-threshold 6 s.jsonl

# live watch while a session runs (Ctrl-C stops; alarms once per streak)
python3 -m spinwatch --follow --interval 5 ~/.local/share/opencode

Exit codes: `0` no spin · `1` findings · `2` usage error.

Live watch (`--follow`)

Scan answers "did it spin?"; `--follow` answers "is it spinn