# AgentWorth — full text

> Every agent says it's done. AgentWorth checks the git log. Generated 2026-09-02 from https://agentworth.dev. Source: https://github.com/unfoundbox-crew/agentworth (Apache-2.0).

## Install

    npx -y agentworth scan
    curl -fsSL https://agentworth.dev/install.sh | sh
    agentworth serve

## MCP tools

- sessions_find: filter the index by adapter, model, repo, time or outcome
- session_get: one session with its events, tokens and outcome rung
- blame_find: which session, model and prompt produced a line of code
- usage_summary: tokens and cost rolled up by day, week or month
- pacing_window: throughput over a moving window
- coverage_stats: which adapters are detected and what they yield
- outcome_rate: verified-outcome rate by model, adapter or repo, with an n floor
- session_handoff: what a session promised, decided and did not finish
- carry_forward: what the previous session left for this one
- forgotten_context: decisions compaction dropped, returned verbatim with receipts
- suspect_commits: commits whose session had no exit-0 test or a demoted claim

## AgentWorth Reference

_Generated by `agentworth docs --write` from v0.1.14 on 2026-09-02. Do not edit by hand -- regenerate with `agentworth docs --write` (see `apps/cli/src/commands/docs.rs`)._

Three sections, each read straight from the running code: every `clap` subcommand and flag, every route the local API server registers, and every MCP tool this binary exposes over stdio.

### CLI

#### Global flags

Accepted before the subcommand on every command below.

| Flag | Required | Help | Default | Values |
|---|---|---|---|---|
| `--verbose, -v` | no | Enable verbose debug logging | false | - |
| `--db-path` | no | Custom path for the local SQLite index database | - | - |
| `--no-json` | no | Force text output even if persisted config defaults to JSON (see `agentworth config`) | false | - |
| `--no-color` | no | Disable colour. NO_COLOR in the environment does the same thing | false | - |
| `--plain` | no | No colour and ASCII-only glyphs, at identical column positions | false | - |

#### `agentworth scan`

Scan and index agent histories from the local system

| Flag | Required | Help | Default | Values |
|---|---|---|---|---|
| `PATHS` | no | Optional specific paths or directories to scan | - | - |
| `--force, -f` | no | Force rescanning and re-indexing of unchanged source files | false | - |
| `--include-stubs` | no | Keep storing/pruning near-empty stub sessions instead of filtering them out | false | - |
| `--json` | no | Output scan results as formatted JSON | false | - |

#### `agentworth stats`

Show machine-wide summary statistics of indexed traces

| Flag | Required | Help | Default | Values |
|---|---|---|---|---|
| `--json` | no | Output summary statistics as formatted JSON | false | - |

#### `agentworth traces`

List indexed traces with optional filtering

| Flag | Required | Help | Default | Values |
|---|---|---|---|---|
| `--limit, -l` | no | Maximum number of traces to display (default 20, or persisted `config limit`) | - | - |
| `--adapter, -a` | no | Filter by adapter name (e.g. claude_code, codex, gemini, opencode) | - | - |
| `--model, -m` | no | Filter by model substring (e.g. sonnet, gpt-4o, gemini-2.5) | - | - |
| `--all-stubs` | no | Include 1-event session stubs in the listing | false | - |
| `--json` | no | Output traces as formatted JSON | false | - |

#### `agentworth matrix`

Display extraction capabilities and coverage matrix across all 20 agent adapters

| Flag | Required | Help | Default | Values |
|---|---|---|---|---|
| `--json` | no | Output matrix as formatted JSON | false | - |

#### `agentworth inspect`

Inspect a specific trace session in detail with timeline visualization

| Flag | Required | Help | Default | Values |
|---|---|---|---|---|
| `SESSION_ID` | yes | The session ID to inspect | - | - |
| `--json` | no | Output raw trace structure as formatted JSON | false | - |

#### `agentworth export`

Export a trace session safely in JSON or ATIF format

| Flag | Required | Help | Default | Values |
|---|---|---|---|---|
| `SESSION_ID` | yes | The session ID to export | - | - |
| `--redact, -r` | no | Apply redaction to mask secrets, API keys, tokens, emails, and home paths | false | - |
| `--format, -f` | no | Export format: json (default), atif, receipt, or svg | json | json, atif, receipt, terminal, ansi, svg |
| `--output, -o` | no | Optional file path to write export output to (defaults to stdout) | - | - |

#### `agentworth receipt`

Generate and render an authentic ANSI or SVG Flight Receipt for a trace session

| Flag | Required | Help | Default | Values |
|---|---|---|---|---|
| `SESSION_ID` | yes | The session ID to generate flight receipt for | - | - |
| `--format, -f` | no | Output format: terminal (default), ansi, svg, receipt, or json | terminal | terminal, ansi, svg, receipt, json |
| `--output, -o` | no | Optional file path to write receipt or SVG output to (defaults to stdout) | - | - |

#### `agentworth search`

Semantic vector search across indexed trajectory turns with ASCII thermal receipts

| Flag | Required | Help | Default | Values |
|---|---|---|---|---|
| `QUERY` | yes | Search query (natural language or code snippet) | - | - |
| `--limit, -l` | no | Maximum number of results to return (default 10, or persisted `config limit`) | - | - |
| `--min-score` | no | Minimum similarity score threshold (0.0 to 1.0) | 0 | - |
| `--kind, -k` | no | Filter by chunk kind (summary, error_recovery, tool_invocation, apology_panic, code_lineage) | - | - |
| `--json` | no | Output results as JSON | false | - |

#### `agentworth audit`

Safety and threat audit detecting forbidden commands, leaked variables, sweeps, and fake claims

| Flag | Required | Help | Default | Values |
|---|---|---|---|---|
| `--safety` | no | Restrict audit to safety and threat vectors only | false | - |
| `--json` | no | Output audit results as formatted JSON | false | - |

#### `agentworth blunder`

Discover top agent blunders, render thermal receipts, and export to the Hall of Blunders

| Flag | Required | Help | Default | Values |
|---|---|---|---|---|
| `--top, -t` | no | Number of top blunder exhibits to retrieve and display (default: 5) | 5 | - |
| `--submit, -s` | no | Submit redacted blunder receipts to the public Hall of Blunders at stfuopus.lol | false | - |
| `--json` | no | Output blunder exhibits as formatted JSON | false | - |

#### `agentworth serve`

Start the local API server and interactive explorer UI

| Flag | Required | Help | Default | Values |
|---|---|---|---|---|
| `--port, -p` | no | Port to bind the server to | 3000 | - |
| `--open` | no | Automatically open the Web UI in the default browser | false | - |
| `--dist` | no | Optional path to custom web frontend dist directory | - | - |

#### `agentworth mcp`

Start the read-only MCP server over stdio, for a coding agent to query this machine's session index mid-session (see docs/specs/mcp-server.md). Register it once with `claude mcp add agentworth --scope user -- agentworth mcp`

#### `agentworth usage`

View deep usage, pacing, and token expenditure rollups

| Flag | Required | Help | Default | Values |
|---|---|---|---|---|
| `--period, -p` | no | Rollup period: day, week, or month (default day, or persisted `config period`) | - | day, week, month |
| `--pacing` | no | Show 5-hour rolling pacing window (burn rate, active models, quota headroom) | false | - |
| `--hours` | no | Pacing window duration in hours | 5 | - |
| `--alert-above` | no | Alert and highlight if window spend exceeds this threshold in USD | - | - |
| `--limit, -l` | no | Maximum number of rows to display (default 20, or persisted `config limit`) | - | - |
| `--by-model` | no | Group the rollup by model instead of adapter (e.g. how many tokens each of claude-opus-5 / claude-sonnet-5 / claude-fable-5 used) | false | - |
| `--json` | no | Output usage data as JSON | false | - |

#### `agentworth blame`

Trace file modifications back to the AI agent session, model, and prompt that authored them

| Flag | Required | Help | Default | Values |
|---|---|---|---|---|
| `FILE_PATH` | yes | Target file path or pattern to search | - | - |
| `--json` | no | Output results as JSON | false | - |

#### `agentworth handoff`

Hand a session over: what it promised and dropped, decided, changed, ran, and proved

| Flag | Required | Help | Default | Values |
|---|---|---|---|---|
| `SESSION_ID` | no | Session to hand over. Defaults to the newest session indexed for this directory's repository, which is what `--last` also selects | - | - |
| `--last` | no | Hand over the newest session for this repository. The default when no ID is given | false | - |
| `--redact, -r` | no | Mask secrets, paths, and this session's own repository name before printing | false | - |
| `--markdown` | no | Emit the same markdown the `session_handoff` MCP tool returns | false | - |
| `--max-lines` | no | Line budget for `--markdown` (default 60, ceiling 120) | - | - |
| `--json` | no | Output the structured handoff as JSON | false | - |

