# gmsniff A live manager for running `gm` agents — see every agent on the machine, what phase it is in, what instruction it was actually served, and what it has produced, from a terminal CLI or a browser GUI. gmsniff is read-mostly tooling for the observer. It reads the telemetry each running agent's daemon writes, plus each project's own `.gm/` state files, and turns them into a single cross-project view. It never drives an agent; it watches them. ## Install ``` npm install -g gmsniff ``` Zero dependencies. Nothing is fetched at install time or at runtime — the CLI and the GUI both work fully offline. ## The primary view ``` gmsniff --agents -f ``` The live manager view: one row per working agent, showing its current phase, the instruction the daemon is serving it right now, how long it has been in that phase, its pending PRD rows and unresolved mutables, and a streaming feed of its recent output. Idle and `COMPLETE` agents are hidden by default; pass `--idle` to include them. ``` gmsniff --agents one-shot snapshot, no refresh gmsniff --agents --idle include idle/COMPLETE agents gmsniff --agents -f --interval 5000 refresh every 5s instead of the 2s default gmsniff --agents --agent full instruction text + a longer output feed for one project ``` `IN-PHASE` is measured from the project's own `.gm/turn-state.json` phase change. `LAST-EVT` is measured from the last real event in that project's watcher log. They are different clocks on purpose: an agent can sit in a phase for an hour while emitting events every few seconds, or hold a phase with nothing happening at all. ## Where the data comes from **Primary: per-project `/.gm/exec-spool/.watcher.log`.** This is the live stream that every current-generation `agentplug` daemon writes. gmsniff discovers projects, tails their watcher logs, and merges them into one event stream. **Opt-in only: `~/.claude/gm-log`.** The old central jsonl archive. Current builds no longer write to it, so it is historical data — a query restricted to it can read empty while agents are actively running. gmsniff never silently merges it into live results. It is read only when you explicitly ask for it, or when you set `GM_LOG_DIR` yourself. **Neither, for `--agents`:** the manager view reads each project's state files directly — `.gm/turn-state.json`, `.gm/next-step.md`, `.gm/exec-spool/.turn-summary.json`, `.gm/last-prompt.txt`, `.gm/exec-spool/.last-gate-fired.json`. Project discovery seeds from `~/.gm-tools/daemon-registry.txt` — the daemon's own list of served working directories, which reaches deep worktree paths a directory scan would miss — plus a scan of `GM_SPOOL_DIRS`, `DEV_ROOT`, `GM_DEV_ROOT`, the current directory, and `C:/dev` or `~/dev`. The registry is append-only and never prunes itself, so candidates are filtered against real existence before use. Discovery is deliberately wide and liveness deliberately narrow. On a typical machine that means on the order of a hundred-plus projects discovered, the majority of them worktrees, of which only one or two are genuinely working at any moment. ## Reading a watcher log Only about 15% of watcher-log lines are `evt: {json}` records. The rest are structured text that carries real signal, so gmsniff models it rather than discarding it: `[dispatch] -> verb=… task=…` lines become synthesized `dispatch.start` events (there is no upstream `evt` record for a dispatch *starting*), wasm version banners carry the per-project runtime version, daemon and watcher spawn lines mark epoch boundaries, and stale-lock takeovers and retention sweeps are recorded as events. Every replay reports its own parse coverage, so you can see what fraction of the input was understood rather than trusting a silent number. ## Liveness Three different questions, three different answers — do not substitute one for another: - `discoverProjects().alive` — **is this project working?** Judged from real per-project activity within a five-minute window. - `readWatcherStatus().alive` — **is the daemon up?** Machine-wide, one shared `agentplug-runner.exe` process serving every project. - `readProjectLiveness(cwd).active` — the per-project judgement on its own, with the individual activity clocks (`log_age_ms`, `summary_age_ms`, `turn_age_ms`) broken out. The `ts` field in a project's `.gm/exec-spool/.status.json` is **not** a per-project activity signal. The shared daemon rewrites it for every project it serves several times a second, so it reads as fresh even for a project that has done nothing for days. It is a daemon heartbeat and nothing else. ## Correlation There is no universal session key in the data. gmsniff ranks the identities that actually exist, best first: `sess` → `session_id` → `cwd#run` → `cwd`. Most events fall back to the daemon run, so grouped views say so explicitly rather than implying a per-agent session that the data cannot support. ## Investigation ``` gmsniff -f live tail across every discovered project gmsniff --list-deviations what went wrong recently, grouped by kind gmsniff --list-sessions --since 24h per-session summary with phase walk gmsniff --tree chronological process tree for one session gmsniff --stats --since 24h breakdown by sub / event / sess / day gmsniff --list-events --sub plugkit event-type histogram gmsniff --efficiency turn count, dispatch ratio, time-to-COMPLETE gmsniff --watchers daemon liveness per project + runtime version gmsniff --projects PRD-pending + unresolved mutables per project gmsniff --updates runtime version + real drift gmsniff --rollup out.ndjson --since 7d ``` Filters compose across all of these: `--since/--until`, `--sub`, `--event`, `--sess`, `--grep`, `--cwd`. Output shaping via `--json`, `--limit`, `--ctx`, `--reverse`. `--spool ` forces a single project directory or watcher-log path as the source. `gmsniff --help` has the full reference. ## Browser GUI ``` gmsniff gui --open ``` Opens on the live-agents view — the same manager information as `--agents`, with per-project drilldowns showing the full served instruction alongside a scrollable output feed. Clicking a project also shows which of three tiers resolved its instruction: a `vendored override` (a per-project `.gm/instructions/.md`, shown with its exact path), `source-synced`, or the `compiled default` baked into the wasm guest — so a surprising local override is never invisible. The stream updates over SSE. The sidebar is tiered daily-first: Daily and Investigate groups always show; Subsystems, Analytics, and Control panels sit behind a collapsed "Show advanced" toggle. Every panel stays reachable via the Ctrl+K command palette and `#panel=` deep links regardless of the toggle. The GUI makes no external-origin requests. Every stylesheet, component, and font is served from the installed package, so it works on an air-gapped machine. ## Agent-facing Machine callers get a self-describing contract and write surfaces: ``` gmsniff --schema # machine-readable JSON: flags, types, exit codes gmsniff --prd-edit --status done # atomic PRD row rewrite gmsniff --mutable-edit --witness "..." # atomic mutable row rewrite gmsniff --dispatch --json '{...}' # write a spool request ``` Every parsed event carries `_schema: "v1"` for versioned parsing. The GUI server exposes the same data — and more — over `/api/*` routes, including `/api/spool-queue` (pending dispatch files per verb per project), `/api/watcher-versions` (per-project liveness, runtime, version) and `/api/instruction-tiers` (vendored vs source-synced vs default distribution); these three are server routes only, with no CLI flag. The event store is bounded at 1M events (`GM_MAX_EVENTS`) with oldest-event eviction. Exit codes: 0 = success (zero-match queries included — absence of data is not a failure), 2 = usage error; uncaught exceptions keep Node's non-zero default. ## Requirements Node >= 18. gmsniff imports only core Node modules (`fs`, `path`, `os`, `http`, `url`, `events`, `crypto`) and uses no API newer than that floor. Development and CI currently run on Node 24; the declared floor is held by source review rather than by an executed Node 18 build. ## Development - `node test.js` runs the single mock-free, real-services integration test. Extend that file; there is no test framework and no parallel suite by design. - `gui/ds/` is vendored byte-for-byte from the sibling `../anentrypoint-design` repo via `npm run sync:ds`; never hand-edit files under it. - Pushing to `main` auto-bumps the patch version and publishes to npm via GitHub Actions; do not hand-bump `package.json`. ## Donations BTC: `15FLMay4of9rk4jK2davzzL4HDdGQtscGX`