Spotter

English · 日本語

Separate the spotter from the doer. Spotter runs alongside Claude Code and quietly flags the moments when your primary Claude forgets to use a tool it has access to.

Claude has a structural blind spot: it can't reach for a tool it doesn't realize it needs. It may skip a project memory MCP when a decision should be recorded, answer from stale memory instead of a docs-lookup MCP, or reason about UI state without a browser-automation MCP. The model can't always tell when it doesn't know — so the tool stays unused.

Spotter pins a second agent (Claude Haiku 4.5) next to Claude. The second agent has the full tool catalog memorized and audits both the user's prompt and Claude's reply in parallel. When it spots a missed tool, it injects a transparent recommendation into Claude's context and, if needed, asks Claude to amend its answer. Claude is never asked to self-audit — that would defeat the entire premise. Detection happens through hooks, independent of Claude's intent.

_{Claude answers (the doer)  ·  Spotter watches (the auditor, silent)}

See it in 30 seconds

Examples of what Spotter catches:

Spotter audits in two stages:

• stage=user_input — given the user's prompt, list any local catalog tools whose description clearly applies. A prompt-fulfillment check
• stage=turn_end — given Claude's final reply, look for places where a catalog tool (verification / recording / lookup) could plug in. A missed-opportunity audit. Zero findings is fine; tools already used in this turn are not re-flagged

Install

npm install -g claude-spotter
cd your-project
spotter install

On macOS with Homebrew Node, Codex hook commands use the stable /opt/homebrew/bin/node symlink when it resolves to the current Node binary, instead of a versioned /opt/homebrew/Cellar/node/<version>/... path. That keeps Codex hooks working across Homebrew Node upgrades.

Since v0.3.0, Spotter requires explicit per-project install (the earlier postinstall auto-registration was the leading cause of orphan daemons). spotter install writes hooks into the project's .claude/settings.json; the audit is then active only in Claude Code sessions for that project. When the Codex CLI is available, the same spotter install also registers user-level Codex native hooks. Project activation still depends on the same per-project .spotter/marker.json, so unrelated Codex sessions do not trigger Spotter. For Codex, install enables the current [features].hooks = true flag and still recognizes older codex_hooks diagnostics output for compatibility.

After upgrading Spotter, re-run spotter install in each installed project when release notes mention hook setting changes. The global package update changes the code path, but existing .claude/settings.json timeout values are not rewritten automatically.

spotter uninstall        # remove hooks from this project

Release install smoke:

npm uninstall -g claude-spotter
npm install -g claude-spotter
spotter --version
spotter install -y
spotter codex-hook install

Requirements

• Node.js 22.5+
• Claude Code 2.0+
• Claude Max plan for the current Claude-backed auditor path (Spotter spawns Haiku via claude -p)
• Codex CLI for Codex native hooks. Codex host auditing uses codex exec by default and does not fall back to Haiku

Architecture

Audit flow per turn

Claude Code and Codex have different Stop surfaces. The diagram below is the Claude host flow. Codex native Stop uses deferred delivery: findings are queued and shown on the next same-session UserPromptSubmit.