#### `agentworth forgotten`

What compaction dropped: decisions this session made and its own summaries did not keep

| Flag | Required | Help | Default | Values |
|---|---|---|---|---|
| `SESSION_ID` | no | Session to diff, by full ID or a unique prefix. Defaults to the newest session indexed for this directory's repository | - | - |
| `--round` | no | One 1-based compaction round. Defaults to every round | - | - |
| `--class` | no | Any of decision, rejected, reason. Repeatable. Defaults to all three | - | - |
| `--limit` | no | How many statements to return, newest first (default 20, ceiling 200) | - | - |
| `--redact, -r` | no | Mask secrets, paths, and this session's own repository name before printing | false | - |
| `--json` | no | Output the structured diff as JSON | false | - |

#### `agentworth asks`

The questions you asked and where their answers are -- built so you never have to re-scroll or re-ask because the answer landed several messages later

| Flag | Required | Help | Default | Values |
|---|---|---|---|---|
| `--session` | no | Session to index, by full ID, a unique prefix, or a raw JSONL file path (parsed directly if it isn't an indexed session). Defaults to the newest session for this directory's repository, same as `--current` | - | - |
| `--current` | no | Resolve the newest session for this directory's repository. The default when `--session` is not given -- this flag exists so an invocation can say that on purpose | false | - |
| `--since` | no | Only questions asked at or after this time: RFC 3339, `YYYY-MM-DD`, or a relative duration like `2h`, `30m`, `1d`, `3w` | - | - |
| `--unanswered` | no | Only questions that are not `answered` -- still open, or flagged back to you | false | - |
| `--json` | no | Output the structured index as JSON | false | - |

#### `agentworth loose-ends`

The handoff's loose-ends section alone: what a session said it would do and did not

| Flag | Required | Help | Default | Values |
|---|---|---|---|---|
| `SESSION_ID` | no | Session to check. Defaults to the newest session for this directory's repository | - | - |
| `--last` | no | Check the newest session for this repository. The default when no ID is given | false | - |
| `--redact, -r` | no | Mask secrets, paths, and this session's own repository name before printing | false | - |
| `--prompt` | no | Print the copyable prompt to hand to an agent that has the repository open | false | - |
| `--json` | no | Output the loose ends as JSON | false | - |

#### `agentworth doctor`

Check local environment, adapter discoveries, and SQLite database health

| Flag | Required | Help | Default | Values |
|---|---|---|---|---|
| `--json` | no | Output diagnostic report as formatted JSON | false | - |

#### `agentworth version`

Print version details: binary version, npm install detection, and a live check for a newer release

| Flag | Required | Help | Default | Values |
|---|---|---|---|---|
| `--offline` | no | Skip the live GitHub-releases update check (fully local, no network call) | false | - |
| `--json` | no | Output as formatted JSON | false | - |

#### `agentworth update`

Check for a newer AgentWorth release and show exactly how to get it

| Flag | Required | Help | Default | Values |
|---|---|---|---|---|
| `--offline` | no | Skip the live GitHub-releases check and just show install-method guidance | false | - |
| `--json` | no | Output as formatted JSON | false | - |

#### `agentworth merge`

Merge another local SQLite index database into this index

| Flag | Required | Help | Default | Values |
|---|---|---|---|---|
| `SOURCE_DB` | yes | Path to the source SQLite database file to merge from | - | - |
| `--json` | no | Output results as JSON | false | - |

#### `agentworth watch`

Watch active session transcripts and detect doom loops or file edit thrashing

| Flag | Required | Help | Default | Values |
|---|---|---|---|---|
| `--interval-secs, -i` | no | Polling interval in seconds (default: 3) | 3 | - |
| `--poll-once` | no | Run a single poll check and exit immediately | false | - |
| `--json` | no | Output findings as formatted JSON | false | - |
| `--paths, -p` | no | Custom path directories to monitor | - | - |

#### `agentworth cache-doctor`

Diagnose turn-by-turn prompt caching dynamics and identify cache drop root causes

| Flag | Required | Help | Default | Values |
|---|---|---|---|---|
| `SESSION_ID` | yes | Target session ID to inspect | - | - |
| `--json` | no | Output findings as formatted JSON | false | - |

#### `agentworth blind-spots`

List sessions whose completion claims were never independently corroborated by tests or CI

| Flag | Required | Help | Default | Values |
|---|---|---|---|---|
| `--limit, -l` | no | Maximum number of sessions to list (default 20, or persisted `config limit`) | - | - |
| `--json` | no | Output results as JSON | false | - |

#### `agentworth threat-digest`

Rank indexed sessions by real secret/credential exposure risk, by category and severity

| Flag | Required | Help | Default | Values |
|---|---|---|---|---|
| `--limit, -l` | no | Maximum number of sessions to show in the report (default 20, or persisted `config limit`) -- every indexed session is still scanned; this only trims the displayed list | - | - |
| `--min-severity` | no | Only include sessions whose worst finding is at least this severity | low | low, medium, high, critical |
| `--json` | no | Output results as JSON | false | - |

#### `agentworth autopsy`

Surface recurring human correction and steering phrases across all sessions

| Flag | Required | Help | Default | Values |
|---|---|---|---|---|
| `--min-occurrences, -m` | no | Minimum number of occurrences across sessions to report (default: 2) | 2 | - |
| `--json` | no | Output results as JSON | false | - |

#### `agentworth recall`

Semantically recall past solutions joined with outcome validation and cost

| Flag | Required | Help | Default | Values |
|---|---|---|---|---|
| `QUERY` | yes | Search query to match against previous trajectories | - | - |
| `--limit, -l` | no | Maximum number of results to return (default 5, or persisted `config limit`) | - | - |
| `--min-score` | no | Minimum similarity score threshold (0.0 to 1.0) | 0 | - |
| `--json` | no | Output results as JSON | false | - |

#### `agentworth bisect`

Pinpoint the exact turning point where an agent session trajectory turned negative

| Flag | Required | Help | Default | Values |
|---|---|---|---|---|
| `SESSION_ID` | yes | Session ID to bisect | - | - |
| `--json` | no | Output results as JSON | false | - |

#### `agentworth pr-blame`

Annotate changed PR files with AI agent authoring provenance and outcome validation

| Flag | Required | Help | Default | Values |
|---|---|---|---|---|
| `FILES` | no | List of files to check (if omitted, infers from git diff) | - | - |
| `--json` | no | Output results as JSON | false | - |

#### `agentworth blunder-blame`

Bridge AI Code Blame with the Hall of Blunders: trace a recorded blunder forward to the exact files it blame-attributes to, or a file's blame history backward to any recorded blunders in the sessions blamed for it

| Flag | Required | Help | Default | Values |
|---|---|---|---|---|
| `--file` | no | Blame -> blunder direction: file path or pattern. Checks every session AI Code Blame attributes this file to for a recorded blunder | - | - |
| `--session` | no | Blunder -> blame direction: one specific session ID. Resolves it to the files AI Code Blame attributes to that session | - | - |
| `--top, -t` | no | In default mode (no --file or --session), number of top blunders to bridge | 5 | - |
| `--json` | no | Output results as JSON | false | - |

#### `agentworth suspect`

List commits on this branch whose authoring session never proved anything, so you know where to look twice before pushing. Prints a list and a prompt, never a patch

| Flag | Required | Help | Default | Values |
|---|---|---|---|---|
| `--repo` | no | Path to a git checkout. Defaults to the current directory | - | - |
| `--since` | no | A date (RFC 3339 or YYYY-MM-DD) or a git ref to measure from. Defaults to the branch's upstream, then origin/main | - | - |
| `--branch` | no | Branch to walk. Defaults to HEAD | - | - |
| `--base` | no | Ref to diff against, if you want to name it separately from --since | - | - |
| `--window-hours` | no | How long before a commit a session's file touch still counts as authoring it | - | - |
| `--hook` | no | Print a ready-to-install pre-push hook and exit. The hook never blocks a push | false | - |
| `--quiet` | no | Print only the copyable prompt, and only when something is suspect. What the hook runs | false | - |
| `--json` | no | Output the full report as JSON | false | - |

#### `agentworth config`

Get, set, or list persisted CLI defaults (~/.agentworth/config.toml)

#### `agentworth config list`

List every persisted config key and its current value

| Flag | Required | Help | Default | Values |
|---|---|---|---|---|
| `--json` | no | Output as JSON | false | - |

#### `agentworth config get`

Print the persisted value for one config key

| Flag | Required | Help | Default | Values |
|---|---|---|---|---|
| `KEY` | yes | Config key: json, limit, or period | - | - |
| `--json` | no | Output as JSON | false | - |

#### `agentworth config set`

Persist a default value for one config key

| Flag | Required | Help | Default | Values |
|---|---|---|---|---|
| `KEY` | yes | Config key: json, limit, or period | - | - |
| `VALUE` | yes | Value to store (json: true/false, limit: a number, period: day/week/month) | - | - |
| `--json` | no | Output as JSON | false | - |

#### `agentworth docs`

Generate CLI, HTTP API, and MCP tool reference documentation from the code itself (see docs/REFERENCE.md). Nothing here is hand-written prose: the CLI section walks the clap command tree, the API section walks the axum route table, and the MCP section walks the rmcp tool router -- so the reference cannot drift from the code

| Flag | Required | Help | Default | Values |
|---|---|---|---|---|
| `--format` | no | Output format when printing to stdout (ignored with --write, which always writes both forms) | markdown | markdown, json |
| `--write` | no | Write docs/REFERENCE.md and docs/reference.json (relative to the current directory, which must be the repository root) instead of printing to stdout | false | - |

### HTTP API

Registered by `agentworth serve` under `http://localhost:<port>` (default port 3000). Every route below lives in one table, `server::routes::route_entries()`, that also builds the live router -- so this list cannot list a route the server doesn't actually serve.

#### `GET /api/stats`

Machine-wide experience stats with outcome distributions and verification telemetry

#### `GET /api/traces`

Filtered, paginated list of indexed sessions

| Query Param | Description |
|---|---|
| `adapter` | Filter by adapter name |
| `model` | Filter by model substring |
| `search` | Full-text search across session content |
| `outcome` | Filter by primary outcome kind |
| `min_tokens` | Minimum total token count |
| `limit` | Maximum number of sessions to return (default 50) |
| `offset` | Number of sessions to skip |
| `order_by` | Sort order for the result list |

#### `GET /api/traces/:id`

Full trace details: metadata, stats, 5-factor score, outcome evidence, timeline

| Query Param | Description |
|---|---|
| `offset` | Number of events to skip (default 0) |
| `limit` | Maximum number of events to return (default: all) |

#### `GET /api/traces/:id/events`

Just the paginated event slice for one trace

| Query Param | Description |
|---|---|
| `offset` | Number of events to skip (default 0) |
| `limit` | Maximum number of events to return (default: all) |

#### `GET /api/usage`

Daily, weekly, and monthly token usage rollups

| Query Param | Description |
|---|---|
| `daily_limit` | Maximum number of daily rollup rows |
| `weekly_limit` | Maximum number of weekly rollup rows |
| `monthly_limit` | Maximum number of monthly rollup rows |

#### `GET /api/pacing`

Rolling pacing window: burn velocity and cache hit ratio

| Query Param | Description |
|---|---|
| `hours` | Pacing window duration in hours (default 5) |

#### `GET /api/blame`

File change lineage matching session histories

| Query Param | Description |
|---|---|
| `file` | Target file path or pattern |
| `path` | Alias for `file` |

#### `GET /api/matrix`

Adapter extraction coverage and capabilities matrix

#### `GET /api/archaeology`

Archaeology highlights across the whole index

#### `GET /api/live-tail`

Server-Sent Events stream of live filesystem changes under watched adapter session directories

#### `POST /api/scan`

Trigger a scanner background sync (body: paths, force)

#### `POST /api/export/:id`

Export a trace with optional redaction, in JSON or ATIF format (body: redact, format)

### MCP Tools

Register once with `claude mcp add agentworth --scope user -- agentworth mcp` (stdio). Read-only; redaction is on by default for every tool (see `docs/specs/mcp-server.md`).

#### `blame_find`

Find sessions whose recorded file modifications match a substring of file_path -- AI Code Blame, the same query /api/blame makes. Returned paths are redacted.

| Param | Required | Type | Description |
|---|---|---|---|
| `file_path` | yes | string | Substring pattern matched against recorded file-modification paths. |

<details><summary>JSON schema</summary>

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "file_path": {
      "description": "Substring pattern matched against recorded file-modification paths.",
      "type": "string"
    }
  },
  "required": [
    "file_path"
  ],
  "type": "object"
}
```

</details>

#### `carry_forward`

The last N handoffs for one repository, newest first, so a session's first tool call can be "what happened here recently" and the answer is structured rather than a file it has to find and parse. `repo` is the same key session_handoff's receipt reports (e.g. `unfoundbox/agentworth`); a repo's worktrees all answer to one value. n defaults to 3, ceiling 10. Handoffs are listed, never merged -- merging two contradictory facts needs judgment about which is current, and that is not in the index. Redacted by default.

| Param | Required | Type | Description |
|---|---|---|---|
| `include_raw` | no | boolean | Same per-call raw opt-in `session_handoff` has, applied to every handoff returned. |
| `max_lines` | no | integer or null | Line budget for each rendered handoff. Defaults to 60, hard ceiling 120. |
| `n` | no | integer or null | How many handoffs to return, newest first. Defaults to 3, ceiling 10. |
| `repo` | yes | string | Repository/workspace key, as `sessions_find`'s `repo` and the handoff receipt report<br>it (e.g. `unfoundbox/agentworth`). A repo's worktrees all answer to one value. |
| `since` | no | string or null | RFC 3339 timestamp; only sessions started at or after this instant. |

<details><summary>JSON schema</summary>

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "include_raw": {
      "default": false,
      "description": "Same per-call raw opt-in `session_handoff` has, applied to every handoff returned.",
      "type": "boolean"
    },
    "max_lines": {
      "description": "Line budget for each rendered handoff. Defaults to 60, hard ceiling 120.",
      "format": "uint",
      "minimum": 0,
      "type": [
        "integer",
        "null"
      ]
    },
    "n": {
      "description": "How many handoffs to return, newest first. Defaults to 3, ceiling 10.",
      "format": "uint",
      "minimum": 0,
      "type": [
        "integer",
        "null"
      ]
    },
    "repo": {
      "description": "Repository/workspace key, as `sessions_find`'s `repo` and the handoff receipt report\nit (e.g. `unfoundbox/agentworth`). A repo's worktrees all answer to one value.",
      "type": "string"
    },
    "since": {
      "description": "RFC 3339 timestamp; only sessions started at or after this instant.",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "repo"
  ],
  "type": "object"
}
```

