Metadata-Version: 2.4
Name: argus-code
Version: 0.2.0
Summary: Local-first dashboard for Claude Code cost, token, tool-usage, and full-text search analytics
Project-URL: Homepage, https://github.com/KrishBhimani/argus-code
Project-URL: Repository, https://github.com/KrishBhimani/argus-code.git
Project-URL: Issues, https://github.com/KrishBhimani/argus-code/issues
Author: Krish Bhimani
License: MIT License
        
        Copyright (c) 2026 Krish Bhimani
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
License-File: NOTICE
Keywords: ai-tools,analytics,anthropic,claude,claude-code,cli,cost,dashboard,llm,local-first,tokens,usage
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.115
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.9
Requires-Dist: typer>=0.12
Requires-Dist: uvicorn[standard]>=0.32
Requires-Dist: watchdog>=5.0
Description-Content-Type: text/markdown

# Argus

**Local-first analytics + persistent archive for Claude Code.** Argus reads
your `~/.claude/` session logs, computes cost from a bundled pricing table,
and serves a dashboard at `http://localhost:4242` that tells you exactly how,
when, and how much you've been using Claude Code.

Claude Code rotates its own session files (`cleanupPeriodDays` defaults to
30). Once Argus ingests a session into `~/.argus/argus.db`, the row stays
forever — so a few months in, Argus knows about sessions Claude has already
deleted. Live tools like `ccusage` can only show what's currently on disk;
Argus accumulates.

Everything stays on your machine. No telemetry, no API calls, no
embeddings — just SQLite and a static web UI.

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

That's it. Your default browser opens to the dashboard once the first-pass
ingest finishes (~5–10s for a typical install).

## What it shows you

| Page | What it answers |
|---|---|
| **Overview** | How many tokens have I burned? How much would I have paid on the API? Where does my spend land each day? Plus a **"What needs attention"** card that surfaces detector findings (e.g. a tool whose error rate spiked this week). |
| **Sessions** | Sortable table of every session — project, model, tokens, cost, duration. Click any row to drill in. |
| **Tools** | Tool-call leaderboard (Bash vs Edit vs Read vs WebFetch…), error rates per tool, MCP server breakdown, sub-agent invocations. |
| **Search** *(opt-in)* | Full-text search over every prompt you've typed AND every assistant response, your replies, and tool output. SQLite FTS5, sub-millisecond, no embeddings. |
| **Trends** | Tokens and cost bucketed by day / week / month, grouped by model. |
| **Models** | Per-model token mix and cost rollup. |
| **Settings** | Search-indexing toggle, pricing version, parse errors, data export. |

## CLI

```sh
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
├─ search
│  ├─ 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
└─ wipe                                 # delete ~/.argus/ entirely
```

Run `--help` at any level for details — `argus --help`, `argus claude --help`,
`argus claude template --help`.

### `argus claude` — project scaffolding

Set good agent config *before* you run, not just observe it after. `init`
copies a template into a project: `CLAUDE.md` goes to the project root,
everything else into `.claude/`. Existing files are skipped (use `--force`
to overwrite) — but an existing `CLAUDE.md` is **never** overwritten, even
with `--force`. The bundled `default` template ships a sensible
`settings.json`, agents, commands, rules, and a placeholder skill. Save your
own project's setup as a reusable template with `template create`; user
templates live in `~/.argus/templates/` and take precedence over bundled ones.

## Privacy & security

Argus is built for one user on one machine. The defaults reflect that:

- **Server binds to `127.0.0.1` only.** Nothing on your LAN/Wi-Fi/VPN can
  reach the dashboard. Use `argus start --host 0.0.0.0` if you really
  want LAN exposure — it prints a loud warning when you do.
- **No external requests, ever**, except `argus pricing refresh` which
  is a manual command that fetches one JSON file from LiteLLM's GitHub.
  No telemetry, no analytics pings, no LLM calls.
- **Transcript indexing is opt-in.** Cost-and-token analytics work out of
  the box without indexing any text content. Full-text search across
  prompts and transcripts requires explicit opt-in via Settings or
  `argus search enable`. Opting out actually means out — the API
  returns empty results, even if data is on disk.