flowchart TD
    U([User prompt]) --> UPH[UserPromptSubmit hook<br/>Spotter audits prompt against catalog]
    UPH --> BT[Claude thinking<br/>receives Spotter's recommendations<br/>as additionalContext]
    BT --> BA([Claude's first answer])
    BA --> SH[Stop hook<br/>Spotter re-audits answer + tools used]
    SH --> DEC{Missed<br/>tool?}
    DEC -->|No| DONE([Done])
    DEC -->|Yes| SB[Queue finding to .spotter/pending/<br/>v1.4.8 deferred delivery]
    SB --> NEXT([Surfaces as additionalContext<br/>on next UserPromptSubmit])

Catalog discovery

flowchart LR
    subgraph SRC[Discovery sources]
      direction TB
      MCP[MCP servers<br/>via claude mcp list]
      SK[Skills<br/>SKILL.md frontmatter]
      AG[Sub-agents<br/>agent .md frontmatter]
      BL[claude.ai baseline<br/>Gmail / Calendar / Drive<br/>injected when present]
    end
    subgraph SCOPES["MCP env / headers — 4 scopes, top wins on collision"]
      direction TB
      L["Local — projects.&lt;root&gt;.mcpServers in ~/.claude.json"]
      P["Project — &lt;root&gt;/.mcp.json"]
      US["User — mcpServers in ~/.claude.json"]
      LG["Legacy — ~/.claude/.mcp.json"]
    end
    SCOPES -. merged into .-> MCP
    MCP --> DB[(Host-local tool-db<br/>name + description<br/>per project)]
    SK --> DB
    AG --> DB
    BL --> DB
    DB --> H[Haiku audit<br/>session-scoped, preamble-once]

The audited catalog is host-local: Claude uses <project>/.spotter/tool-db.json, while Codex uses <project>/.spotter/tool-db.codex.json. The daemon audits against the Claude local DB only, and Codex native hooks read the Codex local DB. Global description caches are host-specific too: Claude uses ~/.spotter/tool-db.json, while Codex uses ~/.spotter/tool-db.codex.json. They are shared only across projects for the same host and are never audit sources. Each host-local DB matches that host's current discovery snapshot for the project (stale entries are pruned on refresh), so tools from another project or another host cannot overwrite this session's audit catalog.

spotter install seeds the Claude catalog automatically, and the SessionStart hook runs a background spotter db refresh on every Claude Code session start — so you don't need to invoke Claude catalog commands by hand. When Codex CLI is available, the same spotter install registers Codex native hooks and seeds .spotter/tool-db.codex.json synchronously, so the first Codex session has a catalog too. Later Codex SessionStart hooks start spotter db refresh --host-agent codex in the background, updating .spotter/tool-db.codex.json without touching the Claude catalog. Claude discovery reads claude mcp list plus Claude skills / sub-agents; Codex discovery reads codex mcp list/get plus Codex skills. Each MCP server's tools/list is fetched via JSON-RPC (HTTP / SSE / stdio transports supported); skill and sub-agent metadata comes straight from frontmatter; the claude.ai baseline (25 hand-curated entries for Gmail / Calendar / Drive over OAuth proxy) is injected only for Claude when claude mcp list confirms the server is present. You never have to maintain the tool list by hand.

Spotter and Throughline

Throughline is a sibling project from the same author. Different mechanism, shared philosophy.

Both share the principle of "don't rely on the primary agent to do it itself." They compose well — you can run them together.

Common commands

spotter db list          # show the current Claude local tool-db
spotter db list --host-agent codex
                         # show the current Codex local tool-db
spotter db refresh       # rediscover Claude MCP / skills / sub-agents and update the Claude DB
spotter db refresh --host-agent codex
                         # rediscover Codex MCP / skills and update .spotter/tool-db.codex.json
                         #   (Claude refresh is automatic on install + Claude SessionStart;
                         #    Codex refresh is automatic on Codex SessionStart after spotter install)
spotter db rebuild       # wipe Claude local + Claude global DBs and refresh from scratch
                         #   (use after catalog-shape changes)
spotter status           # list running daemons
spotter doctor           # environment check (Node / claude CLI / Codex readiness / tool-db integrity)
spotter diagnostics logs # summarize daemon logs for pass=false / backend latency / anomaly signals
spotter codex risk-check --findings findings.json --host-agent claude
                         # run read-only codex-sidecar risk analysis for Spotter findings
spotter codex review|explore|opinion --findings findings.json --host-agent claude
                         # run other read-only codex-sidecar second-pass workflows
spotter codex work --findings findings.json --instruction "Update docs" --approve-work \
  --allowed-path docs/ --preserve-worktree
                         # run approved codex-sidecar work in an isolated worktree
spotter codex-hook install
                         # repair / explicitly register Codex native hooks (normally handled by spotter install)
spotter codex-hook diagnostics
                         # check Codex hooks feature and Spotter hook entries
spotter uninstall        # remove hooks from this project (leaves ~/.spotter intact)

Optional async Codex risk dispatch:

SPOTTER_CODEX_RISK_CHECK=1 spotter daemon start --session-id ... --project-root ...

When enabled, the daemon dispatches pass:false findings to spotter codex risk-check in a detached process. Hook responses do not wait for Codex. Add SPOTTER_CODEX_RISK_CHECK_DRY_RUN=1 to exercise the wiring without calling Codex.

Primary auditor backend policy: Claude hooks keep the current Haiku-compatible path by default. Codex native hooks use Codex CLI by default and do not fall back to Haiku; their SessionStart hook refreshes .spotter/tool-db.codex.json in the background without touching the Claude DB. Codex CLI auditor child processes explicitly use gpt-5.4-mini with model_reasoning_effort="low" by default so hook checks stay cheap and fast; SPOTTER_CODEX_CLI_MODEL and SPOTTER_CODEX_CLI_REASONING_EFFORT can override those values for smoke tests or controlled experiments. SPOTTER_AUDITOR_BACKEND=codex-sidecar is available for explicit sidecar auditor smoke.

Design docs

• Current design (catalog, discovery, classification axes): docs/catalog-design.md — source of truth from v1.0.0
• Open issues + unverified concerns: docs/open-issues.md — read this before starting new work
• Runtime contract: docs/SPOTTER_CLAUDE_CONTRACT.md — Claude hook / daemon / Haiku contract plus Codex native hook policy
• Implementation invariants (§0): CLAUDE.md — no fallbacks, no silent failures, no provisional code
• Archived plans and history: docs/archive/ — completed Codex rollout plans, primary backend smoke logs, and the frozen v0.1 design discussion

Known limitations

• The Stop hook fires after Claude's first answer has already been streamed to the user. When Spotter sends Claude back, the user sees both the original answer and the corrected one. Detection accuracy in UserPromptSubmit (the pre-response stage) is therefore Spotter's primary axis of quality
• Stop hook is deferred for both Claude and Codex hosts as of v1.4.8. When Spotter finds a missed tool at Stop, it appends the finding to <projectRoot>/.spotter/pending/<sessionId>.json and surfaces it on the next same-session UserPromptSubmit as additionalContext. The original assistant message stays as the turn's final transcript entry — no decision:"block" re-generation cycle. The same pending file is shared by Claude and Codex (host-neutral path)
• Since v0.5.0, JSON schema violations from Haiku are treated as expected-anomalies (silent pass + session renew, logged as role_collapse_reset) — this is the role-collapse recovery path. Haiku timeouts still throw, which surfaces as UserPromptSubmit blocking the user's prompt from reaching Claude. Timeouts have been raised twice (30s in v0.5.0, 45s in v0.13.1); making timeouts fail-open is deferred until §0 is revisited

License

MIT — see LICENSE.