</details>

#### `coverage_stats`

Machine-wide aggregate stats: total sessions/events, token usage, sessions by adapter, model/tool usage counts, and verified-outcome count -- the same population /api/stats reports. Pass include_matrix=true to also get the per-adapter detection/capability matrix (/api/matrix's equivalent), answering "what does this machine even have" without opening the dashboard.

| Param | Required | Type | Description |
|---|---|---|---|
| `include_matrix` | no | boolean | Also compute and include the per-adapter detection/capability matrix<br>(`/api/matrix`'s equivalent). Defaults to false. |

<details><summary>JSON schema</summary>

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "include_matrix": {
      "default": false,
      "description": "Also compute and include the per-adapter detection/capability matrix\n(`/api/matrix`'s equivalent). Defaults to false.",
      "type": "boolean"
    }
  },
  "type": "object"
}
```

</details>

#### `forgotten_context`

The decisions this session's compaction rounds threw away, quoted verbatim with a receipt on each. Compaction replaces the conversation with a summary in the model's view while the full transcript stays on disk, so the dropped span and the summary that replaced it both exist and can be diffed. Measured on one real 8-round session (docs/specs/compaction-diff.md): 402 decision-shaped sentences went in and 28 came out -- conclusions survive at 15%, reasons at 1.7%, which is the shape that makes a session re-propose something it already rejected. Filter with round (1-based) and classes (decision, rejected, reason); limit defaults to 20, ceiling 200, and the totals describe the whole session regardless of it. Every statement carries its round, source sequence, and what the session did in the next few events, so a stated decision that was acted on can be told from one that was only claimed. Three answers are kept distinct and none is padded: never compacted, compacted with nothing decision-shaped dropped, and a real list. No model is involved -- three regexes return the sentence verbatim, because a paraphrase would make this a second summariser. Refuses if the raw session file is gone. Redacted by default; include_raw=true opts out, per call.

| Param | Required | Type | Description |
|---|---|---|---|
| `classes` | no | array or null | Any of `decision`, `rejected`, `reason`. Defaults to all three. An unknown name is an<br>error, not an ignored filter. |
| `include_raw` | no | boolean | Return unredacted sentences, paths and evidence labels. Defaults to false -- everything<br>this tool returns is transcript text (docs/specs/mcp-server.md, "What it must not<br>expose"). |
| `limit` | no | integer or null | How many statements to return, newest first. Defaults to 20, hard ceiling 200. The<br>totals in the response describe the whole session regardless of this. |
| `round` | no | integer or null | One 1-based compaction round. Defaults to every round. |
| `session_id` | no | string or null | Session to diff. Defaults to the most recent indexed session for the repository this<br>server process is running in, which is what an agent asking "what did I forget here"<br>means; pass one explicitly to reach any other session. |

<details><summary>JSON schema</summary>

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "classes": {
      "description": "Any of `decision`, `rejected`, `reason`. Defaults to all three. An unknown name is an\nerror, not an ignored filter.",
      "items": {
        "type": "string"
      },
      "type": [
        "array",
        "null"
      ]
    },
    "include_raw": {
      "default": false,
      "description": "Return unredacted sentences, paths and evidence labels. Defaults to false -- everything\nthis tool returns is transcript text (docs/specs/mcp-server.md, \"What it must not\nexpose\").",
      "type": "boolean"
    },
    "limit": {
      "description": "How many statements to return, newest first. Defaults to 20, hard ceiling 200. The\ntotals in the response describe the whole session regardless of this.",
      "format": "uint",
      "minimum": 0,
      "type": [
        "integer",
        "null"
      ]
    },
    "round": {
      "description": "One 1-based compaction round. Defaults to every round.",
      "format": "uint32",
      "minimum": 0,
      "type": [
        "integer",
        "null"
      ]
    },
    "session_id": {
      "description": "Session to diff. Defaults to the most recent indexed session for the repository this\nserver process is running in, which is what an agent asking \"what did I forget here\"\nmeans; pass one explicitly to reach any other session.",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "type": "object"
}
```

