Argus

The observability console for Claude Code — local-first, permanent, and honest about cost.

Quick start · Tour · CLI · Privacy · Architecture · Contributing

Claude Code writes a detailed transcript of every session to ~/.claude/ — every turn, every token, every tool call, every sub-agent it spawned — and then tells you almost nothing about it. Argus tails those files into a SQLite archive on your machine, prices each turn, and serves a dashboard at http://localhost:4242 that answers the questions the transcripts never do: what am I spending, where did it go, and which turn made it so?

Nothing leaves your computer. No telemetry, no API calls, no embeddings — SQLite and a static web app, bound to 127.0.0.1.

🚀 Quick start

pipx install argus-code     # or:  uv tool install argus-code
argus start

Your browser opens once the first pass finishes (5–10 s for a typical install). From then on, every session you run is ingested live. All you need is Python ≥ 3.11 and a ~/.claude/ directory or a Codex home — i.e. you've used Claude Code or Codex at least once.

Codex too. Argus also reads OpenAI Codex rollouts from $CODEX_HOME (default ~/.codex; only sessions/ and archived_sessions/ are read — never auth.json, config or state databases). Codex sessions get the same treatment: per-response turns and estimated cost (OpenAI's standard-tier API rates; Codex plans are usually billed differently, so treat it as an API-equivalent figure), tool health, and sub-agents folded under their parent thread. With both agents present the Sessions page gains an agent filter and column.

✨ Why Argus

It does forensics, not just totals. Argus keeps the structure of every session — turns, tool calls, sub-agents, cache reads — not just its sums. So you can find the turn that blew the budget, the tool that quietly started failing last Tuesday, and exactly what a sub-agent was told before it went off the rails.

It watches for you. Detectors re-check your data every 10 minutes against historical baselines and file alerts — a tool whose error rate doubles, a project whose weekly spend triples, a prompt cache that quietly stopped hitting — all flagged the day it happens, not when you happen to notice.

It accumulates. Usage tools like ccusage read what's on disk right now, and Claude Code rotates its own logs (cleanupPeriodDays, default 30) — so "right now" is a sliding month. Once Argus has ingested a session into ~/.argus/argus.db the row stays forever; a few months in, Argus remembers sessions Claude has already forgotten.

🔭 A tour

Every session, priced

A virtualised, sortable grid of every session you've ever run, with inline token bars and a duration × tokens scatter (log–log, coloured by model) that makes outliers obvious. Filter by text, project, model or time window; export to CSV.

Session forensics

Click a session and you get its shape — one bar per turn, cache reads beneath fresh tokens, failing turns in red, click a bar to jump — plus a cumulative-cost line, a tool mix with error segments, and a timeline where every turn expands into its tool calls, sizes, status and error text inline. Resumed sessions are stitched into one chronological thread.

Sub-agent X-ray

When a session delegates to sub-agents, Argus keeps each one: the task as it was given, its tools, tokens, cost, shape and full timeline — with an at-a-glance strip that turns red where an agent failed. No more guessing what that Task call actually did.

Trends that use rates, not totals

This period vs last, a monthly run-rate projection, tokens per session, cache-read share, and $ per million tokens as you actually experienced it — so you can tell "I'm working more" apart from "each session got more expensive".

Tool health

A leaderboard of every tool with its error share, calls per day stacked by tool, MCP servers, and sub-agent invocations by type. Three detectors re-check the last 7 days against a 4-week baseline every 10 minutes and file an alert when a tool's failures double (tool_error_rate_spike), when a project's weekly spend multiplies (cost_spike), or when its prompt-cache hit rate falls off a cliff (cache_hit_drop) — so you notice the day something breaks, not the week after.

Full-text search (opt-in)

Search every prompt you've typed and every assistant reply, thinking block and tool output. SQLite FTS5 — sub-millisecond, lexical, deterministic, offline. Off by default; see Privacy.

House rules

Every chart follows a few rules: one axis per chart, a legend whenever there's more than one series, status colours always paired with an icon and a label, and a table view behind every chart. Tokens are exact; costs are estimates, and the UI says so.

💻 CLI

argus start                 # watcher + ingester + dashboard at :4242
argus daemon start          # keep ingesting in the background (argusd)
argus indexing enable       # opt in to full-text transcript search
argus pricing refresh       # pull latest model prices from LiteLLM
argus claude init           # scaffold a good .claude/ setup into a project
argus wipe                  # delete ~/.argus/ entirely

--help works at every level.

argus                                   # top-level command group
├─ start [--port 4242] [--host 127.0.0.1] [--data-dir <path>]
│                                       # watcher + ingester + dashboard server
├─ pricing
│  └─ refresh                           # pull latest model prices from LiteLLM
├─ indexing                             # (was `search` — still works, hidden alias)
│  ├─ status                            # is transcript indexing on?
│  ├─ enable                            # turn it on (next start backfills)
│  ├─ disable                           # turn it off, keep data
│  └─ clear                             # wipe all indexed segments + disable
├─ claude                               # scaffold & manage .claude/ setups
│  ├─ init [path] [--template <name>] [--force]
│  │                                    # stamp CLAUDE.md + .claude/ into a project
│  └─ template
│     ├─ list                           # list templates (bundled + user)
│     └─ create <name> [--path <dir>] [--all]
│                                       # save a project's .claude/ as a template
├─ daemon                               # argusd — background ingestion + detectors
│  ├─ start                             # start argusd detached, write PID file
│  ├─ stop                              # stop argusd gracefully
│  ├─ restart                           # stop then start
│  ├─ status                            # running? PID + uptime
│  └─ logs [-n N] [-f]                  # tail ~/.argus/argusd.log
└─ wipe                                 # delete ~/.argus/ entirely

argus daemon start      # run argusd in the background (survives closing the terminal)
argus daemon status     # PID + uptime
argus daemon logs -f    # follow the log
argus daemon stop

🔒 Privacy & security

Argus is built for one person on one machine, and the defaults say so.

• Binds to 127.0.0.1 only. Nothing on your LAN, Wi-Fi or VPN can reach it. --host 0.0.0.0 exists, and prints a loud warning.
• No external requests, ever — except argus pricing refresh, a manual command that fetches one JSON file from LiteLLM's GitHub. No telemetry, no analytics, no LLM calls.
• Transcript indexing is opt-in. Cost and token analytics need no text content. Full-text search over prompts and transcripts requires an explicit opt-in (Settings or argus indexing enable), and opting out means the API returns nothing even if data is on disk.
• Cross-origin writes are rejected. State-changing endpoints check the Origin header against Argus's own origin — exactly — so neither a random tab nor another localhost app can flip your settings.
• A loopback Host header is required. This defeats DNS rebinding, where a site you visit repoints its domain at 127.0.0.1 to read your history. Anything else gets a 421 (skipped only when you deliberately bind 0.0.0.0).
• Transcript text never becomes HTML. The dashboard renders every transcript-derived string as text; a test forbids raw-HTML sinks in the source.
• No embeddings, no model weights. Search is a plain inverted index.

Your data is one file, ~/.argus/argus.db. argus wipe deletes it; so does rm. Vulnerability reports: SECURITY.md.

⚙️ How it works

1. Ingest. A watchdog observer tails ~/.claude/projects/<project>/<session>.jsonl. Lines are validated with pydantic, de-duplicated by message.id, and normalised into session / turn rows in SQLite (WAL mode). Resumed sessions and sub-agent files are folded into their parent.
2. Cost. Per-turn cost comes from a bundled price table sourced from LiteLLM. Tokens are exact; costs are estimates.
3. Tools. Each tool_use block becomes a row; errors come from the matching tool_result. MCP servers are parsed from mcp__<server>__<tool>; the Agent tool's subagent_type is kept so delegation is visible.
4. Search (opt-in). Two FTS5 tables — one over your prompt history, one over transcript text — indexed incrementally during the normal ingest tick.
5. Detection. A scheduler runs registered detectors every 10 minutes; findings land in an alerts inbox with a seen / resolved lifecycle, so an issue that recovers and recurs fires again instead of staying silent.
6. Dashboard. A Vite + React single-page app (uPlot and hand-drawn SVG charts), statically built and served by the FastAPI app. No Node at runtime, no network beyond /api/*.

Want the deeper tour? ARCHITECTURE.md.

🔧 Configuration

Keep more history in Claude Code itself

Claude Code deletes session files after 30 days by default. Raise it in ~/.claude/settings.json (minimum 1; it can't be disabled):

{ "cleanupPeriodDays": 365 }

Argus keeps its own copy regardless — this only widens what Claude itself retains.

📋 Requirements

• Python ≥ 3.11 with an FTS5-enabled sqlite3 (the standard CPython builds for macOS, Linux and Windows all are; Argus checks at startup and says so clearly if not).
• A ~/.claude/ directory with real session JSONL, or a Codex home ($CODEX_HOME, default ~/.codex) with rollouts under sessions/.

🛠️ Development

git clone https://github.com/KrishBhimani/argus-code.git
cd argus-code
uv sync               # install deps + create venv
uv run pytest         # ~490 tests, ~35 s
uv run argus start    # runs directly from source

Dashboard work happens in dashboard/ (Vite + React): npm install && npm run dev proxies /api to a running argus start; npm test, npm run build, npm run size and npm run e2e are the gates. The built copy in dashboard-dist/ ships inside the wheel, so end users never touch npm. See CONTRIBUTING.md.

python/argus/         Python ingest, store, server, CLI
  adapters/           Claude Code + Codex parsers + adapter registry
  store/              SQLite schema + migrations + repo
  server/             FastAPI app + /api routes
  collector/          watcher + pipeline + first-run + search backfill + alert scheduler
  core/               CoreRuntime — shared watcher+scheduler+ingest lifecycle
  daemon/             argusd: pidfile, foreground service, process control, logging
  detectors/          alert detectors (pure reads) + @register registry
  scaffold/           `argus claude` template storage / init / snapshot
  pricing/            LiteLLM-derived price table + cost compute
  schema/             pydantic data models
dashboard/            React SPA source (Vite)
dashboard-dist/       Vite build output (shipped in wheel as data)
pricing/              Bundled pricing JSON (shipped in wheel as data)
templates/            Bundled .claude/ scaffolding templates (shipped in wheel as data)
tests/                pytest suite, mirrors python/argus/ layout

MIT — see LICENSE.

Named for Argus Panoptes — the watchman with a hundred eyes, who never slept.

If it keeps good watch for you, a ⭐ helps other Claude Code users find it.