Spotter is a local runtime supervisor for coding agents.
It watches how work unfolds—not only the final diff—so costly deviations can be caught early.
local-first · bounded gates · trajectory-aware
Install · Quick start · Project site · Detailed guide · Current status · Documentation
Coding agents rarely fail in one obvious step. A weak assumption can shape the next search, edit, and test; repeated local decisions then turn a recoverable mistake into wasted time, tokens, and repository churn.
|
🔭 Trajectory-aware Observe decisions, evidence, edits, and validation—not only the final diff. |
⚡ Bounded safety Keep deterministic checks local and fast before risky tool use. |
🩺 Visible degradation Make unavailable observation or control diagnosable without blocking Codex. |
Spotter maintains an independent view of the running trajectory and helps answer:
- Is the agent repeating failures or equivalent actions without learning anything new?
- Is the change growing beyond the requested scope?
- Did meaningful edits happen without relevant validation?
- Is the agent still acting on a hypothesis that newer evidence has weakened?
- Is a deterministic safety rule about to be violated?
The goal is not more alerts. It is less wasted work after the first meaningful deviation.
The current runtime can:
- collect Codex Hook and configured App Server events into durable trajectory journals;
- maintain daemon-owned live state for threads, turns, evidence, progress, and detected signals;
- enforce bounded deterministic gates before risky tool use;
- detect candidate loops, stalled exploration, scope growth, missing validation, and stale hypotheses;
- run optional semantic reviews in shadow mode, with a separate live-advisory opt-in;
- expose health and integration diagnostics through
spotter statusandspotter doctor; - preserve Git-backed snapshots and replay material for recovery and analysis.
Important
Spotter is under active development. Deterministic gates are active; semantic VERIFY and
NUDGE decisions remain shadow-only by default and can steer only with explicit active-mode
configuration. Live advisory benefit and task-ownership safety are not yet established. Check
Status for the exact current boundary.
Codex is the primary standalone integration.
Codex
├─ Hooks ────────────────► bounded deterministic gates
└─ App Server events ────► observation and control when configured
│
▼
spotterd
│
journal · live state · signals · review · opt-in advisory
Deterministic gates stay bounded, while slower semantic review remains off synchronous tool-execution paths. If observation or control degrades, diagnostics remain explicit and generated Hooks fail open rather than blocking normal Codex use.
The supported packaged installation uses the official Homebrew tap:
brew install spotter-agent/spotter/spotterVerify both installed entry points:
spotter --version
spotterd --versionPackage installation only installs the CLI, daemon, and Hook bridge. It does not edit Codex configuration or register an integration.
For a source/development checkout, follow CONTRIBUTING.md.
Install Codex CLI (stable 0.147.0 or newer) and make it available on PATH, then run:
spotter setup codex --local --dry-run
spotter setup codex --local
spotter doctor
spotter codex--local prepares and verifies a local App Server automatically; no separate server terminal or
endpoint configuration is needed. Setup verifies server identity and observation capabilities before
committing the integration. It reuses a configured local endpoint or defaults to
ws://127.0.0.1:4500. The server is shared and remains running after the TUI exits; Spotter never
stops it. --dry-run does not start or contact the server.
The default is observation only: violations are recorded, not blocked, and automatic AI reviews
and live advisories are off. doctor shows these settings and a safe policy preview without running
the example command or calling a model. See mode selection.
Use spotter codex for subsequent sessions. Plain codex does not connect to the same observation
path. At managed session start, Spotter checks daemon-owned state for the exact thread and displays a
warning when live observation is not confirmed; the warning is not added to model context. Existing
external-server users can keep setup codex --endpoint <address>; new setup without --local or
--endpoint remains Hook-only. Rerunning setup retains a configured endpoint.
| Command | Purpose |
|---|---|
spotter status |
Show integration, daemon, capability, and storage health |
spotter doctor |
Run synthetic health checks and print actionable diagnostics |
spotter codex [args...] |
Start spotterd, verify the configured endpoint, and launch the remote TUI |
spotter mode [observe|protect|advisory|custom] |
Show or select supervision behavior without editing TOML |
spotter status --session ID |
Show one live thread's observation, policy, and review budget state |
spotter daemon status |
Inspect the packaged spotterd process and build identity |
spotter daemon reload |
Atomically apply safe config changes or stage the next generation |
spotter update |
Detect the package owner and print non-mutating update guidance |
spotter metrics |
Summarize collected runtime and evaluation metrics |
spotter sample-signals |
Persist a deterministic detector-silence sampling frame |
spotter label-opportunity |
Record semantic and observable intervention windows |
spotter analyze |
Review per-session interventions, costs, and provenance-linked outcomes |
spotter observability |
Inspect which trajectory sources and normalized events are available |
spotter --help |
Show the complete command surface |
Configuration is optional. Use spotter.example.toml as the reference when you need to customize gates, storage, snapshots, or reviewer budgets. Signal-driven semantic reviews spend model tokens and are disabled by default. Live delivery is a second opt-in that also requires active mode; enable either deliberately and keep the provided per-session and per-day limits.
Use spotter mode for a guided choice, or select directly:
spotter mode observe # record only (default)
spotter mode protect # block deterministic rule violations; no AI reviews
spotter mode advisory # experimental AI advice; consumes model tokensUpgrade the Formula, then rerun setup so Spotter can reconcile the installed build, running daemon, and integration generation:
spotter update
brew upgrade spotter-agent/spotter/spotter
spotter setup codex
spotter doctorspotter update is advisory: it reports the current build and the appropriate Homebrew, pipx, uv
tool, or pip command. It never overwrites package-managed files, and source/editable installs are
directed back to their owning development workflow.
Persistent Hook and service references use stable package entry points rather than versioned
Homebrew Cellar paths. Spotter detects a still-running older daemon instead of assuming it matches
the newly installed CLI. A rerun without --endpoint retains and re-verifies an endpoint already
recorded by a successful setup.
To remove the Codex integration but keep Spotter installed:
spotter teardown codexFor a clean uninstall:
spotter teardown codex
brew uninstall spotter-agent/spotter/spotterHomebrew uninstall removes package-owned executables and stops the packaged runtime. It
intentionally does not purge separately managed user data under ~/.spotter. An integration left
behind by an uninstall without teardown is designed to fail open and can be repaired after
reinstalling.
See Lifecycle before upgrades, recovery, migration, teardown, or data removal that needs more than the common path above.
Show the safety and ownership guarantees
brew installandbrew upgradedo not silently modify Codex configuration.spotter setup codexandspotter teardown codexchange only exact owned integration state.- Generated Hooks use stable executable paths and fail open when Spotter is unavailable.
- Spotter does not stop a shared Codex App Server that it cannot prove it owns.
- Uninstall and user-data purge are separate operations.
statusanddoctormake degraded observation or control visible.
These contracts are covered by fast fixtures and a real macOS Homebrew install → live upgrade → uninstall → reinstall lifecycle smoke. See Homebrew lifecycle smoke for the evidence and reproduction path.
| If you want to… | Read |
|---|---|
| See what works today and what is still experimental | Status |
| Install, configure, operate, troubleshoot, or uninstall | Detailed user guide |
| Understand the complete package and integration contract | Lifecycle |
| Understand the product idea and intervention model | Concept |
| Understand runtime boundaries and durable state | Architecture |
| Follow upcoming work and evidence gates | Roadmap |
| Review experiments, hypotheses, and evidence | Research |
| Build or contribute to Spotter | Contributing |
| Browse every project document | Documentation index |
Maintained by @bogyie / Bogyoeng Kim and
@zerone / Youngjin Jung.
Released under the MIT License.