- **Cross-origin POSTs are rejected.** The state-changing endpoints
  (`/api/search-index/*`) check the `Origin` header so a random tab in
  your browser can't silently wipe your data while argus is running.
- **No embeddings, no model weights.** Search uses SQLite FTS5 — pure
  inverted-index lexical search. Lookups are deterministic and offline.

Data lives at `~/.argus/argus.db`. Delete it any time with `argus wipe`
(or just remove the file).

For vulnerability reports, see [SECURITY.md](./SECURITY.md).

## How it works

1. **Ingest.** A `watchdog` observer tails every `~/.claude/projects/<project>/<session-id>.jsonl`
   file. Lines are validated with `pydantic`, deduplicated by `message.id`,
   and turned into normalized session/turn rows in SQLite (WAL mode).
2. **Cost.** Per-turn cost comes from a bundled `pricing/<version>.json`
   table sourced from [LiteLLM](https://github.com/BerriAI/litellm).
   Tokens are exact; costs are estimates and the dashboard says so.
3. **Tools.** Each `tool_use` block in the JSONL becomes a row in
   `tool_calls`. Errors come from matching `tool_result.is_error` in the
   next user message. MCP servers are extracted from tool names matching
   `mcp__<server>__<tool>`.
4. **Search (opt-in).** Two FTS5 virtual tables: one over `~/.claude/history.jsonl`
   (every prompt you've ever typed, ~150 KB indexed for a heavy user),
   one over assistant text + thinking blocks + user content + tool
   output (~30–60 MB for hundreds of sessions). Indexing happens
   incrementally during the normal ingest tick.
5. **Dashboard.** Astro 5 + ECharts, statically built, served by the
   FastAPI app (uvicorn). No server-side rendering, no Node code in the browser.
6. **Detection (alerts).** A lightweight scheduler thread runs registered
   *detectors* on a fixed cadence. Each detector reads the DB and returns
   findings; the scheduler is the sole writer, upserting them into an
   `alerts` table — idempotent, with a `resolved_at` lifecycle so an issue
   that recovers then recurs fires again instead of staying silent. The
   Overview's "What needs attention" card reads these, and critical findings
   raise a browser notification. The v1 detector flags tools whose error rate
   spiked versus their preceding 4-week baseline.

## Configuration

| Where | Knob |
|---|---|
| `argus start --port <n>` | Pick a different port (default 4242). |
| `argus start --host <h>` | Bind host (default `127.0.0.1`). Pass `0.0.0.0` for LAN exposure. |
| `argus start --data-dir <path>` | Override `~/.argus/`. |
| `pricing/*.json` | Bundled price tables. Refresh with `argus pricing refresh`. |

## Requirements

- **Python ≥ 3.11.** Argus uses the stdlib `sqlite3` module — make sure
  your Python was built with FTS5 (the standard CPython distributions
  for macOS, Linux, and Windows all are). Argus checks at startup and
  fails with a clear error if FTS5 is missing.
- A `~/.claude/` directory containing real session JSONL — i.e. you've
  used Claude Code at least once. Argus exits with a friendly message
  if it's missing.

## Keep your history longer

By default Claude Code deletes session files after 30 days. To extend the
window, set `cleanupPeriodDays` in `~/.claude/settings.json`:

```json
{
  "cleanupPeriodDays": 365
}
```

The minimum is 1; there's no way to disable cleanup entirely. Whatever you
set, Argus's own database keeps the data even after Claude rotates it out.

## Development

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

The dashboard is an Astro project under `dashboard/` and still builds via
`npm` at release time only. End users never touch npm.

Source layout:

```
python/argus/         Python ingest, store, server, CLI
  adapters/           Claude Code JSONL parsers + adapter registry
  store/              SQLite schema + migrations + repo
  server/             FastAPI app + /api routes
  collector/          watcher + pipeline + first-run + search backfill + alert scheduler
  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/            Astro source
dashboard-dist/       Astro 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
```

## License

MIT — see [LICENSE](./LICENSE).