</details>

#### `outcome_rate`

Verified-outcome rate by model, adapter, or repo: of the sessions that claimed done, what share left evidence (a passed test/build or stronger), with the sample size next to every row. Groups under min_n (default 20) are suppressed and counted in suppressed_groups rather than shown; a group with sessions but zero detected outcomes comes back as rate: null with reason: "no_outcome_detection" instead of being suppressed -- those are different claims. Includes a receipt (db_path, counted_at, index_last_session_at, the non-stub predicate, and the session IDs behind each row) so the answer is checkable.

| Param | Required | Type | Description |
|---|---|---|---|
| `group_by` | yes | object | - |
| `include_stubs` | no | boolean or null | Include near-empty session stubs in the population. Defaults to false. |
| `min_n` | no | integer or null | Groups with fewer than this many claimed sessions are suppressed (counted in<br>`suppressed_groups`) rather than returned as a row. Defaults to 20. |
| `since` | no | string or null | RFC 3339 timestamp; only sessions started at or after this instant. |
| `until` | no | string or null | RFC 3339 timestamp; only sessions started at or before this instant. |

<details><summary>JSON schema</summary>

```json
{
  "$defs": {
    "OutcomeRateGroupByParam": {
      "description": "Mirrors `agentworth_storage::OutcomeRateGroupBy` with the same snake_case wire values -- a\nlocal copy for the same reason `SessionsOrderBy` is one (see its doc comment above).",
      "enum": [
        "model",
        "adapter",
        "repo"
      ],
      "type": "string"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "group_by": {
      "$ref": "#/$defs/OutcomeRateGroupByParam"
    },
    "include_stubs": {
      "default": null,
      "description": "Include near-empty session stubs in the population. Defaults to false.",
      "type": [
        "boolean",
        "null"
      ]
    },
    "min_n": {
      "description": "Groups with fewer than this many claimed sessions are suppressed (counted in\n`suppressed_groups`) rather than returned as a row. Defaults to 20.",
      "format": "uint",
      "minimum": 0,
      "type": [
        "integer",
        "null"
      ]
    },
    "since": {
      "description": "RFC 3339 timestamp; only sessions started at or after this instant.",
      "type": [
        "string",
        "null"
      ]
    },
    "until": {
      "description": "RFC 3339 timestamp; only sessions started at or before this instant.",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "group_by"
  ],
  "type": "object"
}
```

</details>

#### `pacing_window`

Rolling burn-rate window (default 5 hours): tokens/hour, active adapters and models, estimated cost, and cache hit ratio -- the same window /api/pacing computes. Answers "what am I burning right now".

| Param | Required | Type | Description |
|---|---|---|---|
| `hours` | no | integer or null | Rolling window size in hours; defaults to 5. |

<details><summary>JSON schema</summary>

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "hours": {
      "description": "Rolling window size in hours; defaults to 5.",
      "format": "int64",
      "type": [
        "integer",
        "null"
      ]
    }
  },
  "type": "object"
}
```

</details>

#### `session_asks`

The questions-to-answers index for one session: every question asked (a `?` sentence in a user turn, or a flag-prefixed `⚑`/`🚩` line in an assistant turn asking the user something) matched to the first substantive assistant text that follows it, before the next user turn. Exists so an agent can be told where an answer already landed instead of the user re-scrolling or re-asking. Each result carries the question (trimmed to 120 chars), a status (answered, flagged_back_to_user -- either a flag line or a reply that was itself a question, or no_reply_yet), an answer excerpt when one was found (trimmed to 200 chars), and a pointer (event sequence and timestamp) to jump to: the answer's location when there is one, otherwise the question's own. Filter with since (RFC 3339) and unanswered_only; limit defaults to 50, ceiling 500, and the totals describe the whole session regardless of it. No model is involved -- three deterministic patterns, same `regex_v1` method `forgotten_context` uses. Defaults to the newest session for the repo this server runs in. Redacted by default; include_raw=true opts out, per call.

| Param | Required | Type | Description |
|---|---|---|---|
| `include_raw` | no | boolean | Return unredacted questions and answer excerpts. Defaults to false -- everything this<br>tool returns is transcript text (docs/specs/mcp-server.md, "What it must not expose"). |
| `limit` | no | integer or null | How many questions to return, newest first. Defaults to 50, hard ceiling 500. The<br>totals in the response describe the whole session regardless of this. |
| `session_id` | no | string or null | Session to index. Defaults to the most recent indexed session for the repository this<br>server process is running in, same default `session_handoff` uses. |
| `since` | no | string or null | RFC 3339 timestamp; only questions asked at or after this instant. |
| `unanswered_only` | no | boolean | Only questions that are not `answered` -- still open, or handed back to the user.<br>Defaults to false. |

<details><summary>JSON schema</summary>

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "include_raw": {
      "default": false,
      "description": "Return unredacted questions and answer excerpts. Defaults to false -- everything this\ntool returns is transcript text (docs/specs/mcp-server.md, \"What it must not expose\").",
      "type": "boolean"
    },
    "limit": {
      "description": "How many questions to return, newest first. Defaults to 50, hard ceiling 500. The\ntotals in the response describe the whole session regardless of this.",
      "format": "uint",
      "minimum": 0,
      "type": [
        "integer",
        "null"
      ]
    },
    "session_id": {
      "description": "Session to index. Defaults to the most recent indexed session for the repository this\nserver process is running in, same default `session_handoff` uses.",
      "type": [
        "string",
        "null"
      ]
    },
    "since": {
      "description": "RFC 3339 timestamp; only questions asked at or after this instant.",
      "type": [
        "string",
        "null"
      ]
    },
    "unanswered_only": {
      "default": false,
      "description": "Only questions that are not `answered` -- still open, or handed back to the user.\nDefaults to false.",
      "type": "boolean"
    }
  },
  "type": "object"
}
```

</details>

#### `session_get`

Get full detail for one session by ID: the trace, its 5-component TraceScore, outcome evidence, and recovery signals -- the same shape /api/traces/:id returns. Redacted by default (trace events, outcome summaries, and recovery summaries all pass through the redaction engine); pass include_raw=true for the unredacted trace. `trace.events` is paginated: events_offset (default 0) and events_limit (default 500, must be > 0) page through it, and the response's events_total says how many events the session actually has, so a large session is never returned in full by accident.

| Param | Required | Type | Description |
|---|---|---|---|
| `events_limit` | no | integer or null | Max number of events to return. Defaults to `SESSION_GET_DEFAULT_EVENTS_LIMIT` (500) so<br>a call can never receive a session's full event list by accident; pass an explicit,<br>larger value to see more. Must be greater than 0. |
| `events_offset` | no | integer or null | Zero-based offset into the trace's events. Defaults to 0. |
| `include_raw` | no | boolean | Return the unredacted trace, outcomes, and recoveries. Defaults to false -- redacted<br>output is the default for every tool that can carry event or file content (see<br>docs/specs/mcp-server.md, "What it must not expose"). |
| `session_id` | yes | string | - |

