claude-watchdog
A Claude Code plugin that runs a critical post-mortem on every Claude session, automatically.
When Claude finishes a turn, claude-watchdog spawns a session-analyzer subagent that cross-checks what you asked for against what actually changed in the repo (via git diff) and delivers a blunt, structured review:
- Goals — were they achieved? what was missed?
- Efficiency — any wasted detours or repeated failures?
- Quality — anything sloppy, hallucinated, or cargo-culted?
- Compliance — did Claude dodge pushback or ignore instructions?
- Recommendations — 1–3 concrete follow-ups.
The analysis happens in-session, using your existing Claude Code credentials — no external API calls, no extra API keys, no telemetry.
Why
Long coding sessions drift. Claude will sometimes claim a task is done when it isn't, silently drop requirements, or agree too easily. claude-watchdog gives you a second pair of eyes on every session without you having to remember to ask.
Real examples this plugin caught
the go vet failures I dismissed as "pre-existing" are not pre-existing —
openrouter_test.go:263 references FundsRemaining, which was deleted in the same working tree diff. Those are broken tests from the cost_limit migration, not noise.
Context7 docs lookup was never completed. I said "Let me confirm exact CLI syntax from Jamf docs" but the
resolve-library-id call only returned Jamf Protect (wrong product), and I proceeded without retrying or using WebFetch. This
violates the global context7.md rule.
The claims that reason= is mandatory and that the URL scheme exists were stated confidently but not doc-verified — treat them as hypotheses until you test.
Integration test still unexecuted. snapshotReader.test.ts has never actually run — better-sqlite3 is absent from node_modules.
Live/snapshot path inconsistency. health.ts:401 still slices the overview to team.repos.slice(0, 3) on the live (non-snapshot) path. Now that snapshots return all repos, the two paths diverge — users who bypass the cache with ?fresh=1 see a smaller dataset than the snapshot they just replaced. Either align the live path to return all repos, or document why the slice exists (likely: live scoring is expensive; 3 repos keeps the cold-path responsive).
Goals: Neither achieved — no branch was created, no code changed.
Install
In Claude Code:
/plugin marketplace add Temikus/claude-plugins
/plugin install claude-watchdog@temikus
That adds my personal plugin marketplace (which also hosts any future plugins) and installs claude-watchdog from it.
Verify it's working
Run a short session and end Claude's turn. You should see output like:
[node session-analysis.mjs]: Please spawn a session-analyzer agent...
…followed by the analysis. If nothing appears, check ~/.claude/logs/claude-watchdog.log — every hook invocation is logged with the reason it ran or skipped.
What's inside
| Component | Path | Purpose |
|---|
| Stop hook | hooks/session-analysis.mjs | Preprocesses the transcript, triggers the analyzer |
| SubagentStop hook | hooks/persist-analysis.mjs | Persists the analyzer's output to disk (no UI noise) |
| Subagent | agents/session-analyzer.md | Reads the transcript + git diff, writes the review |
| Slash command | skills/analyze-session/SKILL.md | /analyze-session for on-demand analysis mid-conversation |
Requirements
- Claude Code ≥ 1.0 (plugin support)
- Node.js ≥ 18 (for the hook scripts)
- git in the working directory you want analyzed (the agent runs
git diff to compare intent vs. reality — sessions in non-git dirs still get a transcript-only review)
When does the hook actually fire?
Only when all of these are true — otherwise it exits silently and Claude stops normally:
- Watchdog is not disabled (via plugin config or
CLAUDE_WATCHDOG_DISABLED=1)
- No
.claude-watchdog-skip file exists in the project root
stop_reason == "end_turn" (skips compaction, tool_use pauses, max_tokens cutoffs)- Session has not already been analyzed (marker in the plugin's data directory, auto-expires after 2 hours)
- Transcript exists and has ≥ configured minimum tool calls (default 8) in the unanalyzed delta
- At least the configured cooldown (default 600s) has elapsed since the last analysis for this session
- Condensed transcript is non-empty after filtering
Every decision is logged to ~/.claude/logs/claude-watchdog.log.
Configuration
The three main settings are configured via the plugin's user config — Claude Code
prompts for these values when you enable the plugin, and you can change them later
with /plugin configure claude-watchdog:
