agentwrangler 0.1.1-next.fbffef0 → 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

@@ -16,7 +16,7 @@ Requires **Node 22-24 and npm**, plus Claude Code transcripts for populated char
 npx agentwrangler@latest
 ```
 
-Open **http://127.0.0.1:47821** if the browser does not open automatically. Keep the terminal
+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.
@@ -35,8 +35,10 @@ before starting another on the same port.
    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. After completing a supported change, use **I completed the change**
-   when offered, then **Track this change** to record a baseline.
+   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.
@@ -50,7 +52,7 @@ session inspection, and supported recommendation tracking work without either.
 
 ## Dashboard preview
 
-![Synthetic Overview: spend for the selected window, model mix, and links to sessions and recommendations](https://raw.githubusercontent.com/Doogit/AgentWrangler/main/docs/assets/overview.png)
+![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)
 
 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.
@@ -64,7 +66,7 @@ contains the other views and an optional animated preview.
 | 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) |
-| Read a weekly summary | [Briefs](https://github.com/Doogit/AgentWrangler/blob/main/docs/dashboard-tour.md#briefs) |
+| 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
 
@@ -81,22 +83,61 @@ five hooks; **Copy install prompt** prepares instructions for three. Copying alo
 
 [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.
-- SQLite contains aggregates and structural data, and can also contain local command text
-  and filesystem paths. Treat it as sensitive. The optional PreCompact hook makes separate
+- 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.
-- Usage refresh can contact Anthropic using your existing Claude Code sign-in. GitHub
-  outcomes sync requires a configured token. [Privacy details](https://github.com/Doogit/AgentWrangler/blob/main/docs/privacy.md).
+- 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.
+  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/planning/AgentWrangler_Technical_Architecture_v4_5_0.md) |
+[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)