<details><summary>JSON schema</summary>

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "events_limit": {
      "default": null,
      "description": "Max number of events to return. Defaults to `SESSION_GET_DEFAULT_EVENTS_LIMIT` (500) so\na call can never receive a session's full event list by accident; pass an explicit,\nlarger value to see more. Must be greater than 0.",
      "format": "uint",
      "minimum": 0,
      "type": [
        "integer",
        "null"
      ]
    },
    "events_offset": {
      "default": null,
      "description": "Zero-based offset into the trace's events. Defaults to 0.",
      "format": "uint",
      "minimum": 0,
      "type": [
        "integer",
        "null"
      ]
    },
    "include_raw": {
      "default": false,
      "description": "Return the unredacted trace, outcomes, and recoveries. Defaults to false -- redacted\noutput is the default for every tool that can carry event or file content (see\ndocs/specs/mcp-server.md, \"What it must not expose\").",
      "type": "boolean"
    },
    "session_id": {
      "type": "string"
    }
  },
  "required": [
    "session_id"
  ],
  "type": "object"
}
```

</details>

#### `session_handoff`

The handoff for one session, written from rows rather than by a model: what it said it would do and never did, what it said it decided, which files changed, which commands ran and with what exit code, the outcome rung reached, and how often the context was compacted. Returns markdown under a line budget (max_lines, default 60, ceiling 120), the receipt every claim traces back to, and `gaps` -- the machine-readable list of what this session could not answer, which is never padded over. Open decisions, PR/CI state and environment traps are NOT in the index and the output says so. Defaults to the newest session for the repo this server runs in. Redacted by default; include_raw=true opts out, per call.

| Param | Required | Type | Description |
|---|---|---|---|
| `include_loose_ends` | no | boolean or null | Include the "said it would, no evidence it did" section. Defaults to true. |
| `include_raw` | no | boolean | Return unredacted paths, commands and quoted sentences. Defaults to false -- redacted<br>is the default for every tool that can carry event or file content<br>(docs/specs/mcp-server.md, "What it must not expose"). |
| `max_lines` | no | integer or null | Line budget for the rendered markdown. Defaults to 60, hard ceiling 120. |
| `session_id` | no | string or null | Session to hand over. Defaults to the most recent indexed session for the repository<br>this server process is running in, which is what an agent asking "what did I just do<br>here" means; pass one explicitly to reach any other session or repo. |

<details><summary>JSON schema</summary>

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "include_loose_ends": {
      "description": "Include the \"said it would, no evidence it did\" section. Defaults to true.",
      "type": [
        "boolean",
        "null"
      ]
    },
    "include_raw": {
      "default": false,
      "description": "Return unredacted paths, commands and quoted sentences. Defaults to false -- redacted\nis the default for every tool that can carry event or file content\n(docs/specs/mcp-server.md, \"What it must not expose\").",
      "type": "boolean"
    },
    "max_lines": {
      "description": "Line budget for the rendered markdown. Defaults to 60, hard ceiling 120.",
      "format": "uint",
      "minimum": 0,
      "type": [
        "integer",
        "null"
      ]
    },
    "session_id": {
      "description": "Session to hand over. Defaults to the most recent indexed session for the repository\nthis server process is running in, which is what an agent asking \"what did I just do\nhere\" means; pass one explicitly to reach any other session or repo.",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "type": "object"
}
```

</details>

#### `sessions_find`

Find sessions by adapter, model, outcome, search text, date range, token floor, or derived repo/workspace name. `limit` is required with a hard ceiling of 200 -- there is no silent default, so state how many results you want. Returns summaries only (no event content); `source_path` is redacted.

| Param | Required | Type | Description |
|---|---|---|---|
| `adapter` | no | string or null | Exact adapter name match (e.g. `claude_code`, `codex`, `gemini`). |
| `end_date` | no | string or null | RFC 3339 timestamp; only sessions started at or before this instant. |
| `include_stubs` | no | boolean or null | Include near-empty session stubs (defaults to excluding them). |
| `limit` | yes | integer | Maximum rows to return. Required -- there is no silent default -- and capped at<br>`SESSIONS_FIND_LIMIT_CEILING` (200). |
| `min_tokens` | no | integer or null | Only sessions with at least this many total tokens. |
| `model` | no | string or null | Substring match against the session's recorded models. |
| `offset` | no | integer or null | - |
| `order_by` | no | - | Sort order; defaults to `started_at_desc`. |
| `outcome` | no | string or null | Exact match against the stored primary outcome, snake_case (e.g. `commit_observed`). |
| `repo` | no | string or null | Filter to sessions whose derived repository/workspace name matches exactly. Not a<br>stored column -- computed per-row from `source_path` and post-filtered client-side,<br>so combining this with `limit` may require over-fetching (see `truncated` in the<br>response). |
| `search` | no | string or null | Substring match across session ID, source path, models, and adapter. |
| `start_date` | no | string or null | RFC 3339 timestamp; only sessions started at or after this instant. |

<details><summary>JSON schema</summary>

```json
{
  "$defs": {
    "SessionsOrderBy": {
      "description": "Mirrors `agentworth_storage::SessionOrderBy` with the same snake_case wire values. A local\ncopy rather than deriving `schemars::JsonSchema` on the storage crate's own enum, since\n`agentworth-storage` has no reason to take on a `schemars` dependency for one MCP-only need.",
      "enum": [
        "started_at_desc",
        "started_at_asc",
        "tokens_desc",
        "tokens_asc",
        "events_desc",
        "events_asc",
        "duration_desc",
        "score_desc",
        "score_asc"
      ],
      "type": "string"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "adapter": {
      "description": "Exact adapter name match (e.g. `claude_code`, `codex`, `gemini`).",
      "type": [
        "string",
        "null"
      ]
    },
    "end_date": {
      "description": "RFC 3339 timestamp; only sessions started at or before this instant.",
      "type": [
        "string",
        "null"
      ]
    },
    "include_stubs": {
      "default": null,
      "description": "Include near-empty session stubs (defaults to excluding them).",
      "type": [
        "boolean",
        "null"
      ]
    },
    "limit": {
      "description": "Maximum rows to return. Required -- there is no silent default -- and capped at\n`SESSIONS_FIND_LIMIT_CEILING` (200).",
      "format": "uint",
      "minimum": 0,
      "type": "integer"
    },
    "min_tokens": {
      "description": "Only sessions with at least this many total tokens.",
      "format": "uint64",
      "minimum": 0,
      "type": [
        "integer",
        "null"
      ]
    },
    "model": {
      "description": "Substring match against the session's recorded models.",
      "type": [
        "string",
        "null"
      ]
    },
    "offset": {
      "format": "uint",
      "minimum": 0,
      "type": [
        "integer",
        "null"
      ]
    },
    "order_by": {
      "anyOf": [
        {
          "$ref": "#/$defs/SessionsOrderBy"
        },
        {
          "type": "null"
        }
      ],
      "description": "Sort order; defaults to `started_at_desc`."
    },
    "outcome": {
      "description": "Exact match against the stored primary outcome, snake_case (e.g. `commit_observed`).",
      "type": [
        "string",
        "null"
      ]
    },
    "repo": {
      "description": "Filter to sessions whose derived repository/workspace name matches exactly. Not a\nstored column -- computed per-row from `source_path` and post-filtered client-side,\nso combining this with `limit` may require over-fetching (see `truncated` in the\nresponse).",
      "type": [
        "string",
        "null"
      ]
    },
    "search": {
      "description": "Substring match across session ID, source path, models, and adapter.",
      "type": [
        "string",
        "null"
      ]
    },
    "start_date": {
      "description": "RFC 3339 timestamp; only sessions started at or after this instant.",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "limit"
  ],
  "type": "object"
}
```

</details>

#### `suspect_commits`

Which commits on this branch came out of a session that never proved anything. Walks `git log` over the range, joins each commit's changed paths to indexed sessions that touched them within window_hours before it, and reports each session's risk signals: no_test_run (the session never got past artifact_changed), no_outcome_detected (the adapter extracted no outcome at all -- weaker), demoted_claim (verification contradicted a claim, with the event sequence), and loop (the sentinel caught repetition). Returns a list and a copyable prompt -- never a patch, a diff, or a PR: a trajectory says the session was going badly, not what the code does wrong. Two counts are load-bearing and must be reported to the user, not dropped: `unattributed` commits had no indexed session at all (unknown, not clean), and `unanchored_blame_rows` is evidence that could not be placed in any repository. Paths and session source paths are redacted.

| Param | Required | Type | Description |
|---|---|---|---|
| `base` | no | string or null | Ref to diff against. Defaults to the branch's own upstream, then `origin/main`, then<br>`origin/master`, then the most recent `max_commits` commits. |
| `branch` | no | string or null | Branch to walk. Defaults to `HEAD`. |
| `max_commits` | no | integer or null | Ceiling on commits walked. Defaults to 200, hard-capped at 1000. |
| `repo` | yes | string | Absolute path to a git checkout on this machine. Anything inside it works — the<br>repository root is resolved with `git rev-parse --show-toplevel`. |
| `since` | no | string or null | RFC 3339 timestamp. Only consulted when `base` is absent. |
| `window_hours` | no | integer or null | How long before a commit a session's file touch still counts as having authored it.<br>Defaults to 24. |

