Metadata-Version: 2.5
Name: cli-consumption
Version: 0.0.16
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 is a local-first Python package for measuring how AI coding CLIs use
models, tokens, tools, conversations, and turns. It can analyze one workstation,
consolidate copied data from several machines, or send metadata-only snapshots to a
central collector.

Amp, Codex, Continue CLI, Cursor CLI, GitHub Copilot CLI, Crush, Aider, Gemini
CLI, Goose, Grok Build, Kilo Code, Pi, Qwen Code, OpenCode, and the core Claude
Code local transcript format are supported.

The collector deliberately excludes prompts, responses, tool arguments, and
credentials. See [Privacy](docs/privacy.md) before sharing a database or export.

## Quick start

The project requires Python 3.14 or newer and uses
[`uv`](https://docs.astral.sh/uv/) for every development and execution workflow.

From a checkout:

```bash
uv sync
uv run cli-consumption collect
uv run cli-consumption export --output reports
```

Open `reports/dashboard.html` locally. The generated dashboard is self-contained and
makes no network requests. Detailed normalized CSV tables are opt-in with `--csv`.

The dashboard supports time, provider, machine, project, and model filters. It reports
period-over-period activity, token composition, cache efficiency, turn latency and
duration distributions, technical throughput, context pressure, content-free work-item
duration and reliability, configuration cohorts, compactions, subagent delegation, and
ingestion quality. Token events are local usage metadata rather than billing records,
and a technically completed turn is not a measure of task quality or productivity.

For a dashboard that is safer to share, pseudonymize
machine, project, model, and role labels, group tool names, round timestamps to days,
and hide small rows in the cohort-comparison view:

```bash
uv run cli-consumption export --output shared-report --share-safe
```

Share-safe reports still disclose aggregate work patterns and must be treated as
private operational data.

From PyPI, the CLI can run without a permanent installation:

```bash
uv tool run cli-consumption collect
uv tool run cli-consumption export --output reports
```

To run the latest unreleased GitHub source instead:

```bash
uv tool run --from git+https://github.com/Guillaume-Lombardo/cli-consumption \
  cli-consumption providers
```

## Collect from one or more machines

With no source option, `collect` reads `~/.codex` and labels it with the local
hostname:

```bash
uv run cli-consumption collect --database usage.sqlite
```

Select Claude Code to read `~/.claude/projects/` instead:

```bash
uv run cli-consumption collect --provider claude --database usage.sqlite
```

Select OpenCode to read `~/.local/share/opencode/opencode.db` instead:

```bash
uv run cli-consumption collect --provider opencode --database usage.sqlite
```

Select Crush to read its global project registry and per-project SQLite stores:

```bash
uv run cli-consumption collect --provider crush --database usage.sqlite
```

Select Cursor CLI to read its local Composer 2 transcripts and chat metadata:

```bash
uv run cli-consumption collect --provider cursor --database usage.sqlite
```

Select Amp to read its local thread mirror:

```bash
uv run cli-consumption collect --provider amp --database usage.sqlite
```

Select GitHub Copilot CLI to read its local session event logs:

```bash
uv run cli-consumption collect --provider copilot --database usage.sqlite
```

Select Continue CLI to read its local session JSON files:

```bash
uv run cli-consumption collect --provider continue --database usage.sqlite
```

Select Kilo Code to read `~/.local/share/kilo/kilo.db` instead:

```bash
uv run cli-consumption collect --provider kilo --database usage.sqlite
```

Select Goose to read `~/.local/share/goose/sessions/sessions.db` instead:

```bash
uv run cli-consumption collect --provider goose --database usage.sqlite
```

Select Grok Build to read `~/.grok/sessions/` instead:

```bash
uv run cli-consumption collect --provider grok --database usage.sqlite
```

Select Pi to read `~/.pi/agent/sessions/` instead:

```bash
uv run cli-consumption collect --provider pi --database usage.sqlite
```

Select Gemini CLI to read `~/.gemini/tmp/*/chats/` instead:

```bash
uv run cli-consumption collect --provider gemini --database usage.sqlite
```

Select Qwen Code to read `~/.qwen/projects/*/chats/` instead:

```bash
uv run cli-consumption collect --provider qwen --database usage.sqlite
```

Select Aider to read a local analytics log configured at
`~/.aider/analytics.jsonl` instead:

```bash
export AIDER_ANALYTICS_LOG="$HOME/.aider/analytics.jsonl"
uv run cli-consumption collect --provider aider --database usage.sqlite
```

Use `all` to detect and collect every supported provider present on the machine:

```bash
uv run cli-consumption collect --provider all --database usage.sqlite
```

With explicit copied sources, each path is inspected for the provider-specific
`sessions/` or `projects/` directory. Sources that contain no supported provider data
are rejected instead of silently skipped.

For an offline multi-machine workflow, copy only each machine's Codex `sessions/`
directory into a trusted analysis location. Do not copy `auth.json` or other
credentials. Then repeat `--source`:

```bash
uv run cli-consumption collect \
  --source desktop=/data/codex/desktop \
  --source laptop=/data/codex/laptop \
  --source server=/data/codex/server \
  --database usage.sqlite
```

Globally identical conversation IDs are deduplicated. If copies differ, the most
complete rollout wins. Explicit project mappings use the longest matching original
working-directory prefix:

```bash
uv run cli-consumption collect \
  --source desktop=/data/codex/desktop \
  --project cli-consumption=/home/me/dev/cli-consumption
```

Copied Claude Code sources point to the configuration directory containing `projects/`:

```bash
uv run cli-consumption collect --provider claude \
  --source desktop=/data/claude/desktop \
  --source laptop=/data/claude/laptop
```

Copied OpenCode sources point to the data directory containing `opencode.db`:

```bash
uv run cli-consumption collect --provider opencode \
  --source desktop=/data/opencode/desktop \
  --source laptop=/data/opencode/laptop
```

Copied Crush sources can point directly to a project directory containing
`.crush/crush.db`, or to the data directory containing `crush.db`:

```bash
uv run cli-consumption collect --provider crush \
  --source desktop=/data/crush/desktop/project-a \
  --source laptop=/data/crush/laptop/project-b/.crush
```

Copied Cursor CLI sources point to a data directory containing `projects/`, `chats/`,
or both:

```bash
uv run cli-consumption collect --provider cursor \
  --source desktop=/data/cursor/desktop \
  --source laptop=/data/cursor/laptop
```

Copied Amp sources point to the data directory containing `threads/`:

```bash
uv run cli-consumption collect --provider amp \
  --source desktop=/data/amp/desktop \
  --source laptop=/data/amp/laptop
```

Copied GitHub Copilot CLI sources point to the configuration directory containing
`session-state/`:

```bash
uv run cli-consumption collect --provider copilot \
  --source desktop=/data/copilot/desktop \
  --source laptop=/data/copilot/laptop
```

Copied Continue CLI sources point to the global directory containing `sessions/`:

```bash
uv run cli-consumption collect --provider continue \
  --source desktop=/data/continue/desktop \
  --source laptop=/data/continue/laptop
```

Copied Kilo Code sources point to the data directory containing `kilo.db`:

```bash
uv run cli-consumption collect --provider kilo \
  --source desktop=/data/kilo/desktop \
  --source laptop=/data/kilo/laptop
```

Copied Goose sources point to the sessions directory containing `sessions.db`:

```bash
uv run cli-consumption collect --provider goose \
  --source desktop=/data/goose/desktop \
  --source laptop=/data/goose/laptop
```

Copied Grok Build sources point to the `.grok` data directory containing
`sessions/`:

```bash
uv run cli-consumption collect --provider grok \
  --source desktop=/data/grok/desktop \
  --source laptop=/data/grok/laptop
```

Copied Pi sources point to the agent directory containing `sessions/`:

```bash
uv run cli-consumption collect --provider pi \
  --source desktop=/data/pi/desktop \
  --source laptop=/data/pi/laptop
```

Copied Gemini CLI sources point to the configuration directory containing `tmp/`:

```bash
uv run cli-consumption collect --provider gemini \
  --source desktop=/data/gemini/desktop \
  --source laptop=/data/gemini/laptop
```

Copied Qwen Code sources point to the runtime directory containing `projects/`:

```bash
uv run cli-consumption collect --provider qwen \
  --source desktop=/data/qwen/desktop \
  --source laptop=/data/qwen/laptop
```

Copied Aider sources point to a directory containing `analytics.jsonl`:

```bash
uv run cli-consumption collect --provider aider \
  --source desktop=/data/aider/desktop \
  --source laptop=/data/aider/laptop
```

## SQLite and PostgreSQL

A file path selects SQLite. A SQLAlchemy URL selects PostgreSQL:

```bash
uv run cli-consumption collect --database usage.sqlite
uv run cli-consumption collect \
  --database postgresql+psycopg://usage@localhost/cli_consumption
```

Pass credentials through environment variables or a secret manager rather than shell
history. `CLI_CONSUMPTION_DATABASE` can supply the database setting.

## Central collector API

Offline imports are the simplest choice for personal use and air-gapped machines. A
central API is useful for recurring collection across machines.

Start the collector locally:

```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
```

Send a snapshot from another machine:

```bash
export CLI_CONSUMPTION_API_TOKEN="$(your-secret-provider)"
uv run cli-consumption sync --endpoint https://usage.example.test
```

The application refuses to bind beyond localhost without a token. Production
deployments must also place TLS and normal operational controls in front of the ASGI
server. See [Architecture](docs/architecture.md) for trade-offs.

## Commands

```text
cli-consumption collect    Collect local or copied provider data into SQL
cli-consumption sync       Collect and send a snapshot to a central API
cli-consumption serve      Run the central collection API
cli-consumption export     Write the HTML dashboard and optional CSV tables
cli-consumption providers  Show supported and planned providers
```

Run `uv run cli-consumption COMMAND --help` for every option.

## 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 follows short-lived branches and squash-merged pull requests into a
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). It provides permissive reuse plus an
explicit patent grant and contribution protections appropriate for an extensible
developer tool.
