cli-consumption 0.0.18__tar.gz → 0.1.0__tar.gz

cli_consumption-0.1.0/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.5
+Name: cli-consumption
+Version: 0.1.0
+Summary: Analyze and consolidate AI coding CLI consumption across machines.
+Project-URL: Homepage, https://github.com/Guillaume-Lombardo/cli-consumption
+Project-URL: Documentation, https://github.com/Guillaume-Lombardo/cli-consumption#readme
+Project-URL: Issues, https://github.com/Guillaume-Lombardo/cli-consumption/issues
+Project-URL: Repository, https://github.com/Guillaume-Lombardo/cli-consumption.git
+Author-email: Guillaume Lombardo <lombardo.guillaume@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: ai,cli,codex,observability,tokens,usage
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.14
+Requires-Dist: fastapi>=0.115
+Requires-Dist: httpx>=0.27
+Requires-Dist: psycopg[binary]>=3.2
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: typer>=0.15
+Requires-Dist: uvicorn>=0.34
+Description-Content-Type: text/markdown
+
+# CLI Consumption
+
+CLI Consumption measures how AI coding CLIs use models, tokens, tools,
+conversations, and turns. It runs locally, can consolidate copied data from several
+machines, and can send metadata-only snapshots to a central collector.
+
+It never stores prompts, responses, tool arguments, credentials, or raw provider
+events. Local token counters are usage metadata, not billing records. Read the
+[privacy boundary](docs/privacy.md) before sharing a database or report.
+
+## Quick start
+
+CLI Consumption requires Python 3.14 or newer and uses
+[`uv`](https://docs.astral.sh/uv/).
+
+From a checkout, collect every supported CLI detected on the machine and generate a
+self-contained dashboard:
+
+```bash
+uv sync
+uv run cli-consumption collect --provider all
+uv run cli-consumption export --output reports
+```
+
+Open `reports/dashboard.html` locally. It makes no network requests. Detailed
+normalized CSV tables are generated only when `--csv` is passed.
+
+To collect a single CLI, use its provider name. For example, with Codex:
+
+```bash
+uv run cli-consumption collect --provider codex --database usage.sqlite
+```
+
+From PyPI, no permanent installation is required:
+
+```bash
+uv tool run cli-consumption collect --provider all
+uv tool run cli-consumption export --output reports
+```
+
+To run the latest unreleased GitHub source:
+
+```bash
+uv tool run --from git+https://github.com/Guillaume-Lombardo/cli-consumption \
+  cli-consumption providers
+```
+
+## Supported CLIs
+
+`--provider all` detects the supported data stores found in their default locations.
+Use the provider name below with `--provider` to select one CLI explicitly.
+
+| CLI | Provider name | Default local source | Particularities and limits |
+| --- | --- | --- | --- |
+| Aider | `aider` | `~/.aider/analytics.jsonl` | Requires opt-in analytics logging; no projects, tools, cache/reasoning split, or provider-reported durations. |
+| Amazon Q Developer CLI | `amazon-q` | `~/.local/share/amazon-q/data.sqlite3` | Persistent conversations only; request timing is available, but token counters are not. |
+| Amp | `amp` | `~/.local/share/amp/threads/` | Per-inference tokens and context windows; no subthreads, compactions, reasoning split, or latency. |
+| Claude Code | `claude` | `~/.claude/projects/` | Main sessions, tokens, tools, and compactions; no subagents, context windows, or provider-reported durations. `claude-code` is accepted as an alias. |
+| Cline CLI | `cline` | `~/.cline/data/sessions/sessions.db` | Uses the session index and message artifacts; no costs or arbitrary task metadata. |
+| Codex | `codex` | `~/.codex/sessions/` | Richest support: timing, context pressure, settings, compactions, work items, and subagent relationships. |
+| Continue CLI | `continue` | `~/.continue/sessions/` | Token usage when present; session files lack reliable per-message timing and duration. |
+| Crush | `crush` | `~/.local/share/crush/` | Reads registered per-project SQLite stores; token counters are a latest-context snapshot, not additive usage. |
+| Cursor CLI | `cursor` | `~/.cursor/` | Composer 2 transcripts and chat metadata; no per-message time or tokens, and model attribution is incomplete. |
+| Gemini CLI | `gemini` | `~/.gemini/tmp/` | Replays active history and rewinds; hashed projects are not reversed and nested agents are excluded. |
+| GitHub Copilot CLI | `copilot` | `~/.copilot/session-state/` | Tokens are latest shutdown aggregates and cannot be assigned to individual turns. |
+| Goose | `goose` | `~/.local/share/goose/sessions/sessions.db` | Supports SQLite schema v16; no legacy JSONL, subagents, reasoning tokens, or latency. |
+| Grok Build | `grok` | `~/.grok/sessions/` | Per-prompt aggregates, reasoning effort, TTFT, and auto-compactions; no costs or subagent relationships. |
+| Kilo Code | `kilo` | `~/.local/share/kilo/kilo.db` | CLI SQLite store only; excludes legacy IDE tasks, cloud sessions, subagents, context windows, and costs. |
+| Kimi Code CLI | `kimi` | `~/.kimi/sessions/` | Wire v1 events, context windows, and compactions; selected model is not persisted and is reported as `unknown`. |
+| OpenCode | `opencode` | `~/.local/share/opencode/opencode.db` | SQLite v2 only; no legacy storage, child sessions, context windows, or costs. |
+| OpenHands CLI | `openhands` | `~/.openhands/conversations/` | SDK persistence with context windows, reasoning effort, and condensations; excludes cloud-only conversations and delegates. |
+| Pi | `pi` | `~/.pi/agent/sessions/` | Counts all persisted branches; no branch relationships, custom-directory auto-detection, context windows, or provider-reported durations. |
+| Plandex | `plandex` | `/plandex-server` | Requires an offline copy of a self-hosted `PLANDEX_BASE_DIR`; hosted accounts are not accessed, and models/tools are unavailable. |
+| Qwen Code | `qwen` | `~/.qwen/projects/` | Follows the active branch and records context windows and compactions; excludes archived and sidechain sessions. |
+
+Provider formats are internal and can change without notice. The detailed extraction
+rules and qualification versions are documented in
+[Provider support](docs/provider-support.md).
+
+## Collect copied data
+
+`--source [LABEL=]PATH` points to a provider home directory and can be repeated. With
+`--provider all`, each path is inspected and unmatched sources are rejected. With one
+provider selected, each path must contain that provider's expected store.
+
+For example, consolidate trusted copies of Codex data from several machines:
+
+```bash
+uv run cli-consumption collect --provider codex \
+  --source desktop=/data/codex/desktop \
+  --source laptop=/data/codex/laptop \
+  --source server=/data/codex/server \
+  --database usage.sqlite
+```
+
+Copy only the required provider data. For Codex, copy the `sessions/` directory but
+never `auth.json` or other credentials. Globally identical conversation IDs are
+deduplicated, and the most complete copy wins.
+
+Map original working-directory prefixes to stable project labels with repeated
+`--project NAME=PATH_PREFIX` options. The longest matching prefix wins:
+
+```bash
+uv run cli-consumption collect --provider codex \
+  --source desktop=/data/codex/desktop \
+  --project cli-consumption=/home/me/dev/cli-consumption
+```
+
+Plandex auto-detection checks `/plandex-server`. For any other trusted offline copy of
+a self-hosted server data directory, pass the path explicitly:
+
+```bash
+uv run cli-consumption collect --provider plandex \
+  --source server=/srv/plandex-server --database usage.sqlite
+```
+
+## Explore and share reports
+
+The dashboard can filter by time, provider, machine, project, and model. It reports
+activity, token composition, cache efficiency, latency and duration distributions,
+technical throughput, context pressure, work-item reliability, configuration cohorts,
+compactions, subagent delegation, and ingestion quality. Availability varies by
+provider, as summarized in the table above.
+
+Generate a more shareable dashboard by pseudonymizing labels, grouping tool names,
+rounding timestamps to days, and hiding small cohort rows:
+
+```bash
+uv run cli-consumption export --output shared-report --share-safe
+```
+
+Share-safe reports still disclose aggregate work patterns and remain private
+operational data. A technically completed turn is not a measure of task quality or
+productivity.
+
+## SQLite and PostgreSQL
+
+A file path selects SQLite. A SQLAlchemy URL selects PostgreSQL:
+
+```bash
+uv run cli-consumption collect --provider all --database usage.sqlite
+uv run cli-consumption collect --provider all \
+  --database postgresql+psycopg://usage@localhost/cli_consumption
+```
+
+Pass credentials through environment variables or a secret manager rather than shell
+history. `CLI_CONSUMPTION_DATABASE` can provide the database setting.
+
+## Central collector API
+
+Copied files are simplest for personal or air-gapped use. For recurring collection
+across machines, start the metadata-only API:
+
+```bash
+export CLI_CONSUMPTION_API_TOKEN="$(your-secret-provider)"
+uv run cli-consumption serve \
+  --database postgresql+psycopg://usage@localhost/cli_consumption \
+  --host 0.0.0.0
+```
+
+Then send all locally detected snapshots from another machine:
+
+```bash
+export CLI_CONSUMPTION_API_TOKEN="$(your-secret-provider)"
+uv run cli-consumption sync --provider all \
+  --endpoint https://usage.example.test
+```
+
+The application refuses to bind beyond localhost without a token. Production
+deployments also need TLS and standard operational controls. See
+[Architecture](docs/architecture.md) for the trade-offs.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `collect` | Collect local or copied provider data into SQL. |
+| `sync` | Collect and send metadata-only snapshots to a central API. |
+| `serve` | Run the central collection API. |
+| `export` | Write the HTML dashboard and optional CSV tables. |
+| `providers` | List provider names and support status. |
+
+Run `uv run cli-consumption COMMAND --help` for all options.
+
+## Development
+
+```bash
+uv sync --all-groups
+uv run pre-commit install
+uv run pre-commit run --all-files
+uv run ruff format --check .
+uv run ruff check .
+uv run ty check
+uv run pytest --cov --cov-report=term-missing
+uv build
+```
+
+Development uses short-lived branches and squash-merged pull requests into protected
+`main`. Read [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md) before
+changing the project.
+
+## License
+
+Licensed under the [Apache License 2.0](LICENSE).

cli_consumption-0.1.0/README.md

@@ -0,0 +1,204 @@
+# CLI Consumption
+
+CLI Consumption measures how AI coding CLIs use models, tokens, tools,
+conversations, and turns. It runs locally, can consolidate copied data from several
+machines, and can send metadata-only snapshots to a central collector.
+
+It never stores prompts, responses, tool arguments, credentials, or raw provider
+events. Local token counters are usage metadata, not billing records. Read the
+[privacy boundary](docs/privacy.md) before sharing a database or report.
+
+## Quick start
+
+CLI Consumption requires Python 3.14 or newer and uses
+[`uv`](https://docs.astral.sh/uv/).
+
+From a checkout, collect every supported CLI detected on the machine and generate a
+self-contained dashboard:
+
+```bash
+uv sync
+uv run cli-consumption collect --provider all
+uv run cli-consumption export --output reports
+```
+
+Open `reports/dashboard.html` locally. It makes no network requests. Detailed
+normalized CSV tables are generated only when `--csv` is passed.
+
+To collect a single CLI, use its provider name. For example, with Codex:
+
+```bash
+uv run cli-consumption collect --provider codex --database usage.sqlite
+```
+
+From PyPI, no permanent installation is required:
+
+```bash
+uv tool run cli-consumption collect --provider all
+uv tool run cli-consumption export --output reports
+```
+
+To run the latest unreleased GitHub source:
+
+```bash
+uv tool run --from git+https://github.com/Guillaume-Lombardo/cli-consumption \
+  cli-consumption providers
+```
+
+## Supported CLIs
+
+`--provider all` detects the supported data stores found in their default locations.
+Use the provider name below with `--provider` to select one CLI explicitly.
+
+| CLI | Provider name | Default local source | Particularities and limits |
+| --- | --- | --- | --- |
+| Aider | `aider` | `~/.aider/analytics.jsonl` | Requires opt-in analytics logging; no projects, tools, cache/reasoning split, or provider-reported durations. |
+| Amazon Q Developer CLI | `amazon-q` | `~/.local/share/amazon-q/data.sqlite3` | Persistent conversations only; request timing is available, but token counters are not. |
+| Amp | `amp` | `~/.local/share/amp/threads/` | Per-inference tokens and context windows; no subthreads, compactions, reasoning split, or latency. |
+| Claude Code | `claude` | `~/.claude/projects/` | Main sessions, tokens, tools, and compactions; no subagents, context windows, or provider-reported durations. `claude-code` is accepted as an alias. |
+| Cline CLI | `cline` | `~/.cline/data/sessions/sessions.db` | Uses the session index and message artifacts; no costs or arbitrary task metadata. |
+| Codex | `codex` | `~/.codex/sessions/` | Richest support: timing, context pressure, settings, compactions, work items, and subagent relationships. |
+| Continue CLI | `continue` | `~/.continue/sessions/` | Token usage when present; session files lack reliable per-message timing and duration. |
+| Crush | `crush` | `~/.local/share/crush/` | Reads registered per-project SQLite stores; token counters are a latest-context snapshot, not additive usage. |
+| Cursor CLI | `cursor` | `~/.cursor/` | Composer 2 transcripts and chat metadata; no per-message time or tokens, and model attribution is incomplete. |
+| Gemini CLI | `gemini` | `~/.gemini/tmp/` | Replays active history and rewinds; hashed projects are not reversed and nested agents are excluded. |
+| GitHub Copilot CLI | `copilot` | `~/.copilot/session-state/` | Tokens are latest shutdown aggregates and cannot be assigned to individual turns. |
+| Goose | `goose` | `~/.local/share/goose/sessions/sessions.db` | Supports SQLite schema v16; no legacy JSONL, subagents, reasoning tokens, or latency. |
+| Grok Build | `grok` | `~/.grok/sessions/` | Per-prompt aggregates, reasoning effort, TTFT, and auto-compactions; no costs or subagent relationships. |
+| Kilo Code | `kilo` | `~/.local/share/kilo/kilo.db` | CLI SQLite store only; excludes legacy IDE tasks, cloud sessions, subagents, context windows, and costs. |
+| Kimi Code CLI | `kimi` | `~/.kimi/sessions/` | Wire v1 events, context windows, and compactions; selected model is not persisted and is reported as `unknown`. |
+| OpenCode | `opencode` | `~/.local/share/opencode/opencode.db` | SQLite v2 only; no legacy storage, child sessions, context windows, or costs. |
+| OpenHands CLI | `openhands` | `~/.openhands/conversations/` | SDK persistence with context windows, reasoning effort, and condensations; excludes cloud-only conversations and delegates. |
+| Pi | `pi` | `~/.pi/agent/sessions/` | Counts all persisted branches; no branch relationships, custom-directory auto-detection, context windows, or provider-reported durations. |
+| Plandex | `plandex` | `/plandex-server` | Requires an offline copy of a self-hosted `PLANDEX_BASE_DIR`; hosted accounts are not accessed, and models/tools are unavailable. |
+| Qwen Code | `qwen` | `~/.qwen/projects/` | Follows the active branch and records context windows and compactions; excludes archived and sidechain sessions. |
+
+Provider formats are internal and can change without notice. The detailed extraction
+rules and qualification versions are documented in
+[Provider support](docs/provider-support.md).
+
+## Collect copied data
+
+`--source [LABEL=]PATH` points to a provider home directory and can be repeated. With
+`--provider all`, each path is inspected and unmatched sources are rejected. With one
+provider selected, each path must contain that provider's expected store.
+
+For example, consolidate trusted copies of Codex data from several machines:
+
+```bash
+uv run cli-consumption collect --provider codex \
+  --source desktop=/data/codex/desktop \
+  --source laptop=/data/codex/laptop \
+  --source server=/data/codex/server \
+  --database usage.sqlite
+```
+
+Copy only the required provider data. For Codex, copy the `sessions/` directory but
+never `auth.json` or other credentials. Globally identical conversation IDs are
+deduplicated, and the most complete copy wins.
+
+Map original working-directory prefixes to stable project labels with repeated
+`--project NAME=PATH_PREFIX` options. The longest matching prefix wins:
+
+```bash
+uv run cli-consumption collect --provider codex \
+  --source desktop=/data/codex/desktop \
+  --project cli-consumption=/home/me/dev/cli-consumption
+```
+
+Plandex auto-detection checks `/plandex-server`. For any other trusted offline copy of
+a self-hosted server data directory, pass the path explicitly:
+
+```bash
+uv run cli-consumption collect --provider plandex \
+  --source server=/srv/plandex-server --database usage.sqlite
+```
+
+## Explore and share reports
+
+The dashboard can filter by time, provider, machine, project, and model. It reports
+activity, token composition, cache efficiency, latency and duration distributions,
+technical throughput, context pressure, work-item reliability, configuration cohorts,
+compactions, subagent delegation, and ingestion quality. Availability varies by
+provider, as summarized in the table above.
+
+Generate a more shareable dashboard by pseudonymizing labels, grouping tool names,
+rounding timestamps to days, and hiding small cohort rows:
+
+```bash
+uv run cli-consumption export --output shared-report --share-safe
+```
+
+Share-safe reports still disclose aggregate work patterns and remain private
+operational data. A technically completed turn is not a measure of task quality or
+productivity.
+
+## SQLite and PostgreSQL
+
+A file path selects SQLite. A SQLAlchemy URL selects PostgreSQL:
+
+```bash
+uv run cli-consumption collect --provider all --database usage.sqlite
+uv run cli-consumption collect --provider all \
+  --database postgresql+psycopg://usage@localhost/cli_consumption
+```
+
+Pass credentials through environment variables or a secret manager rather than shell
+history. `CLI_CONSUMPTION_DATABASE` can provide the database setting.
+
+## Central collector API
+
+Copied files are simplest for personal or air-gapped use. For recurring collection
+across machines, start the metadata-only API:
+
+```bash
+export CLI_CONSUMPTION_API_TOKEN="$(your-secret-provider)"
+uv run cli-consumption serve \
+  --database postgresql+psycopg://usage@localhost/cli_consumption \
+  --host 0.0.0.0
+```
+
+Then send all locally detected snapshots from another machine:
+
+```bash
+export CLI_CONSUMPTION_API_TOKEN="$(your-secret-provider)"
+uv run cli-consumption sync --provider all \
+  --endpoint https://usage.example.test
+```
+
+The application refuses to bind beyond localhost without a token. Production
+deployments also need TLS and standard operational controls. See
+[Architecture](docs/architecture.md) for the trade-offs.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `collect` | Collect local or copied provider data into SQL. |
+| `sync` | Collect and send metadata-only snapshots to a central API. |
+| `serve` | Run the central collection API. |
+| `export` | Write the HTML dashboard and optional CSV tables. |
+| `providers` | List provider names and support status. |
+
+Run `uv run cli-consumption COMMAND --help` for all options.
+
+## Development
+
+```bash
+uv sync --all-groups
+uv run pre-commit install
+uv run pre-commit run --all-files
+uv run ruff format --check .
+uv run ruff check .
+uv run ty check
+uv run pytest --cov --cov-report=term-missing
+uv build
+```
+
+Development uses short-lived branches and squash-merged pull requests into protected
+`main`. Read [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md) before
+changing the project.
+
+## License
+
+Licensed under the [Apache License 2.0](LICENSE).

{cli_consumption-0.0.18 → cli_consumption-0.1.0}/docs/architecture.md

@@ -16,12 +16,12 @@ provider files -> adapter -> metadata-only snapshot -> SQL storage -> dashboard/
 
 - `adapters`: parse a CLI's local data into conversations, turns, model calls, tool
   calls, context-pressure samples, bounded turn settings, compactions, and content-free
-  work-item intervals. Codex exposes the complete analytics contract; Aider, Amazon Q
+  work-item intervals. Codex exposes the complete analytics contract. Aider, Amazon Q
   Developer CLI, Amp, Cline CLI, Claude Code, Continue CLI, Crush, Cursor CLI, Gemini
-  CLI, GitHub Copilot CLI, Goose, Kilo Code, Kimi Code CLI, OpenCode, Pi, Plandex, and
-  Qwen Code expose the core dimensions available in their stores. OpenHands CLI
-  exposes the same core dimensions plus context windows and condensation timestamps
-  from its SDK persistence.
+  CLI, GitHub Copilot CLI, Goose, Grok Build, Kilo Code, Kimi Code CLI, OpenCode,
+  OpenHands CLI, Pi, Plandex, and Qwen Code expose the reliable subset available in
+  each local store. The exact differences are maintained in
+  [Provider support](provider-support.md).
 - `models`: define the transport boundary shared by offline and API ingestion.
 - `storage`: owns the normalized schema, idempotent replacement rules, SQLite, and
   PostgreSQL engine creation.
@@ -73,7 +73,7 @@ to an older strict API is rejected before ingestion, so central deployments must
 upgrade the server first. Downgrading a writer after rich metadata has been ingested is
 not supported because old writers do not know how to replace the new child rows.
 
-## Adapter roadmap
+## Adapter qualification
 
 Adapters are introduced one at a time because local data formats are undocumented or
 can evolve independently. Each adapter must have synthetic fixtures, format detection,

{cli_consumption-0.0.18 → cli_consumption-0.1.0}/docs/provider-support.md

@@ -31,6 +31,8 @@ It does not mean that token counters are equivalent to invoices.
 ingests each metadata-only snapshot independently. With no explicit source it checks
 the local default homes; repeated `--source` paths are filtered by detected format.
 
+## Codex
+
 Codex additionally exposes provider-reported turn duration and TTFT, model context
 window samples, bounded reasoning/collaboration/service-tier labels, timestamped
 compactions, technical work-item categories and durations, and local thread-spawn
@@ -38,6 +40,8 @@ relationships. Work-item content and rate-limit payloads are deliberately exclud
 Subagent state can remain `open` after a child thread is technically closed; reporting
 therefore derives closure from collected child turns when they are available.
 
+## Cursor CLI
+
 Cursor CLI reads Composer 2 transcripts from
 `~/.cursor/projects/*/agent-transcripts/<session-id>/<session-id>.jsonl` and optional
 session metadata from `~/.cursor/chats/*/<session-id>/store.db`. It extracts visible
@@ -58,13 +62,16 @@ transcripts, Cursor IDE history, background/cloud agents, subagent transcripts,
 compactions, context windows, costs, and provider-reported durations are not collected.
 The internal formats can change without notice, and local events are not billing data.
 
-Continue CLI reads session JSON files from `~/.continue/sessions/` (or
-`CONTINUE_GLOBAL_DIR`). The adapter was qualified against the current session format
-used by Continue CLI in August 2026. It extracts visible user turns, assistant model
-labels, per-response token usage when present, the cumulative session token snapshot,
-and function-call names while discarding titles, prompts, responses, reasoning, tool
-arguments/results, context items, editor state, rules, arbitrary metadata, costs, and
-credentials. Working directories are inspected only for explicit project mappings.
+## Continue CLI
+
+Continue CLI reads session JSON files from `~/.continue/sessions/`. A custom
+`CONTINUE_GLOBAL_DIR` must be passed with `--source`. The adapter was qualified against
+the current session format used by Continue CLI in August 2026. It extracts visible
+user turns, assistant model labels, per-response token usage when present, the
+cumulative session token snapshot, and function-call names while discarding titles,
+prompts, responses, reasoning, tool arguments/results, context items, editor state,
+rules, arbitrary metadata, costs, and credentials. Working directories are inspected
+only for explicit project mappings.
 
 Continue reports prompt and completion totals with optional cache-read, cache-write,
 and reasoning subsets. The adapter prefers per-response usage and adds only the
@@ -76,6 +83,8 @@ history stores, context-window sizes, compactions, provider-reported status, lat
 or cost. Continue's internal session format can change without notice, and local token
 events are not billing data.
 
+## Crush
+
 Crush reads its global project registry at
 `~/.local/share/crush/projects.json` and each registered project's `crush.db`, or a
 direct copied project/data directory. The adapter was qualified against Crush v0.91.2
@@ -92,8 +101,11 @@ data. Cache and reasoning splits are unavailable. Child agent sessions, costs,
 attachments, provider-reported latency, and context-window sizes are not collected.
 The SQLite schema is internal and can change without notice.
 
+## Claude Code
+
 Claude Code reads top-level sessions from
-`~/.claude/projects/<project>/<session-id>.jsonl` (or `CLAUDE_CONFIG_DIR`). It extracts
+`~/.claude/projects/<project>/<session-id>.jsonl`. A custom `CLAUDE_CONFIG_DIR` must
+be passed with `--source`. It extracts
 main-session turns, models, token usage, tool names, and compaction timestamps while
 discarding prompts, responses, tool inputs/results, paths, branches, and arbitrary
 metadata. Streaming fragments are deduplicated by request or message identifier.
@@ -105,6 +117,8 @@ is not billing data. This first increment does not collect subagent transcripts,
 context-window sizes, effort/service-tier settings, TTFT, provider-reported duration,
 or technical work-item intervals.
 
+## Gemini CLI
+
 Gemini CLI reads automatic session history from
 `~/.gemini/tmp/<project-hash>/chats/session-*.jsonl` and the legacy `.json` form. It
 replays append-only message updates, metadata checkpoints, and rewinds before extracting
@@ -122,6 +136,8 @@ context-window sizes, configuration labels, tool outcomes, or provider-reported
 durations. Gemini CLI's internal history schema can change without notice, and local
 token events are not billing data.
 
+## Goose
+
 Goose reads `sessions.db` from its sessions directory (normally
 `~/.local/share/goose/sessions/`). The adapter was qualified against Goose v1.47.0
 and schema v16. It extracts visible user turns, per-request model and token usage,
@@ -139,6 +155,8 @@ collect parent/subagent relationships, context-window sizes, reasoning tokens,
 provider-reported latency, or cost. Goose's internal schema can change without notice,
 and local token events are not billing data.
 
+## Grok Build
+
 Grok Build reads session directories under
 `~/.grok/sessions/<encoded-cwd>/<session-id>/`. It extracts stable session and
 prompt identifiers, timestamps, terminal turn status, model labels, per-turn
@@ -161,6 +179,8 @@ collected. The adapter was qualified against the open-source Grok Build session
 schema in August 2026. Local usage events are not billing records, and the
 internal format can change without notice.
 
+## OpenCode
+
 OpenCode reads `opencode.db` from its XDG data directory (normally
 `~/.local/share/opencode/`). It extracts v2 session messages, model references, token
 usage, tool names, and compaction timestamps while discarding message text, reasoning,
@@ -174,6 +194,8 @@ components. The adapter does not currently read pre-v2 JSON storage, legacy
 provider-reported cost. The SQLite schema is internal and may change without notice;
 local token events are not billing data.
 
+## OpenHands CLI
+
 OpenHands CLI reads SDK conversation persistence from
 `~/.openhands/conversations/<conversation-id>/`, including `base_state.json` and
 individual event JSON files. The adapter was qualified against OpenHands CLI v1.16.0
@@ -193,6 +215,8 @@ adapter does not collect cloud-only conversations, delegate relationships, cost,
 critic data, tool outcomes, or provider-reported response latency. OpenHands SDK
 persistence can change without notice, and local token events are not billing data.
 
+## Kilo Code
+
 Kilo Code reads `kilo.db` from its data directory (normally
 `~/.local/share/kilo/`). The adapter was qualified against Kilo Code CLI v7.5.5 and
 the matching current `session`, `message`, and `part` schema. It extracts user turns,
@@ -209,6 +233,8 @@ a non-default database, which must be passed explicitly with `--source`. Kilo Co
 SQLite schema can change without notice, and its local token events are not billing
 data.
 
+## Pi
+
 Pi reads session JSONL files under `~/.pi/agent/sessions/` (or copied agent
 directories). It extracts user turns, assistant and compaction model calls, provider
 and model identifiers, token usage, tool names, thinking-level changes, and compaction
@@ -224,6 +250,8 @@ session directories automatically, context-window sizes, costs, branch relations
 or provider-reported durations. Pi's JSONL schema can change without notice, and its
 local token events are not billing data.
 
+## GitHub Copilot CLI
+
 GitHub Copilot CLI reads session event logs from
 `~/.copilot/session-state/<session-id>/events.jsonl`. The adapter was qualified
 against GitHub Copilot CLI v1.0.80 and session event schema v1. It extracts root
@@ -245,8 +273,11 @@ cloud sessions, subagent relationships, context-window samples, cost, or billing
 data. The local session schema can change without notice, and local token aggregates
 are not billing records.
 
+## Qwen Code
+
 Qwen Code reads active session transcripts from
-`~/.qwen/projects/<project-id>/chats/<session-id>.jsonl` (or `QWEN_HOME`). It
+`~/.qwen/projects/<project-id>/chats/<session-id>.jsonl`. A custom `QWEN_HOME` must
+be passed with `--source`. It
 follows the latest `uuid`/`parentUuid` branch so turns abandoned by rewind are not
 counted, and extracts user turns, assistant model calls, token usage, context-window
 sizes, function-call names, and chat-compression timestamps. Prompts, responses,
@@ -264,6 +295,8 @@ input is unavailable in the serialized metadata. This adapter was qualified agai
 Qwen Code v0.22.2. Its internal transcript schema can change without notice, and local
 token events are not billing data.
 
+## Aider
+
 Aider reads an explicitly configured local analytics log named `analytics.jsonl` (for
 example, `AIDER_ANALYTICS_LOG=~/.aider/analytics.jsonl`). It groups events from
 `launched` through `exit`, extracts message-send attempts, model identifiers, and
@@ -280,6 +313,8 @@ identifier. Unknown custom model names may already be represented as
 `provider/REDACTED` by Aider. Its analytics event schema can change without notice,
 and local token events are not billing data.
 
+## Amp
+
 Amp reads thread JSON files under `~/.local/share/amp/threads/`. It extracts visible
 user turns, assistant model calls, per-inference token usage, tool names, and context
 window samples while discarding titles, prompts, responses, thinking, tool
@@ -297,6 +332,8 @@ collect thread content, subthread relationships, compaction markers, reasoning-t
 splits, costs, credits, or provider-reported latency. Amp's local mirror format is
 internal and can change without notice, and local token events are not billing data.
 
+## Cline CLI
+
 Cline CLI reads `~/.cline/data/sessions/sessions.db` and the referenced
 `*.messages.json` artifacts. It extracts session timestamps/status, configured model,
 visible user-turn boundaries, per-assistant token metrics, and tool names while
@@ -306,6 +343,8 @@ and writes; normalized uncached input is the non-negative remainder. Model and e
 timestamps come from each assistant artifact when present. The adapter was qualified
 against Cline CLI's current SDK session schema in August 2026.
 
+## Kimi Code CLI
+
 Kimi Code CLI reads `~/.kimi/sessions/*/*/wire.jsonl`. It extracts turn boundaries,
 step token usage, tool names, context-window samples, and completed compactions while
 discarding user input, model output, reasoning, tool arguments/results, approvals,
@@ -313,6 +352,8 @@ notifications, subagent payloads, paths, and arbitrary events. The wire log does
 persist the selected model label, so calls use `unknown`; hashed work-directory keys
 are not reversed. The adapter targets Wire v1 as qualified in August 2026.
 
+## Amazon Q Developer CLI
+
 Amazon Q Developer CLI reads persistent conversations from
 `~/.local/share/amazon-q/data.sqlite3`. It extracts user-turn timestamps, model labels,
 tool names, and request timing while discarding prompts, responses, transcripts,
@@ -322,6 +363,8 @@ conversation state contains no token counters, so all normalized token values ar
 Non-persistent sessions are unavailable. The adapter targets the current conversations
 table and serialized state format as qualified in August 2026.
 
+## Plandex
+
 Plandex reads an offline copy of a self-hosted server's `PLANDEX_BASE_DIR`, specifically
 `orgs/*/plans/*/conversation/*.json`. It extracts stable plan/message identifiers,
 timestamps, roles, stop status, and provider-reported per-message token totals while