agentwrangler 0.1.1-next.fbd0f08 → 0.2.1-next.5ed2140

package/CHANGELOG.md

@@ -0,0 +1,107 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0]
+
+A large release: a redesigned dashboard, 31 detectors (up from 9), one ranked list of recommendations with
+measured effects, and a new Rate my setup page. Usage limits are now read through your own Claude Code CLI, and
+one-click apply is off. Full notes: [docs/releases/0.2.0.md](https://github.com/Doogit/AgentWrangler/blob/main/docs/releases/0.2.0.md).
+
+### Performance
+- Opens sooner on first launch (newest sessions first, the rest in the background) and stays responsive while it
+  reads.
+- Transcript reading runs in short time slices. History, recommendations, Usage patterns and headroom are built in
+  background worker threads and served from snapshots, so page requests do not wait on them.
+- Copied or renamed transcripts are not read again, warm restarts skip unchanged files, and one browser tab polls
+  for status on behalf of the others.
+- Measured in our release test gate while a backfill is running: daemon event-loop p99 ≤ 50 ms, and each of the 67
+  budgeted API routes within its p95 latency budget (250 ms for most routes).
+
+### UI / dashboard
+- New sidebar groups, a redesigned Overview, Sessions and Workspaces, and new Usage patterns and Help pages.
+- Overview: a Usage limits card, $ and Tokens spend tabs, a 12-week chart of your implied weekly limit, and your most
+  expensive sessions of the last 7 days. Sessions is paged, with cache hit %, peak context and subagent cost columns.
+- Usage patterns groups avoidable spend and reliability problems by root cause, with the affected sessions.
+- Removed: the Briefs tab (now Rate my setup), work records, and the Overview cache-efficiency tile.
+
+### Detectors
+- 31 detectors (up from 9), each tested with a must-fire and a near-miss fixture.
+- New areas include oversized tool output, cache misses and breaks, tool error rates, edits before reads, repeated
+  errors, permission denials, subagent over-spawning and destructive operations.
+- Dollar figures are estimates at list prices; a card says **Not estimated** when it cannot price the finding.
+  Shared turns are no longer counted twice, and subagent turns are attributed and priced.
+
+### Handlers and recommendations
+- One list ranked by dollars per week; **Track** a change and AgentWrangler measures its effect over 14 days.
+  Dismissals and adoptions can be undone.
+- Each card shows a summary, why it matters, the evidence (sessions and turns) and its actions. A change it cannot
+  measure says "Effect not measured" instead of guessing.
+- Resetting recommendations keeps the ones you acted on and their measured effects.
+
+### Judge module
+- **Rate my setup** grades your Claude Code setup; optional **Judge me** asks Claude for a review after showing you
+  what will be sent.
+- Checks cover settings, hooks, CLAUDE.md and memory files, MCP servers, permissions, skills and agents. A snapshot
+  is saved each time your grade changes.
+- Judge me runs your own `claude` with no tools, no MCP servers and no saved session; secrets are blocked. Typical
+  cost: $0.30–$0.40 of your Claude usage.
+
+### Usage limits
+- Read by running your own `claude -p /usage` in the background (on by default, off in Settings), or from the
+  statusline. AgentWrangler no longer sends your Claude login token anywhere.
+- The reader runs only while the dashboard is open: at most every 5 minutes when you are active, hourly when idle,
+  and not while the statusline reading is fresh. Only percentages, reset times and model labels are kept.
+- The card keeps the last good reading across restarts and marks it stale when it is old.
+
+### Ingest and data
+- Reads `/clear`, `/compact`, session titles and subagent attribution; price fixes; one daemon per database and a
+  backup before each migration. Some unused API routes were removed (see the full notes).
+- 38 new database migrations. A database written by a newer AgentWrangler is refused instead of damaged; the
+  pre-migration backup (`.pre-migrate.bak`) is skipped above 512 MB.
+- Price fixes for Opus 5.5 and Sonnet 5.5 cache reads and Haiku 5.5 tiers, with a re-price of stored history.
+
+### CLI, install and packaging
+- **The default address is now `http://127.0.0.1:2929`** (was `127.0.0.1:47821`). Set `AW_PORT` to keep the old
+  port. Update bookmarks.
+- New `agentwrangler statusline` (install from Settings; wraps your existing statusline command).
+- New `agentwrangler audit` (experimental). The npm package now includes this changelog. Still requires Node.js 22
+  to 24.
+
+### macOS
+- Non-blocking Keychain read, a checked and time-limited Terminal.app launch for Open in Claude Code, and a macOS
+  first-run smoke test in CI.
+- The Keychain read is limited to 3 seconds and cached; the Terminal.app launch gives up after 20 seconds.
+
+### Security and privacy
+- `ANTHROPIC_API_KEY` is never passed to a `claude` that AgentWrangler starts. Write requests need a per-run token.
+- Guardrail hooks no longer skip Claude Code's permission prompt; reinstall them from Settings after upgrading.
+- The local database may hold secrets-filtered transcript excerpts; nothing leaves your machine as sync, backup or
+  telemetry.
+
+### Off in 0.2.0 / known limits
+- One-click apply is off (`403 APPLY_DISABLED`); use Copy prompt or Open in Claude Code (Settings > Advanced >
+  Experimental actions).
+- The macOS Keychain and Terminal Automation prompts are not yet tested on a real Mac.
+
+## [0.1.0] - 2026-09-04
+
+Initial public release.
+
+### Added
+- Local-first observability daemon (bound to `127.0.0.1:47821`) and a browser dashboard that joins
+  your Claude Code token spend to the pull requests each session merged or closed — entirely on your
+  machine, with no cloud backend and no telemetry.
+- Installable guardrails, turn-key from the dashboard: a dangerous-command deny hook, a PreCompact
+  checkpoint, and a context-budget warning.
+- SQLite-backed local store (`~/.agentwrangler/db.sqlite`) that persists only aggregates, ids,
+  counts, and structural anchors — never raw transcript or PR content (the SEC-101 privacy
+  invariant).
+- Optional GitHub token (read locally, never logged) powering the PR-outcomes feature.
+
+[0.2.0]: https://github.com/Doogit/AgentWrangler/releases/tag/v0.2.0
+[0.1.0]: https://github.com/Doogit/AgentWrangler/releases/tag/v0.1.0

package/README.md

@@ -1,184 +1,145 @@
 <p align="center">
-  <img src="docs/assets/logo.png" alt="AgentWrangler logo" width="260">
+  <img src="https://raw.githubusercontent.com/Doogit/AgentWrangler/main/docs/assets/logo.png" alt="AgentWrangler logo" width="200">
 </p>
 
-<h1 align="center">AgentWrangler</h1>
+# AgentWrangler
 
-<p align="center">
-  <b>See where your Claude Code tokens go — and whether the work actually shipped.</b><br>
-  Local-first observability for Claude Code: token spend, session outcomes, waste detection,
-  and installable guardrails. Runs entirely on your machine.
-</p>
-
-<p align="center">
-  <a href="https://www.npmjs.com/package/agentwrangler"><img src="https://img.shields.io/npm/v/agentwrangler" alt="npm version"></a>
-  <a href="https://github.com/Doogit/AgentWrangler/actions/workflows/ci.yml"><img src="https://github.com/Doogit/AgentWrangler/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
-  <a href="https://img.shields.io/node/v/agentwrangler"><img src="https://img.shields.io/node/v/agentwrangler" alt="node version"></a>
-  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="license"></a>
-</p>
-
-![AgentWrangler dashboard — spend verdict, model mix, recommendations, and per-repo efficiency](docs/assets/dashboard.gif)
-
-<!--
-  All screenshots and the demo GIF in this README are captured from a SANITIZED instance
-  (Vite test-mode fixtures — anonymized names, no live data) so no real workspace/repository
-  names or paths are committed (SEC-101). Regenerate against `npx vite --mode test`.
--->
-
-## Why
-
-Claude Code tells you almost nothing about where your token budget goes. Sessions balloon,
-caches miss, background agents idle — and you find out when you hit the rate limit.
-AgentWrangler reads the transcripts Claude Code already writes to your disk and answers three
-questions:
-
-- **Where did the tokens go?** Per-model, per-workspace, per-session spend with cache economics.
-- **Did the work ship?** Sessions are linked to the pull requests they merged or closed.
-- **What should I change?** Ranked waste-source detectors with modeled savings — and one-click
-  guardrail hooks that warn *inside* Claude Code before waste happens.
-
-No cloud backend, no telemetry, no account. A daemon on `127.0.0.1`, a dashboard in your
-browser, and a SQLite file in your home directory.
+See where your Claude Code tokens go, inspect costly sessions, and track whether a change helped.
+AgentWrangler reads local Claude Code transcripts and serves a dashboard on your machine.
+No account or cloud backend is required.
 
 ## Quick start
 
+Requires **Node 22-24 and npm**, plus Claude Code transcripts for populated charts.
+
 ```sh
 npx agentwrangler@latest
 ```
 
-That's it — requires Node **22–24**. The daemon starts on `http://127.0.0.1:47821`, opens your
-browser, and scans your `~/.claude/projects` transcripts in the background; the dashboard
-appears immediately and fills in as the scan completes.
-
-More options (install from source, GitHub outcomes sync, environment variables):
-**[Getting started →](docs/getting-started.md)**
-
-## Features
-
-### Overview — verdict first, details on demand
-
-One screen answers "how bad is it this week": a spend verdict with trend, your top waste
-source with a copyable fix prompt, live rate-limit gauges (5-hour and 7-day), a burn forecast
-against your calibrated weekly limit, hot sessions, cache efficiency, and per-model
-context-per-turn tiles.
-
-![Overview tab — at-a-glance verdict, rate limits, burn forecast, hot sessions](docs/assets/overview.png)
-
-### Recommendations — waste-source detectors, ranked by impact
-
-Ten detector families watch your sessions for the patterns that actually burn tokens: cache
-misses (the biggest single lever), session hygiene, retry/redundant-read loops, tool-result
-bloat, model routing, idle background sessions, and more. Each recommendation shows modeled
-weekly savings, a confidence tier, and a concrete action — install a hook, copy a config
-snippet, or copy a guided prompt straight into Claude Code. Adopted changes flow into an
-**impact ledger** that tracks the measured effect, and modeled savings are never counted as
-achieved.
-
-![Recommendations tab — ranked detector families with modeled savings and one-click actions](docs/assets/recommendations.png)
-
-### Installable guardrails — local checks inside Claude Code, before the waste
-
-Five small hooks you can install from the dashboard (directly, or via a copyable prompt that
-Claude Code applies itself):
-
-| Guardrail | What it does |
-|---|---|
-| **Context-budget warning** | Warns when a session's context crosses your soft/hard thresholds |
-| **Loop guard** | Flags repeated identical tool failures before they spiral |
-| **Burn alert** | Catches idle sessions still burning tokens in the background |
-| **Pre-compaction checkpoint** | Copies the raw local transcript before an automatic compaction, subject to a local retention cap |
-| **Dangerous-command guard** | Asks before risky shell commands and denies a small catastrophe list |
-
-The context-budget and burn hooks warn. The loop guard warns before it denies repeated identical
-failures, and the dangerous-command guard can ask or deny. Direct install enables all five hooks;
-the copied install prompt enables the context-budget, loop, and burn hooks only. Thresholds are
-tunable from Settings, and direct uninstall removes every AgentWrangler hook.
-
-### Sessions — who spent it, and on what
-
-The highest-cost sessions ranked with their output-to-context split, model, friction band
-(API errors, tool failures, compactions, interrupts), and a "top X% by spend" self-percentile
-chip. Drill into any session for a turn-by-turn timeline, its cost drivers (which detectors
-fired and how hard), and a guided fix prompt built only from measured numbers.
-
-![Sessions tab — highest-cost sessions with friction bands and spend percentiles](docs/assets/sessions.png)
-
-<details>
-<summary>Session detail view</summary>
-
-![Session detail — per-session KPIs, cost drivers, and a measured-context fix prompt](docs/assets/session-detail.png)
-</details>
-
-### Workspaces — spend efficiency by repository
-
-Every repo you run Claude Code in, with spend share, trend, context-per-turn, cache-write
-share, Opus share, and $/turn. With a GitHub token configured, sessions are linked to the PRs
-and commits they produced — so you can see cost-per-merged-PR, not just cost.
-
-![Workspaces tab — per-repository spend, efficiency, and outcome linkage](docs/assets/workspaces.png)
-
-<details>
-<summary>Workspace detail view</summary>
-
-![Workspace detail — top sessions, context composition, and outcomes](docs/assets/workspace-detail.png)
-</details>
-
-### Weekly brief — one page, three decisions
-
-The week in one screen: spend verdict, what changed vs. last week, the top actions to take —
-with a **Copy as Markdown** button so the whole brief drops into a standup note or a message.
+Open **http://127.0.0.1:2929** if the browser does not open automatically. Keep the terminal
+running; press **Ctrl+C** to stop. The first scan runs in the background. An empty history is
+valid: use Claude Code, then return after ingestion. If a daemon is already running, stop it
+before starting another on the same port.
 
-![Briefs tab — weekly verdict, week-over-week deltas, and top actions](docs/assets/briefs.png)
+[Install from source, configure scan roots, or troubleshoot](https://github.com/Doogit/AgentWrangler/blob/main/docs/getting-started.md).
 
-### Honest numbers, labeled as such
+## Your first five minutes
 
-Every metric carries an honesty-tier chip — `EXACT`, `LIST_EQUIV`, `MODELED`, `PROXY`,
-`DIRECTIONAL`, `EXPERIMENTAL` — so you always know what is measured versus estimated. Dollar
-figures are list-price *equivalents* (subscription plans aren't billed per token; tokens drive
-rate limits), and the built-in glossary ("How to read this dashboard") defines every
-key metric in plain language. The full tour: **[Dashboard tour →](docs/dashboard-tour.md)**
+1. **Check the scan.** In Overview, read the onboarding status. A completed scan with no
+   recommendations is a valid result. For an unexpected empty history, inspect scan roots
+   and parser health in Settings; saved scan-root changes require a daemon restart.
+2. **Find one expensive session.** Select a date window, open Workspaces, choose a workspace,
+   then open one of its sessions. Compare context, cache writes, and output before deciding
+   what to change.
+3. **Inspect one recommendation.** Open Recommendations and **Show details** on an instance.
+   Read its evidence and caveats. A modeled amount is a projection; directional advice may
+   have no dollar estimate. If nothing fires, there is nothing to adopt just to finish setup.
+4. **Make one deliberate change.** A copied prompt is an artifact to review and run yourself.
+   It does not edit files. **Open in Claude Code** (Settings > Advanced > Experimental actions,
+   off by default) starts your own `claude` in a terminal; nothing is applied for you. After
+   completing a supported change, use **I completed the change** when offered, then **Track**
+   to record a baseline.
+5. **Return to the Impact ledger.** Tracking starts observation, not a savings claim. Eligible
+   signals use a 14-day observation window and may finish inconclusive. You can finish this
+   first visit without a GitHub token, calibration, or installed hooks.
 
-## Privacy — local-only by design
+Dollar figures are **list-price equivalents**, not your subscription bill. Modeled savings
+are not achieved savings, and observed improvement does not prove the change caused it.
+GitHub linkage adds outcome metadata; calibration enables the burn forecast. Local spend,
+session inspection, and supported recommendation tracking work without either.
 
-- The daemon binds to **`127.0.0.1`** only. There is no cloud backend, telemetry, or account.
-- Most dashboard data is **aggregates, ids, counts, and structural anchors**. Local command text
-  and filesystem paths can also be retained in SQLite; treat the database as sensitive. The optional
-  direct-install PreCompact hook can separately copy full raw transcripts locally.
-- The optional GitHub token is read locally, never logged, never persisted to the DB.
-- Usage refreshes can call Anthropic with an existing Claude Code sign-in. GitHub outcomes sync
-  calls GitHub only when a token is configured; calibration and G2 judging are separate opt-ins.
+[Worked example: trim always-loaded context and inspect its effect](https://github.com/Doogit/AgentWrangler/blob/main/docs/getting-started.md#example-trim-always-loaded-context).
 
-Full details, including exactly what is and isn't stored: **[Privacy model →](docs/privacy.md)**
+## Dashboard preview
 
-## Configuration
+![Synthetic Overview: usage limits read through Claude Code /usage, spend for the selected window, and the top recommendations](https://raw.githubusercontent.com/Doogit/AgentWrangler/main/docs/assets/overview.png)
 
-Everything is optional with sensible defaults — port, DB path, scan roots, GitHub token, and
-more are environment variables documented in [Getting started](docs/getting-started.md#configuration)
-and [`.env.example`](.env.example).
+This static preview uses synthetic data. [The dashboard tour](https://github.com/Doogit/AgentWrangler/blob/main/docs/dashboard-tour.md)
+contains the other views and an optional animated preview.
 
-## Documentation
+## Pick a question
 
-| Page | What's in it |
+| I want to... | Start here |
 |---|---|
-| [Getting started](docs/getting-started.md) | Install paths, optional setup, configuration, troubleshooting |
-| [Dashboard tour](docs/dashboard-tour.md) | Every tab in depth, plus the metric vocabulary |
-| [Privacy model](docs/privacy.md) | Local storage, raw-checkpoint exception, and network integrations |
-| [Architecture](docs/planning/AgentWrangler_Technical_Architecture_v4_5_0.md) | Daemon, ingestion, detector, and query design |
-| [Data model & metrics](docs/planning/AgentWrangler_Data_Model_and_Metrics_v2.md) | SQLite schema and metric definitions |
-| [Contributing](.github/CONTRIBUTING.md) | Dev setup, checks, PR expectations |
-| [Security policy](.github/SECURITY.md) | Threat model and how to report a vulnerability |
-
-## Limitations
-
-- Reads Claude Code's JSONL transcript format; an upstream format change can require an
-  ingestion update.
-- Tested on Windows; macOS/Linux are believed working — reports welcome.
-- Single local user by design — no multi-user or team-aggregation mode.
-- Outcome linkage needs a read-only GitHub token; without one the feature stays inert (and
-  Settings says so — nothing fails silently).
-
-## License
-
-[Apache 2.0](LICENSE) © 2026 AgentWrangler contributors.
-See [CONTRIBUTING.md](.github/CONTRIBUTING.md), [SECURITY.md](.github/SECURITY.md), and
-[CODE_OF_CONDUCT.md](.github/CODE_OF_CONDUCT.md).
+| Find where my tokens went | [Workspaces and Sessions](https://github.com/Doogit/AgentWrangler/blob/main/docs/dashboard-tour.md#workspaces) |
+| Turn a recommendation into a change | [Worked example](https://github.com/Doogit/AgentWrangler/blob/main/docs/getting-started.md#example-trim-always-loaded-context) |
+| Understand the dollars and verdicts | [Metric vocabulary](https://github.com/Doogit/AgentWrangler/blob/main/docs/dashboard-tour.md#glossary-how-to-read-this-dashboard) |
+| Fix an empty dashboard | [First launch](https://github.com/Doogit/AgentWrangler/blob/main/docs/getting-started.md#first-launch) |
+| Connect GitHub or calibrate limits | [Optional setup](https://github.com/Doogit/AgentWrangler/blob/main/docs/getting-started.md#optional-setup) |
+| Grade my Claude Code setup | [Rate my setup](https://github.com/Doogit/AgentWrangler/blob/main/docs/dashboard-tour.md#rate-my-setup): a score and tier against a cited rubric, what the next tier needs, and an optional AI review |
+
+## Installable guardrails — local checks inside Claude Code, before the waste
+
+Hooks are optional and require an explicit install. Settings **Install directly** installs
+five hooks; **Copy install prompt** prepares instructions for three. Copying alone installs nothing.
+
+| Hook | Behavior | Install path |
+|---|---|---|
+| Context-budget | Warns when context crosses configured thresholds | Direct or copied prompt |
+| Loop guard | Warns, then can deny repeated identical failures | Direct or copied prompt |
+| Burn alert | Warns about session budget consumption | Direct or copied prompt |
+| Dangerous-command | Can ask or deny risky commands | Direct only |
+| PreCompact checkpoint | Copies raw transcripts locally, with retention limits | Direct only |
+
+[Installation, removal, and the checkpoint privacy details](https://github.com/Doogit/AgentWrangler/blob/main/docs/getting-started.md#in-session-guardrails).
+
+## Usage limits — read from Claude Code
+
+By default AgentWrangler runs your own `claude -p /usage` in the background, only while the
+dashboard is open: at most every 5 minutes when you have been active, hourly when idle, and not
+while the statusline reading is fresh. It runs your own `claude` CLI and never reads your Claude
+login. It stores only percentages, reset times and model labels in
+`~/.agentwrangler/usage-cli.json`. Turn it off with the Settings checkbox **Read usage via Claude
+Code /usage** or `AW_USAGE_CLI=off`.
+
+The Claude Code statusline is the optional alternative: it updates on every turn and makes no
+background calls. Settings **Install statusline** points Claude Code's `statusLine` at
+`agentwrangler statusline`, after showing the exact before/after of `~/.claude/settings.json` and
+saving a timestamped backup. It prints a one-line status (model, repo, branch, context, 5h/7d
+limits, session cost) and saves only the two limit percentages and reset times to
+`~/.agentwrangler/statusline-limits.json`. An existing statusline keeps running and displaying
+(`--wrap "<your command>"`); Uninstall restores it. The 5-hour and weekly figures come from
+whichever reading is newer; per-model weekly rows come only from `/usage`.
+
+## Privacy and limits
+
+- The daemon binds to **127.0.0.1**. There is no telemetry or hosted product backend. By default
+  the only outbound call is your own `claude` CLI's `/usage` call for Usage limits; GitHub sync,
+  Judge me and calibration are opt-in.
+- SQLite holds token counts and structural data, filesystem paths, and some transcript
+  content: the shell command text of tool calls and short error excerpts from failed tool
+  results, after a best-effort secrets filter. Recommendation cards also read the calls behind
+  a finding back from your transcripts to show what ran. All of it stays on your machine.
+  Treat the database and any backups as sensitive. The optional PreCompact hook makes separate
+  raw transcript copies on your machine.
+- Rate my setup's optional **Judge me** review sends a redacted summary of your setup to Claude
+  through your own `claude` CLI, only after you approve the exact payload. GitHub outcomes sync
+  requires a configured token. [Privacy details](https://github.com/Doogit/AgentWrangler/blob/main/docs/privacy.md).
+- Claude Code format changes can require parser updates. This is a single-user tool.
+- Windows local validation and Linux/macOS CI smoke coverage do not establish full native
+  accessibility or credential-store compatibility on every platform. The macOS Keychain and
+  Terminal.app Automation prompts have not been tested on a real Mac in 0.2.0.
+
+## How it works
+
+![How data moves through AgentWrangler: logs are read and priced, detectors find waste, and the dashboard serves recommendations](https://raw.githubusercontent.com/Doogit/AgentWrangler/main/docs/assets/how-it-works.png)
+
+AgentWrangler is one local Node process. It tails Claude Code's log files (new lines every 2 s,
+new files every 30 s), stores what it needs in SQLite at `~/.agentwrangler/db.sqlite`, and runs
+detectors over the data to build recommendations. Long passes run in worker threads so the
+dashboard stays responsive. The browser UI talks to the daemon at `127.0.0.1:2929`. There is no
+separate service or scheduled task: stop the daemon and its background work stops.
+
+[Background jobs, ingest, storage, detectors, API, and the privacy boundary](https://github.com/Doogit/AgentWrangler/blob/main/docs/how-it-works.md).
+
+## Deeper documentation
+
+[What's new](https://github.com/Doogit/AgentWrangler/blob/main/CHANGELOG.md) |
+[In-app Help guide](https://github.com/Doogit/AgentWrangler/blob/main/docs/help/guide.md) |
+[Configuration](https://github.com/Doogit/AgentWrangler/blob/main/docs/getting-started.md#configuration) |
+[Architecture](https://github.com/Doogit/AgentWrangler/blob/main/docs/how-it-works.md) |
+[Data model and metrics](https://github.com/Doogit/AgentWrangler/blob/main/docs/planning/AgentWrangler_Data_Model_and_Metrics_v2.md) |
+[Contributing](https://github.com/Doogit/AgentWrangler/blob/main/.github/CONTRIBUTING.md) |
+[Security policy](https://github.com/Doogit/AgentWrangler/blob/main/.github/SECURITY.md)
+
+[Apache 2.0](https://github.com/Doogit/AgentWrangler/blob/main/LICENSE).