argus-code 0.5.2__tar.gz → 0.6.0__tar.gz

argus_code-0.6.0/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:raw.githubusercontent.com)"
+    ]
+  }
+}

{argus_code-0.5.2 → argus_code-0.6.0}/AGENTS.md

@@ -78,6 +78,17 @@ When cutting version `X.Y.Z`:
    token is the maintainer's secret; **an agent must never run this or handle the
    token.** Stop and hand off.
 
+### Screenshots (README + site)
+
+`assets/` is the only tracked image location (`docs/` is gitignored). Regenerate
+every dashboard screenshot with an Argus instance running on a spare port:
+`uv run argus start --port 4243`, then
+`node scripts/screenshots/capture.mjs --out <tmp>` and
+`node scripts/screenshots/frame.mjs --in <tmp>`. Filenames are stable; the README
+and the site repo (`KrishBhimani/argus`) hotlink them from `main`. The capture
+script redacts the Settings parse-error paths in-page before shooting; extend the
+same hook rather than editing images by hand.
+
 ## Work Guidance
 
 Global engineering rules (binding):

{argus_code-0.5.2 → argus_code-0.6.0}/ARCHITECTURE.md

@@ -174,11 +174,37 @@ Rules that matter:
   side-effect in `python/argus/detectors/__init__.py` — same pattern as
   adapters. Adding one is a new file + the import line; no scheduler edits.
 
-The v1 detector (`tool_error_rate_spike`) compares each tool's last-7-day
-error rate against its preceding 4-week baseline and fires when the rate
-multiplies past a threshold — or breaks from a zero baseline. Cost was
-deliberately *not* the v1 signal: it's meaningless for Pro/Max users who
-don't pay per token.
+Three detectors ship today. All of them compare a trailing 7-day **window**
+against the 28 days immediately before it (the **baseline**), and all of them
+gate on a volume floor so a quiet week can't fire:
+
+| Detector | Keyed on | Fires when |
+|---|---|---|
+| `tool_error_rate_spike` | tool name | the window error rate is >= 2x the baseline rate (or breaks from a zero baseline) |
+| `cost_spike` | project path | window spend is >= 2x the baseline's *per-week* average |
+| `cache_hit_drop` | project path | the input-token cache hit rate falls >= 15 points below baseline |
+
+Notes that shape those rules:
+
+- **The baseline is up to four weeks long, so cost is compared per week**, not
+  per window — otherwise every project looks cheaper than its own history. The
+  weeks are the ones the project **existed** for (from its first turn, capped
+  at 4), and a project with under a week of history is skipped: dividing a
+  10-day-old project's spend by 4 weeks made steady work read as a 9x spike
+  (77 of 137 alerts in a 100-day backtest on a real archive).
+- **Cost was deliberately not the v1 signal:** it's meaningless as *money* for
+  Pro/Max users who don't pay per token. It survives as a v2 signal because it
+  still tracks how much work the agent did; the absolute dollar floors keep
+  small projects quiet.
+- **`cache_hit_drop` divides by input tokens only** (`cache_read / (cache_read +
+  cache_write + fresh_input)`), unlike the dashboard's "cache read share" which
+  divides by all tokens. Output volume is not a caching regression, and cache
+  *writes* are exactly what a miss looks like. It measures the fall in
+  percentage points, not as a ratio: near the top of the range a ratio hides the
+  damage (96% -> 90% doubles the uncached input but reads as "0.94x").
+- Both project-keyed detectors read one aggregate,
+  `Repository.project_turn_stats_in_range`, which attributes sub-agent turns to
+  the parent session's project.
 
 ## Scaffolding (`argus claude`)
 