<details><summary>JSON schema</summary>

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "base": {
      "description": "Ref to diff against. Defaults to the branch's own upstream, then `origin/main`, then\n`origin/master`, then the most recent `max_commits` commits.",
      "type": [
        "string",
        "null"
      ]
    },
    "branch": {
      "description": "Branch to walk. Defaults to `HEAD`.",
      "type": [
        "string",
        "null"
      ]
    },
    "max_commits": {
      "description": "Ceiling on commits walked. Defaults to 200, hard-capped at 1000.",
      "format": "uint",
      "minimum": 0,
      "type": [
        "integer",
        "null"
      ]
    },
    "repo": {
      "description": "Absolute path to a git checkout on this machine. Anything inside it works — the\nrepository root is resolved with `git rev-parse --show-toplevel`.",
      "type": "string"
    },
    "since": {
      "description": "RFC 3339 timestamp. Only consulted when `base` is absent.",
      "type": [
        "string",
        "null"
      ]
    },
    "window_hours": {
      "description": "How long before a commit a session's file touch still counts as having authored it.\nDefaults to 24.",
      "format": "int64",
      "type": [
        "integer",
        "null"
      ]
    }
  },
  "required": [
    "repo"
  ],
  "type": "object"
}
```

</details>

#### `usage_summary`

Daily, weekly, or monthly usage rollups: session counts, token breakdown, estimated cost, and cache hit ratio, grouped by adapter -- the same rollups /api/usage returns for one period at a time.

| Param | Required | Type | Description |
|---|---|---|---|
| `limit` | no | integer or null | Row cap; defaults match the HTTP route's own per-period defaults (30 / 20 / 12). |
| `period` | yes | object | - |

<details><summary>JSON schema</summary>

```json
{
  "$defs": {
    "UsagePeriodParam": {
      "description": "Rollup period for the `usage_summary` tool, mirroring `Storage::get_daily_usage` /\n`get_weekly_usage` / `get_monthly_usage`.",
      "enum": [
        "day",
        "week",
        "month"
      ],
      "type": "string"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "limit": {
      "description": "Row cap; defaults match the HTTP route's own per-period defaults (30 / 20 / 12).",
      "format": "uint",
      "minimum": 0,
      "type": [
        "integer",
        "null"
      ]
    },
    "period": {
      "$ref": "#/$defs/UsagePeriodParam"
    }
  },
  "required": [
    "period"
  ],
  "type": "object"
}
```

</details>



## Blog posts

### The effort dial we can't read
https://agentworth.dev/blog/the-effort-dial-we-cant-read/ — September 2, 2026 — 6 min read

A developer report calls reasoning effort a behavioral control, not a percentage of the model. We checked the load-bearing claims against Anthropic's and OpenAI's own docs, then asked what AgentWorth can actually see about it in your transcripts today.

Every major coding model now takes an effort setting: low, medium, high, and
usually more. It changes how much work the model puts into a response. It
does not change how much of the model you get.

That second sentence is the whole idea, and it is easy to get backwards. Low
effort is not "20% of the network." High is not "80% capable." Anthropic
says so directly: "Effort is a behavioral signal, not a strict token
budget." (Effort)
Think of it as a dial on willingness to spend inference-time compute, not a
dial on intelligence.

  
  
  ConceptModel, effort, and harness are three independent variables. Changing one doesn't move the others.

What we checked

A report someone shared with us — produced with GPT — makes that same
argument at length, with diagrams and a five-level Anthropic ladder and a
comparison of who documents effort better. Per our own rule for anything
that can drift, we did not take its claims at face value. We read it in
full, then verified the three claims the rest of it leans on against the
primary docs.

Anthropic's effort parameter has five levels, and high is the
default. Confirmed directly on the current docs page:

Level
What it does

low
Most efficient; real capability reduction

medium
Moderate token savings

high
Default — same as omitting the parameter

xhigh
Long-horizon agentic work, token budgets in the millions

max
No constraint on token spending

Source: Effort — Claude API docs.
Not every model supports xhigh; some only go up to max.

  
  
  VerifiedAnthropic's five effort levels. Leave the parameter out and you get high.

Effort changes tool-use behavior, not just hidden thinking. The same
docs page states it plainly: lower effort means Claude "combines multiple
operations into fewer tool calls," "makes fewer tool calls," and "proceed[s]
directly to action without preamble." Higher effort means more calls, a
stated plan before acting, and fuller summaries afterward. This is a real
finding worth knowing if you've ever wondered why a low-effort agent run
looks terser end to end, not just in its answer.

OpenAI's current flagship, GPT-5.6, takes the same six-name ladder:
none, low, medium, high, xhigh, max, as separate model variants
(-sol, -terra, -luna) trade off capability for cost. Source:
OpenAI's model guidance docs.
OpenAI also keeps reasoning effort and answer verbosity as two separate
controls — you can ask for deep reasoning and a short answer. Source:
OpenAI's reasoning guide.

  
  
  VerifiedReasoning effort and answer verbosity are separate dials on OpenAI's API — you can turn one up without turning the other up too.

What we left out: the report's claim that Anthropic explains effort's
meaning more clearly while OpenAI exposes more knobs and telemetry.
That's a judgment call about two documentation styles, not a measurement,
and we're not going to launder someone else's opinion as a finding. Its
"12 mediocre iterations vs. 4 better iterations" cost chart is also labeled
illustrative in the report itself — we're repeating that label, not the bar
heights.

  
  
  Illustrative, not measuredThe report's structural point — weak first-pass reasoning can add retries that cost more than the extra reasoning would have — shown as shape, not data. Neither we nor the report have numbers behind these bar lengths.

What AgentWorth can see about this today

Here's the part that matters for us specifically: can we tell, from a
transcript on your machine, what effort level a session actually ran at?

Not for Claude Code. We parsed 190,573 records across 618 local session
files, and Claude Code never writes an effort field to disk — only the
harness that set it would know, and Claude Code doesn't log its own
request config. What Claude Code does write for a thinking-enabled turn
is a thinking content block, and that block is a summary, not the
reasoning itself: "No display setting returns the raw chain of thought,"
and summarization "is processed by a different model" than the one that
did the thinking. Source:
Thinking — Claude API docs.
So even where we can see that a model thought, we can't see how hard.

Codex is different. Its turn_context record carries effort on every
turn, alongside model, approval_policy, and sandbox_policy — per-turn
harness configuration that Claude Code simply does not write. That's a
measured fact from parsing real session files, documented in
docs/research/traces-and-open-models.md.

Harness
Effort on disk?

Claude Code
No — not logged at all

Codex CLI
Yes — turn_context.effort, every turn

  
  
  MeasuredParsed from 190,573 records across 618 local session files: Codex writes effort on every turn; Claude Code's records never carry it.

So if you want to correlate effort level with outcome rate, that analysis
is available today for Codex sessions and not for Claude Code ones. We're
not going to claim otherwise, and we're not going to infer an effort level
from output length or tone — that's a guess wearing a measurement's
clothes.

What this means day to day

We can't tell you the one right effort level, because the data we can
actually see doesn't support that sentence. What the verified claims above
do support: effort is worth setting on purpose rather than leaving on
default, because it changes real behavior — tool-call count, preamble,
summary length — not just an invisible thinking budget. If you're on
Claude Code, you're flying blind on which level you actually used unless
you set it yourself and remember; if you're on Codex, that number is
sitting in your session files right now. Everything past that — which
level is "right" for which task — is a claim about your own repo and your
own evals, not something a report, or we, can hand you.

This draws on a report produced with GPT; we verified the claims we repeat
here against the primary sources linked above.

npx -y agentworth scan


## Changelog

### 0.1.14 — 2026-09-02

Added:
The handoff, written by the machine. agentworth handoff, agentworth loose-ends, and the MCP tools session_handoff and carry_forward: what a session promised and did not do, what it decided, files touched, commands and how they ended, the outcome rung, compactions. Every line carries a receipt; nothing is summarised (#77).

forgotten_context. The decisions compaction dropped, handed back with receipts, plus agentworth forgotten. Measured on one 8-round session: 405 decision sentences in, 28 out (#83).

suspect_commits and agentworth suspect --hook: commits whose authoring session had no exit-0 test, a demoted done-claim, or a loop; anchored to the repo so relative blame paths cannot suffix-match every repo on disk (#84).

outcome_rate: verified-outcome rate by model, adapter or repo, with an n floor (#75).

inspect accepts a session-id prefix; doctor and matrix render in the design system (#76).

CI runs tests on ubuntu and macOS, clippy gates, path-aware jobs; the dead GitHub Pages deploy is gone (#79).

Fixed:
"Tests passed" now means exit 0. The Claude Code adapter never parsed tool results on real transcripts (they nest under message.content), so no exit code ever reached the outcome engine, which granted rung 3 from the command string alone. Exit codes are parsed from is_error and "Exit code N"; a test, build, CI or deploy command with no exit code cannot reach a verified rung. Aider's markdown path no longer hardcodes success (#81, #85).

Every real session gets scored; a parser version per adapter triggers a one-time reparse when parsing changes; backfill runs once per version and never loops on sessions with no prompt (#85, #89).

stats and usage count the same sessions; usage views apply the non-stub predicate (#78).

Live-tail adapter attribution works on macOS (FSEvents reports canonical paths) (#87).

The archaeology pane fetches its data (#80). Trace responses gzip and paginate; the inspector streams large sessions (#72, #73). prompt_preview backfills; the matrix derives from the adapter registry (#74).

### 0.1.13 — 2026-09-02

Added:
MCP server. agentworth mcp (stdio) exposes the index to any coding agent: sessions_find, session_get, blame_find, usage_summary, pacing_window, coverage_stats. Redaction on by default. Register with claude mcp add agentworth -- agentworth mcp (#56).

Per-session compaction tracking in the schema, storage and API, and a compaction pane in the dashboard: rounds, context before and after, what survived, marked on the trajectory (#57, #62).

CLI output redesigned. One design system for stats, usage, traces, blame, scan and the receipt: the evidence ladder with its evidence line, right-aligned numbers, 100-column max, no emoji, --plain, --no-color, NO_COLOR and non-TTY honoured. --json payloads unchanged (#67).

Real vendor logos in the coverage matrix, and one brand mark across the site, dashboard, favicons and social card (#59, #63, #65, #66).

curl -fsSL https://agentworth.dev/install.sh | sh is now a real installer (#55).

Fixed:
The index stored hundreds of config, telemetry and other non-session files as sessions with zero events. Discovery rules for seven adapters now reject them, the scanner skips zero-event parses, and a full scan prunes existing stubs (#68).

agentworth serve --dist <path> silently served the embedded dashboard when the path was wrong; it now fails at startup naming the path (#60).

GET /api/traces dropped primary_outcome and composite_score when null, so every outcome dot rendered grey; the keys are always present now (#60).

Release tarballs ship agwt as well as agentworth; the npm launcher resolves whichever name it was invoked as (#61).

CI now runs cargo test --workspace and the npm launcher tests; a test that had been red on main is fixed; one mutex unwrap that could wedge serve recovers (#54, #61).

Dashboard formatters no longer throw on a field the server stopped sending (#53).

### 0.1.12 — 2026-09-02

Fixed:
npx agentworth works on macOS again. 0.1.11 passed --force-local to tar on every platform. That flag exists only in GNU tar; macOS ships BSD tar, which rejected it, so every fresh install on a Mac failed with "native binary not found". The flag was a Windows-only workaround and Windows is no longer supported, so it is gone (#51).

### 0.1.11 — 2026-09-02

Fixed:
Windows dropped as a supported platform. 0.1.10 shipped a Windows build for the first time, and it broke npx agentworth on real Windows machines within minutes: GNU tar parses a C:\Users\...\agentworth.tar.gz archive path as a remote host:path tar spec (the drive letter before the colon reads as a hostname), so extraction fails instead of just opening the local file. Rather than chase this again, Windows is no longer built or resolved — agentworth on Windows now fails with a clear "unsupported platform" message instead of a 404 or a tar crash. Building from source still works on any platform.

The npm launcher no longer lets a stale binary in a cargo target directory or ~/.cargo/bin silently answer for every later version forever — the same version check already applied to PATH now applies to those sources too.

### 0.1.10 — 2026-09-02

Fixed:
The outcome ladder now actually renders. primary_outcome was written to the index in hand-rolled PascalCase ("CommitObserved") while the API contract and the whole frontend expect snake_case — every session with a real outcome silently read as unresolved, and verified_outcomes_count was 0 for everyone. A data migration corrects every row already on disk the first time this version opens your index; nothing to run by hand.

No busy_timeout was set on the SQLite connection — agentworth serve and agentworth scan running at the same time could return SQLITE_BUSY immediately on a write collision instead of waiting.

prompt_preview was always empty. It's now populated from each session's first real user message, truncated past 200 characters.

/api/stats and /api/traces disagreed on how many sessions existed (one counted near-empty stub sessions, the other didn't) — several report/dashboard numbers were quietly dividing against the wrong population. Fixed at the source rather than patched per call site.

Several commands (audit, threat-digest, stats, archaeology, blind_spots, and more) silently capped how many sessions they looked at while presenting the result as "all sessions" — on an index above the cap, that read as a clean bill of health when it wasn't. All now scan the real total.

agwt search's background indexing only ever ran once per process; any session scanned after the first successful run was never indexed for search again. Rebuilt as a real incremental indexer.

Every dollar figure in agentworth's reports was priced as Claude 3.5 Sonnet regardless of which model actually ran the session.

Added:
agentworth version / agentworth update — checks whether a newer release exists and tells you how to get it (never replaces the binary itself).

agentworth threat-digest and agwt blunder-blame — rank indexed sessions by real secret exposure, and connect a blunder back to the files it touched (or a file back to the sessions that touched it).

A real-time GET /api/live-tail (SSE) endpoint — filesystem-watch-based, no polling.

Outcome claims are now cross-checked against real trace state before being trusted — a bare tool-call request with no observed result no longer counts as verified.

ModelSwitch events, tracked across all 20 supported harnesses.

agentworth config — persisted defaults for json/limit/period, explicit flags always win.

A context-rot marker and a human-vs-agent recovery-loop classifier, both intentionally conservative (weak-to-moderate confidence, documented as such) rather than dressed up as more certain than the underlying signal supports.

Redaction now covers a session's own repository/project name (previously only a home directory's username was stripped, so export --redact still leaked project identity) and reaches outcome/recovery evidence, not just raw event content — closing a gap flagged ahead of the read-only MCP server spec in docs/specs/mcp-server.md.

### 0.1.9 — 2026-09-01

Added:
Trajectory view in the dashboard inspector — a timeline strip (bucketed ticks across three rows), a virtualized event stream, and a detail panel. Before this, the inspector scored a session (80/100) without ever showing what the agent actually did; trace.events was fully populated and rendered nowhere.

Categorical colour palette for the dashboard's data views — eight identity hues, full light and dark sets, with a colour/monochrome toggle. A stacked token-economics bar in one hue plus greys wasn't readable; cache read vs. cache creation is the whole point of that chart.

SpacePilot icon sprite replaces most hand-drawn icons in the dashboard topbar, rail, and outcome ladder (27 icons ported).

Landing state now shows an overview ("how am I doing") instead of "Select a session to inspect it."

Fixed:
Escape now actually collapses the expanded trajectory view. Its tooltip had promised Collapse (esc) since the explorer shell shipped, but no handler existed — and once one was wired up, a stale-closure bug in the key handler's dependency array kept it doing nothing anyway.

Danger red no longer marks sessions that simply lack evidence yet. OutcomeKind has no failure state — every value is a degree of evidence or its absence — so red is now reserved for an actual cost signal (a cache-invalidation spike), and unverified work reads as neutral or hollow instead of a wall of alarms.

### 0.1.8 — 2026-09-01

Fixed:
npx agentworth@<version> now runs the version you asked for. Every release before this deferred to any agentworth already on PATH, so a pinned request silently ran whatever was installed locally instead — four releases stale, in the case that surfaced it. This is the fix 0.1.7 was tagged for; see below — it didn't actually ship until now.

The release smoke test no longer races the npm registry. A good release could previously report itself broken because the check ran before the published version had propagated.

### 0.1.7 — 2026-09-01



### 0.1.6 — 2026-09-01

Added:
MotionVector design system applied across the marketing landing page and the new dashboard.

Keyboard-first, three-pane explorer shell for the dashboard, splitting apps/web into a marketing site and a standalone apps/dashboard.

Inspector detail restored after the shell's first pass thinned it out: a five-component score breakdown with the audit explanations underneath, token economics shown as a proportion (cache read vs. cache creation), a provenance block (source path, fingerprint, on-disk-verified chip), and recovery signals. The session list regained its seven sort modes, cross-field search, and a density toggle.

ci.yml — the repo's first Rust CI. Before this, only page-deploy and the tag-triggered release existed, so nothing compiled the workspace on a pull request.

Fixed:
The installed binary now actually contains the dashboard. Every release back to 0.1.0 built no web app in release.yml and looked for apps/dashboard/dist by a relative path that only resolved inside a repo checkout — so every npm and cargo install served a hardcoded stub page, silently, for months.

The session list was showing 50 of 2,903 sessions, because /api/traces defaults to limit=50 and nothing asked for more — every filter, sort, and search ran against just the newest 50 and looked normal doing it.

Every deep link was a blank page: Vite's base: './' resolves asset URLs against the current route, so /s/<id> requested /s/assets/..., got the SPA fallback's index.html back, and died on a MIME check before React ever mounted.

Five TypeScript field names never matched the server's actual response shape (cache_read_tokens/cache_creation_tokens vs. cache_*_input_tokens; adapter_name, mtime_epoch_secs, content_fingerprint vs. adapter, modified_timestamp, fingerprint) — cache economics silently read as zero and provenance as em-dashes even though the real data was there.

The adapter column was 54px, truncating claude_code — the single most common value in any real index — down to claude_c.

agwt blame now persists file modifications so lineage lookups actually match; previously edits went unrecorded and blame silently came up empty.

### 0.1.5 — 2026-08-31

Fixed:
npx agentworth no longer spawns itself into an EAGAIN crash loop on macOS. The launcher's PATH-resolution step found npm's node_modules/.bin/agentworth symlink — which points back at the launcher itself — before the GitHub-release binary downloader ever got a chance to run. The old anti-recursion guard compared unresolved paths and didn't follow the symlink, so it missed it. Fixed with three independent guards: realpath-based self-detection, rejecting .js/.cjs/.mjs shim files outright, and an AGENTWORTH_LAUNCHER_ACTIVE flag that skips PATH lookup once already inside a launcher.

### 0.1.4 — 2026-08-31

Fixed:
npm install agentworth actually installs something again. 0.1.3's npm publish failed with a 404 that looked like a missing package but was really an npm auth failure, so every npx agentworth invocation — including every landing-page CTA — had been silently stuck on 0.1.1 since. Publishing now goes over trusted publishing (OIDC) instead of a token; classic and even bypass-2FA granular tokens both got a hard 403 when tested against a real publish, which matches npm's own policy of retiring token-based publishing for this case.

A version gate now blocks a release where the git tag, Cargo.toml, and package.json versions disagree. 0.1.3 was tagged from a tree where Cargo.toml still said 0.1.2, so the binary it built reported the wrong version.

npm whoami now runs before publish, so a broken publish fails in seconds naming the real cause instead of ending in a confusing 404.

Added:
A clean-room smoke test: npx -y agentworth@<version> --version and usage --pacing, run on a fresh Ubuntu and macOS runner with no checkout and no cargo cache — the exact conditions 0.1.3 shipped broken under.

Removed:
brew install agentworth and the curl | sh installer, from the missing-binary message. Neither exists: there's no Homebrew tap, and that install URL just returns the site's HTML with a 200 — so the advertised command would have piped a webpage into a shell. Points at the GitHub releases page instead.

### 0.1.3 — 2026-08-31

Added:
Local semantic search (agwt search), backed by a FastEmbed ONNX embedding engine that runs fully offline.

Forensic safety auditor (agwt audit --safety).

Five-rung outcome ladder indexing in SQLite, plus a cache-cliff visualizer and agwt matrix in the (not-yet-shipped) dashboard UI.

agwt blunder — dispatches a redacted incident report to stfuopus.lol, stripping secrets before anything leaves the machine.

Adapter discovery now runs across multiple cores in parallel, with adapter stats sorted; native SQLite ingestion for OpenCode sessions.

Fixed:
primary_outcome and composite_score now migrate before index creation in initialize_schema, instead of after.

### 0.1.2 — 2026-08-31

Added:
Expanded Native Adapter Fleet from 11 to 20 Agents:
🐋 DeepSeek Code (deepseek):
Discovers ~/.deepseek/, ~/.deepseek-coder/, and .deepseek/ traces.

Full reasoning token stream accounting for DeepSeek R1 and V3 (reasoning_content, thought).

Tracks prompt cache hits (prompt_cache_hit_tokens) and cache creation (prompt_cache_miss_tokens).

Normalizes file editing (str_replace_editor, write, edit) and shell execution (bash).

🌙 Kimi Code (kimi):
Discovers Moonshot Kimi Code sessions in ~/.kimi-code/ and ~/.kimi/sessions/wire.jsonl.

Parses streaming wire JSONL protocols, subagent delegations (subagent_delegation), and tool calls.

⚡ MiniMax (minimax):
Discovers ~/.minimax/ and ~/.minimax-agent/ coding plan trajectories.

Normalizes multi-step planning milestones, tool executions, and token expenditures.

🐉 Qwen Code / Qwen-Agent (qwen):
Discovers Alibaba Qwen Code and Qwen-Agent trajectories in ~/.qwen/ and ~/.qwen-agent/.

Extracts reasoning CoT, code_interpreter executions, and tool calls.

🧠 Zhipu / CodeGeeX (zhipu):
Discovers ~/.codegeex/ and ~/.zhipu/ IDE extension and GLM-4 session histories.

🛠️ Aider (aider):
Discovers .aider.chat.history.md and ~/.aider/ git-driven trajectory markdown/JSON logs.

Maps git diff edits and commit messages directly into verified outcome evidence (OutcomeKind::CommitObserved).

👁️ Cline & Roo-Code (cline):
Discovers VSCode global storage task logs (saoudrizwan.claude-dev/tasks/ and rooveterinaryinc.roo-cline/tasks/).

Parses task UI messages, API conversation histories, token cache metrics, and tool execution trees.

🌊 Windsurf / Cascade (windsurf):
Discovers ~/.codeium/windsurf/ and Cascade execution caches.

Normalizes multi-turn code edits, terminal outputs, and test validations.

🦾 Manus (manus):
Discovers ~/.manus/ autonomous agent browser actions and coding trajectories.

### 0.1.1 — 2026-08-30

Added:
agwt usage Command & Rollups:
Deep usage analytics by timeframe with --period day|week|month and --limit.

Aggregates sessions, input tokens, output tokens, prompt cache reads, and estimated USD spend.

Real-time rolling pacing telemetry with --pacing (default 5-hour window via --hours 5):
Token burn velocity (tokens/hour).

Prompt cache hit ratio percentage.

Active agent adapters and models within the pacing window.

Estimated dollar expenditure tracking.

Machine-readable JSON output via --json.

agwt blame <file_path> (AI Code Lineage):
Trace code alterations and file edits back to the specific AI agent session, model, sequence timestamp, and user prompt that created or modified them.

Full support across all 11 supported agent adapter ecosystems.

SQL Analytics Views:
Added native SQLite aggregation views: v_daily_usage, v_weekly_usage, and v_monthly_usage with pre-computed token math and cache metrics.

agwt CLI Alias & Binary Distribution:
Added native agwt command-line alias alongside agentworth.

Fixed:
Date Range Epoch Anomaly:
Fixed an issue where corrupt session timestamps or epoch zeroes (1970-01-01) distorted aggregate date bounds by enforcing MIN(CASE WHEN started_at > '2020-01-01' THEN started_at END) in SQLite aggregate queries.

SQLite Concurrency & WAL Performance:
Configured optimized SQLite WAL mode, busy_timeout = 5000ms, synchronous = NORMAL, and cache_size = -64000 (64MB) to prevent database locking during rapid parallel parsing.

Improved:
Incremental Rescan Performance:
Optimized SHA-256 fingerprint checks to instantly skip unchanged multi-gigabyte session JSONL transcripts.

Unified Multi-Platform Installation:
Standalone script: curl -fsSL https://agentworth.dev/install.sh | sh

Homebrew: brew install unfoundbox/tap/agentworth

Cargo: cargo install agentworth-cli

NPX: npx agentworth or npx agwt

### 0.1.0 — 2026-08-25

Added:
Core Agent History Normalization Pipeline:
100% offline, local-first discovery and streaming JSONL ingestion engine.

Unified AgentWorthTrace and NormalizedEvent canonical schema.

11 Native Streaming Agent Adapters:
Claude Code (claude_code)

Cursor Composer (cursor)

Google Antigravity (antigravity)

OpenAI Codex (codex)

Block Goose (goose)

Pi (pi)

Herdr (herdr)

Nous Hermes (hermes)

OpenClaw (openclaw)

xAI Grok (grok)

OpenCode (opencode)

Outcome Evidence Ladder & Scoring Engine:
Deterministic outcome verification (DoneClaimed < ArtifactChanged < TestOrBuildPassed < CommitObserved < CiOrDeploymentVerified).

Explainable 5-factor TraceScore rating.

CLI Commands:
agentworth scan — Discovers and indexes local session logs.

agentworth stats — Machine-wide token expenditures and top model usage.

agentworth traces — Tabular session directory with filters.

agentworth inspect — Step-by-step ASCII trajectory timeline.

agentworth doctor — System health and adapter discovery diagnostics.

agentworth export — ATIF v1.0 and JSON export with 13-rule offline privacy scrubber.

agentworth serve — Local embedded Axum API server and monochrome receipt explorer UI.