# Spotter
[](https://www.npmjs.com/package/claude-spotter)
[](https://github.com/kitepon-rgb/Spotter/actions/workflows/ci.yml)
[](https://nodejs.org)
[](LICENSE)
**English · [日本語](README.ja.md)**
> **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:
| Situation | What Claude would do | What Spotter flags |
|---|---|---|
| "Please remember this OAuth gotcha" | Acknowledge and move on | Missed call to a memory / caveat MCP |
| "How does this package API work in the latest version?" | Answer from training-time knowledge | Missed call to a docs-lookup MCP |
| "Review this risky patch" | Self-review only | Missed call to a reviewer sub-agent |
| Asserting a fact | State it without verification | Opportunity to call a verification tool |
| "Does this UI still render correctly?" | Reason from source code alone | Missed call to a browser-automation MCP |
| "What did we decide about X earlier?" | Guess or admit forgetting | Missed call to a memory / notes MCP |
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
```bash
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//...` 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.
```bash
spotter uninstall # remove hooks from this project
```
Release install smoke:
```bash
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`.
```mermaid
flowchart TD
U([User prompt]) --> UPH[UserPromptSubmit hook
Spotter audits prompt against catalog]
UPH --> BT[Claude thinking
receives Spotter's recommendations
as additionalContext]
BT --> BA([Claude's first answer])
BA --> SH[Stop hook
Spotter re-audits answer + tools used]
SH --> DEC{Missed
tool?}
DEC -->|No| DONE([Done])
DEC -->|Yes| SB[Queue finding to .spotter/pending/
v1.4.8 deferred delivery]
SB --> NEXT([Surfaces as additionalContext
on next UserPromptSubmit])
```
### Catalog discovery
```mermaid
flowchart LR
subgraph SRC[Discovery sources]
direction TB
MCP[MCP servers
via claude mcp list]
SK[Skills
SKILL.md frontmatter]
AG[Sub-agents
agent .md frontmatter]
BL[claude.ai baseline
Gmail / Calendar / Drive
injected when present]
end
subgraph SCOPES["MCP env / headers — 4 scopes, top wins on collision"]
direction TB
L["Local — projects.<root>.mcpServers in ~/.claude.json"]
P["Project — <root>/.mcp.json"]
US["User — mcpServers in ~/.claude.json"]
LG["Legacy — ~/.claude/.mcp.json"]
end
SCOPES -. merged into .-> MCP
MCP --> DB[(Host-local tool-db
name + description
per project)]
SK --> DB
AG --> DB
BL --> DB
DB --> H[Haiku audit
session-scoped, preamble-once]
```
The audited catalog is host-local: Claude uses `/.spotter/tool-db.json`, while Codex uses `/.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](https://github.com/kitepon-rgb/Throughline) is a sibling project from the same author. Different mechanism, **shared philosophy**.
| | Throughline | Spotter |
|---|---|---|
| Direction | Subtraction — evict what isn't needed | Addition — surface what's missing |
| Target | Context bloat | Missed tool calls |
| Mechanism | Hook-driven memory eviction | Hook-driven sub-agent in parallel |
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
```bash
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:
```bash
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](docs/catalog-design.md) — source of truth from v1.0.0
- **Open issues + unverified concerns**: [docs/open-issues.md](docs/open-issues.md) — read this before starting new work
- **Runtime contract**: [docs/SPOTTER_CLAUDE_CONTRACT.md](docs/SPOTTER_CLAUDE_CONTRACT.md) — Claude hook / daemon / Haiku contract plus Codex native hook policy
- **Implementation invariants (§0)**: [CLAUDE.md](CLAUDE.md) — no fallbacks, no silent failures, no provisional code
- **Archived plans and history**: [docs/archive/](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 `/.spotter/pending/.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
📋 Recent highlights
- **Plugin-scoped MCP servers** — names like `plugin:everything-claude-code:context7` (with internal colons) are now parsed correctly and their tools enter the catalog. Earlier versions silently collapsed all plugin MCP servers into a single literal `"plugin"`, dropping their tools from Claude's audit
- **Per-project / per-host audit isolation** — the daemon audits against the local DB only; global DBs are host-specific description caches. Tools discovered in *other* projects or another host can never bleed into this project's audit set
- **Zero-touch catalog** — `spotter install` seeds the Claude DB automatically; Claude and Codex SessionStart hooks keep their host-local DBs fresh in the background. You never have to maintain the tool list by hand
- **Codex native hooks** — Codex host uses Codex CLI as the primary auditor backend, keeps a separate `.spotter/tool-db.codex.json`, and surfaces backend failures explicitly instead of falling back to Haiku
- **Audit scope** — only user-added surface (MCP servers / skills / sub-agents). Claude Code's built-in tools are intentionally out of scope; Claude already uses those reliably
- **Implementation invariants** — no fallbacks, no silent failures, no provisional code (see [§0 in CLAUDE.md](CLAUDE.md))
Full release history: [CHANGELOG](CHANGELOG.md).
## License
MIT — see [LICENSE](LICENSE).