{argus_code-0.5.2 → argus_code-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: argus-code
-Version: 0.5.2
+Version: 0.6.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
@@ -50,28 +50,46 @@ Requires-Dist: uvicorn[standard]>=0.32
 Requires-Dist: watchdog>=5.0
 Description-Content-Type: text/markdown
 
-# Argus
+<div align="center">
 
-**The observability console for Claude Code — local-first, permanent, and honest about cost.**
+<img src="https://raw.githubusercontent.com/KrishBhimani/argus-code/main/assets/logo.svg" width="84" alt="Argus logo">
 
-[![PyPI](https://img.shields.io/pypi/v/argus-code)](https://pypi.org/project/argus-code/)
-[![Python ≥ 3.11](https://img.shields.io/badge/python-%E2%89%A5%203.11-blue)](#requirements)
-[![License: MIT](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
+<h1>Argus</h1>
+
+<p><strong>The observability console for Claude Code — local-first, permanent, and honest about cost.</strong></p>
+
+<p>
+  <a href="#-quick-start"><b>Quick start</b></a> ·
+  <a href="#-a-tour"><b>Tour</b></a> ·
+  <a href="#-cli"><b>CLI</b></a> ·
+  <a href="#-privacy--security"><b>Privacy</b></a> ·
+  <a href="./ARCHITECTURE.md"><b>Architecture</b></a> ·
+  <a href="./CONTRIBUTING.md"><b>Contributing</b></a>
+</p>
+
+<p>
+  <a href="https://pypi.org/project/argus-code/"><img src="https://img.shields.io/pypi/v/argus-code?color=f0883e" alt="PyPI"></a>
+  <a href="https://pypi.org/project/argus-code/"><img src="https://img.shields.io/pypi/dm/argus-code?color=f0883e" alt="PyPI downloads"></a>
+  <a href="#-requirements"><img src="https://img.shields.io/badge/python-%E2%89%A5%203.11-blue" alt="Python ≥ 3.11"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License: MIT"></a>
+  <a href="https://github.com/KrishBhimani/argus-code"><img src="https://img.shields.io/github/stars/KrishBhimani/argus-code?style=flat&logo=github&color=8b94a3" alt="GitHub stars"></a>
+</p>
+
+</div>
 
 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 **deletes it after
-30 days**. Argus tails those files into a SQLite archive on your machine, prices each
-turn from a bundled table, and serves a dashboard at `http://localhost:4242` that
-answers the questions the transcripts never do:
+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`.
 
-- *How much am I actually spending, and is it going up?*
-- *Which sessions were expensive — and which turn made them so?*
-- *Where do my tools fail, and when did that start?*
-- *What did that sub-agent get told, and what did it do?*
-- *When do I actually work, and on what?*
+<img src="https://raw.githubusercontent.com/KrishBhimani/argus-code/main/assets/hero.png" alt="The Argus overview — tokens, cost, sessions and tool error rate at a glance">
 
-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
 
 ```sh
 pipx install argus-code     # or:  uv tool install argus-code
@@ -79,61 +97,101 @@ 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.
+then on, every session you run is ingested live. All you need is Python ≥ 3.11 and a
+`~/.claude/` directory — i.e. you've used Claude Code at least once.
 
----
+## ✨ Why Argus
 
-## Why it exists
+**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.
 
-Tools like `ccusage` read what's on disk *right now*. 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. **It accumulates.**
+**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.
 
-And because it keeps the *structure* of each session (turns, tool calls, sub-agents,
-cache hits), it can do forensics, not just totals.
+**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
 
-## What you get
+### Every session, priced
 
-The dashboard is organised by the job you came to do.
+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.
 
-### Monitor
+<img src="https://raw.githubusercontent.com/KrishBhimani/argus-code/main/assets/screenshots/sessions.png" alt="Sessions — sortable grid with duration × tokens scatter">
 
-| Page | What it answers |
-|---|---|
-| **Overview** | Four tiles — tokens, estimated cost, sessions, tool error rate — each with its **change vs. the previous window**. A "Needs attention" strip that is always visible (it says *all clear* when there's nothing). Tokens per day, stackable by model. A 90-day activity heatmap and a **weekday × hour** map of when you start sessions. Top sessions in the window. |
-| **Alerts** | The inbox for detector findings, with unseen / all / severity filters and a 30-day strip. Today's detector flags any tool whose error rate doubled against its 4-week baseline; more are planned. |
+### Session forensics
 
-### Analyze
+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.
 
-| Page | What it answers |
-|---|---|
-| **Sessions** | A virtualised, sortable grid of every session with inline token bars. Above it, a **duration × tokens scatter** (log–log, coloured by model) that makes outliers obvious, or a per-project rollup. Filter by text, project, model, window. |
-| **Session detail** | Tiles, then a **session-shape minimap** — one bar per turn, cache reads beneath fresh tokens, failing turns in red; click a bar to jump. A cumulative-cost line. A compact timeline where every row expands into its tool calls, their sizes, status and output, and error text inline. Resumed sessions are stitched into one chronological thread. |
-| **Sub-agents** | For sessions that delegated: a sticky list with an at-a-glance strip (tokens per agent, red where one failed), filter and sort, and ↑↓ stepping. Each agent's **task as given**, tools, shape and full timeline, inline. |
-| **Tools** | Leaderboard with error segments, **tool calls per day** (columns / area / table), MCP servers, sub-agent invocations by type. |
-| **Models** | Tokens and cost per model, **$ per million tokens** as you actually experienced it, and each model's share over time. |
-| **Trends** | Built around **rates, not totals**: this period vs last, a run-rate projection, tokens per session, cache-read share, unit cost — plus the by-model lines, cumulative total and a full breakdown table. |
+<img src="https://raw.githubusercontent.com/KrishBhimani/argus-code/main/assets/screenshots/session-detail.png" alt="Session detail — per-turn shape, cumulative cost, tool mix">
 
-### Search *(opt-in)*
+### Sub-agent X-ray
 
-Full-text search over 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](#privacy--security).
+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.
 
-### Govern
+<img src="https://raw.githubusercontent.com/KrishBhimani/argus-code/main/assets/screenshots/subagents.png" alt="Sub-agents — task given, tools used, per-agent shape and cost">
 
-**Settings** (indexing toggle, pricing version, export, parse errors).
+### Trends that use rates, not totals
 
-Every chart follows a few house 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.
+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".
 
----
+<img src="https://raw.githubusercontent.com/KrishBhimani/argus-code/main/assets/screenshots/trends.png" alt="Trends — weekly tokens by model, run rate, unit cost">
+
+### 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.
+
+<img src="https://raw.githubusercontent.com/KrishBhimani/argus-code/main/assets/screenshots/tools.png" alt="Tools — leaderboard with error segments and calls per day">
+
+### 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](#-privacy--security).
+
+### 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
+
+```sh
+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.
 
-## CLI
+<details>
+<summary><b>Full command tree</b></summary>
 
 ```sh
 argus                                   # top-level command group
@@ -162,14 +220,14 @@ argus                                   # top-level command group
 └─ wipe                                 # delete ~/.argus/ entirely
 ```
 
-`--help` works at every level.
+</details>
 
-### `argus daemon` — keep ingesting when the dashboard is closed
+<details>
+<summary><b><code>argus daemon</code> — keep ingesting when the dashboard is closed</b></summary>
 
-By default the watcher and detector scheduler run *inside* `argus start`; close it
-and ingestion stops. **argusd** moves that work into a long-running background
-process. It does not serve the dashboard — port 4242 is still only bound by
-`argus start`.
+By default the watcher and detector scheduler run *inside* `argus start`; close it and
+ingestion stops. **argusd** moves that work into a long-running background process. It
+does not serve the dashboard — port 4242 is still only bound by `argus start`.
 
 ```sh
 argus daemon start      # run argusd in the background (survives closing the terminal)
@@ -183,8 +241,8 @@ read-only viewer of the database the daemon keeps fresh (the sidebar footer says
 *argusd daemon*). When it isn't, `argus start` ingests in-process exactly as before.
 
 **Living with it.** Idle cost is negligible: the watcher is event-driven and the
-scheduler wakes every 10 minutes — expect ~40–70 MB RAM and no idle CPU. Logs rotate
-at ~1 MB × 3 in `~/.argus/argusd.log`. Things to know:
+scheduler wakes every 10 minutes — expect ~40–70 MB RAM and no idle CPU. Logs rotate at
+~1 MB × 3 in `~/.argus/argusd.log`. Things to know:
 
 - **Restart after upgrading** (`argus daemon restart`) — a running daemon holds the old code.
 - **No auto-restart yet.** A crashed daemon stays down until you start it again; the stale PID file is cleaned up. OS-native autostart (`argus install`) is a follow-up.
@@ -192,18 +250,22 @@ at ~1 MB × 3 in `~/.argus/argusd.log`. Things to know:
 - **Windows `stop` is a hard kill** — safe (no critical in-memory state), but no `argusd stopped.` line lands in the log.
 - **Toggling search:** the dashboard's *Enable indexing* button indexes immediately; the CLI `argus indexing enable` flips the flag and backfills on the next `argus start` / `argus daemon restart`.
 
-### `argus claude` — scaffold good agent config
+</details>
+
+<details>
+<summary><b><code>argus claude</code> — scaffold good agent config</b></summary>
 
 Set things up well *before* you run, not just observe afterwards. `init` copies a
 template into a project: `CLAUDE.md` to the root, everything else into `.claude/`.
 Existing files are skipped (`--force` overwrites — except `CLAUDE.md`, which is never
 overwritten). The bundled `default` template ships a sensible `settings.json`, agents,
 commands, rules and a placeholder skill. Save your own project's setup with
-`template create`; user templates live in `~/.argus/templates/` and win over bundled ones.
+`template create`; user templates live in `~/.argus/templates/` and win over bundled
+ones.
 
----
+</details>
 
-## Privacy & security
+## 🔒 Privacy & security
 
 Argus is built for one person on one machine, and the defaults say so.
 
@@ -218,30 +280,25 @@ Argus is built for one person on one machine, and the defaults say so.
 Your data is one file, `~/.argus/argus.db`. `argus wipe` deletes it; so does `rm`.
 Vulnerability reports: [SECURITY.md](./SECURITY.md).
 
----
-
-## How it works
+## ⚙️ 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 `pricing/<version>.json` sourced from [LiteLLM](https://github.com/BerriAI/litellm). Tokens are exact; costs are estimates.
-3. **Tools.** Each `tool_use` block becomes a `tool_calls` 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 `~/.claude/history.jsonl` (every prompt, ~150 KB for a heavy user), one over assistant text, thinking, user content and tool output (~30–60 MB for hundreds of sessions). Indexed incrementally during the normal ingest tick.
-5. **Detection.** A scheduler thread runs registered *detectors* every 10 minutes. Each reads the DB and returns findings; the scheduler upserts them into `alerts` 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. Analyses that aren't in the API yet — prior-window deltas, tokens per session, cache-read share, calls per day — are derived client-side from the existing endpoints. No Node at runtime, no network beyond `/api/*`.
-7. **One runtime, two hosts.** The watcher, scheduler and first-pass ingest live in a single `CoreRuntime` that both `argus start` and `argusd` construct, so they can never double-ingest.
+2. **Cost.** Per-turn cost comes from a bundled price table sourced from [LiteLLM](https://github.com/BerriAI/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](./ARCHITECTURE.md).
 
----
-
-## Configuration
+## 🔧 Configuration
 
 | Where | Knob |
 |---|---|
 | `argus start --port <n>` | Port (default 4242). |
 | `argus start --host <h>` | Bind host (default `127.0.0.1`; `0.0.0.0` for LAN exposure). |
 | `argus start --data-dir <path>` | Override `~/.argus/`. |
-| `pricing/*.json` | Bundled price tables; refresh with `argus pricing refresh`. |
+| `argus pricing refresh` | Fetch the latest price table into `~/.argus/pricing/` (newest table wins). |
 
 ### Keep more history in Claude Code itself
 
@@ -254,14 +311,12 @@ Claude Code deletes session files after 30 days by default. Raise it in
 
 Argus keeps its own copy regardless — this only widens what Claude itself retains.
 
-## Requirements
+## 📋 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 — i.e. you've used Claude Code at least once.
 
----
-
-## Development
+## 🛠️ Development
 
 ```sh
 git clone https://github.com/KrishBhimani/argus-code.git
@@ -276,6 +331,9 @@ proxies `/api` to a running `argus start`; `npm test`, `npm run build`, `npm run
 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](./CONTRIBUTING.md).
 
+<details>
+<summary><b>Repository layout</b></summary>
+
 ```
 python/argus/         Python ingest, store, server, CLI
   adapters/           Claude Code JSONL parsers + adapter registry
@@ -295,6 +353,18 @@ templates/            Bundled .claude/ scaffolding templates (shipped in wheel a
 tests/                pytest suite, mirrors python/argus/ layout
 ```
 
-## License
+</details>
+
+---
+
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/KrishBhimani/argus-code/main/assets/logo.svg" width="36" alt="">
+
+<p>MIT — see <a href="./LICENSE">LICENSE</a>.</p>
+
+<p><i>Named for Argus Panoptes — the watchman with a hundred eyes, who never slept.</i></p>
+
+<p>If it keeps good watch for you, a ⭐ helps other Claude Code users find it.</p>
 
-MIT — see [LICENSE](./LICENSE).
+</div>