README
¶
Monitor your Claude Code sessions across machines from a terminal dashboard —
which sessions are running, what they're working on, and how many tokens they consume.
Scope
vigie supervises Claude Code, and nothing else. Its whole model is Claude Code's: a session is named from the transcript Claude Code writes, it is alive while Claude Code's process is, and a subagent is part of its parent rather than a session of its own.
Another CLI that reads ~/.claude/settings.json and runs the hooks it finds there
will call vigie report too. Those reports are refused: vigie could not name such
a session, could not tell when it ended, and would count each of its subagents as
a session — so the fleet count, the one question this board answers, would stop
meaning anything (ADR-0013).
Features
- Every session, every machine, one board — eight live statuses, grouped and filtered as you like.
- A session can call you when its work is done.
- Desktop notifications when a session starts calling for you — waiting on
input, in error, or raising a call — and
nto jump straight to it. In the terminal (libnotify), on the GNOME top bar, and in the browser (opt-in from Settings; the browser requires an https or localhost address). - Terminal and browser — a TUI, and a read-only web dashboard served by the daemon itself. Same board and same answers; each suits its own medium.
- Per-session insight — tokens, context fill, reasoning effort, permission mode,
/rclink. - Usage and history — subscription usage, plus daily rollups of tokens and of where your time went.
- Observe-only — vigie never writes into a session, and stores nothing about how you handled one.
A session can call you
Ask in plain language — "when you're finished, tell me in vigie" — and the session raises a call as its turn ends.
vigie installs and keeps a small Agent Skill current so Claude knows the command exists — nothing to run, nothing to set up per project. Your next message in that session clears the call. It is best-effort: if Claude does not run the command, nothing is raised.
How it works
Claude Vigie is a central server and a client you install on every machine. Each
Claude Code session reaches the server two ways: through hooks — a small
vigie report command wired into ~/.claude/settings.json — and through
a watcher that scans transcripts to cover sessions the hooks miss.
The unit of tracking is one Claude Code session. Sessions are grouped by machine and project. See docs/architecture.md for the full design.
Two binaries
vigied serve # server: HTTP + SSE API, SQLite — runs on the host
vigied token # server: print the shared auth token
vigied stats-repair # server: correct one day's output-token figure
vigie init # client: write the config (the watcher installs the hooks)
vigie hooks # client: add/remove reporting hooks (one leg per VIGIE_CONFIG)
vigie report # client: reporter invoked by Claude Code hooks
vigie call # client: raise a call for the operator, from inside a session
vigie watch # client: watcher — scans transcripts, covers all sessions
vigie tui # client: terminal dashboard
vigied is the server daemon (one host). vigie is the client
you install on every machine running Claude Code sessions. See
ADR-0003.
The daemon also serves a read-only web dashboard at its root URL. Open it,
paste the server token, and watch every machine from a phone or laptop. No extra
process: it is embedded in vigied. It shows the same board as the TUI — same
statuses, same hierarchy — with the gestures a browser calls for rather than a
terminal's (architecture).
Design choices
- Go, static binaries — trivial self-hosting, minimal client surface (client and server are separate binaries). See ADR-0002 and ADR-0003.
- Embedded SQLite — no database server to deploy; full usage history.
- Shared-token auth — simple, suitable for personal use or a small team.
- Tokens only — no currency cost estimates (Claude Code subscriptions have no per-token price).
Install & run
Linux only. Releases ship linux/amd64 and linux/arm64, and session
presence is read from /proc — the signal every status derives from
(ADR-0006). There is no macOS or
Windows build.
vigie ships binaries (vigie, vigied). How you run
and expose them — systemd, containers, TLS front — is the deployer's call; see
docs/deployment.md.
# on the host: run the server
vigied serve --addr :8080 --db vigie.db
# on each machine running Claude Code: connect (asks for the server and token)
vigie init
# cover already-open sessions too (run this as a service):
vigie watch
# view the board in the terminal:
vigie tui
# ...or in a browser: open http://host:8080 and paste the token
vigie init only writes the config. The watcher installs the reporting hooks
and the call skill when it starts, and keeps them matching the running binary —
so an upgrade needs no re-install, just a service restart. A machine that runs no
watcher can wire itself with vigie hooks install; vigie hooks uninstall
removes both.
The client reads ~/.config/vigie/config.toml (override the path with
VIGIE_CONFIG, or the deprecated FLEET_CONFIG).
Development
Requires Go 1.26+, just, and Node 22+ (the
dashboard and the GNOME indicator are tested with node's built-in runner — no
package.json, no dependencies).
just dev-setup # configure git hooks
just tool-install # install golangci-lint + goimports + govulncheck into ./bin
just code-check # fmt + lint + build + test (go & js) + vulnerability scan (run before every PR)
just docs-animation # regenerate the README animation after editing its template
Run the current source against a throwaway local server, fully isolated from any
installed production client via VIGIE_CONFIG (never touches ~/.config):
just dev-server # background: builds & runs vigied on :8099 (dev db + token)
just dev-watcher # background: watcher → the dev server
just dev-tui # foreground: the TUI → the dev server
just dev-down # stop the background dev server + watcher
Disclaimer
vigie is an independent, community project. It is not affiliated with, endorsed by, or sponsored by Anthropic. "Claude" and "Claude Code" are trademarks of Anthropic, PBC, used here only to describe interoperability.
License
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
vigie
command
|
|
|
vigied
command
|
|
|
internal
|
|
|
animation
Package animation renders the README's "A session can call you" asset.
|
Package animation renders the README's "A session can call you" asset. |
|
api
Package api holds the request/response types exchanged between the client (reporter, terminal client) and the server.
|
Package api holds the request/response types exchanged between the client (reporter, terminal client) and the server. |
|
apiclient
Package apiclient performs the client side's authenticated GETs against the vigie daemon.
|
Package apiclient performs the client side's authenticated GETs against the vigie daemon. |
|
client
Package client implements the vigie client command-line dispatch.
|
Package client implements the vigie client command-line dispatch. |
|
clock
Package clock centralizes access to the wall clock.
|
Package clock centralizes access to the wall clock. |
|
compaction
Package compaction records that a Claude Code session started compacting its context, so the watcher can refine its status from an opaque `working` to `compacting` while it summarizes (ADR-0008, #342).
|
Package compaction records that a Claude Code session started compacting its context, so the watcher can refine its status from an opaque `working` to `compacting` while it summarizes (ADR-0008, #342). |
|
config
Package config loads the shared per-machine vigie client configuration (server URL, auth token, machine name) used by the reporter and the terminal client.
|
Package config loads the shared per-machine vigie client configuration (server URL, auth token, machine name) used by the reporter and the terminal client. |
|
daemon
Package daemon implements the vigied server command-line dispatch.
|
Package daemon implements the vigied server command-line dispatch. |
|
install
Package install merges vigie reporting hooks into the user's Claude Code settings (~/.claude/settings.json), idempotently, preserving any existing hooks and settings.
|
Package install merges vigie reporting hooks into the user's Claude Code settings (~/.claude/settings.json), idempotently, preserving any existing hooks and settings. |
|
localwatch
Package localwatch records, on the machine itself, that a watcher is running here.
|
Package localwatch records, on the machine itself, that a watcher is running here. |
|
modelinfo
Package modelinfo holds what vigie derives from a Claude model's name — today, the size of its context window.
|
Package modelinfo holds what vigie derives from a Claude model's name — today, the size of its context window. |
|
presence
Package presence links a Claude Code session to the OS process backing it, so the watcher can reliably tell a live session (idle for any duration) from a closed one — something transcript activity alone cannot do.
|
Package presence links a Claude Code session to the OS process backing it, so the watcher can reliably tell a live session (idle for any duration) from a closed one — something transcript activity alone cannot do. |
|
reachability
Package reachability records, on the machine itself, that the daemon did not answer — so a Claude Code hook can decline to wait on it again.
|
Package reachability records, on the machine itself, that the daemon did not answer — so a Claude Code hook can decline to wait on it again. |
|
report
Package report builds and sends a session event report to the fleet server.
|
Package report builds and sends a session event report to the fleet server. |
|
server
Package server implements the vigied HTTP API: it accepts session event reports, lists sessions, and streams updates over SSE.
|
Package server implements the vigied HTTP API: it accepts session event reports, lists sessions, and streams updates over SSE. |
|
status
Package status holds the one list of session statuses vigie can report.
|
Package status holds the one list of session statuses vigie can report. |
|
store
Package store persists fleet state in an embedded SQLite database: the current state of each Claude Code session plus an append-only event log.
|
Package store persists fleet state in an embedded SQLite database: the current state of each Claude Code session plus an append-only event log. |
|
transcript
Package transcript parses a Claude Code session transcript (JSONL) to extract the session's identity, context, token usage, and current activity.
|
Package transcript parses a Claude Code session transcript (JSONL) to extract the session's identity, context, token usage, and current activity. |
|
tui
Package tui renders a live terminal dashboard of fleet sessions, polling the server.
|
Package tui renders a live terminal dashboard of fleet sessions, polling the server. |
|
usage
Package usage fetches Claude subscription usage from the (unofficial) OAuth usage endpoint using the local OAuth credentials.
|
Package usage fetches Claude subscription usage from the (unofficial) OAuth usage endpoint using the local OAuth credentials. |
|
version
Package version holds build metadata injected at link time via -ldflags.
|
Package version holds build metadata injected at link time via -ldflags. |
|
watch
Scanning the transcripts: the per-run cache, the process index and the session lineage the scan carries between passes.
|
Scanning the transcripts: the per-run cache, the process index and the session lineage the scan carries between passes. |
|
web
Package web serves the read-only web dashboard: static assets embedded in the daemon binary (go:embed), a browser mirror of the terminal UI.
|
Package web serves the read-only web dashboard: static assets embedded in the daemon binary (go:embed), a browser mirror of the terminal UI. |
|
tools
|
|
|
animation
command
Command animation writes the README's "A session can call you" asset.
|
Command animation writes the README's "A session can call you" asset. |