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.
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/generate the shared auth token
vigie init # client: install hooks + write the config
vigie hooks # client: add/remove reporting hooks (one leg per VIGIE_CONFIG)
vigie report # client: reporter invoked by Claude Code hooks
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 — a browser
mirror of the TUI. Open it, paste the server token, and watch every machine
from a phone or laptop. No extra process: it is embedded in vigied.
Design choices
- Go, static binaries — trivial self-hosting, cross-platform, 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
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 (writes config + installs hooks)
vigie init --server http://host:8080 --token <token> --machine "$(hostname)"
# 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
Hooks cover sessions started after init; the watcher guarantees coverage by
scanning ~/.claude/projects/. vigie init --uninstall removes the hooks.
The client reads ~/.config/vigie/config.toml (override the path with
VIGIE_CONFIG, or the deprecated FLEET_CONFIG).
Development
Requires Go 1.26+ and just.
just dev-setup # configure git hooks
just tool-install # install golangci-lint + goimports into ./bin
just code-check # fmt + lint + build + test (run before every PR)
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
|
|
|
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. |
|
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 claude-fleet client configuration (server URL, auth token, machine name) used by the reporter and the terminal client.
|
Package config loads the shared per-machine claude-fleet 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 claude-fleet reporting hooks into the user's Claude Code settings (~/.claude/settings.json), idempotently, preserving any existing hooks and settings.
|
Package install merges claude-fleet reporting hooks into the user's Claude Code settings (~/.claude/settings.json), idempotently, preserving any existing hooks and settings. |
|
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. |
|
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 claude-fleetd HTTP API: it accepts session event reports, lists sessions, and streams updates over SSE.
|
Package server implements the claude-fleetd HTTP API: it accepts session event reports, lists sessions, and streams updates over SSE. |
|
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
Package watch continuously scans the local Claude Code transcripts and reports every recent session to the fleet server, deriving status from the transcript state.
|
Package watch continuously scans the local Claude Code transcripts and reports every recent session to the fleet server, deriving status from the transcript state. |
|
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. |