agent-usage-tracker (aut)
Stop guessing how many tokens your coding agents use and what they actually do.
aut reads existing Claude Code, Codex, Cursor, and Pi logs. Export usage to a local CSV, or keep usage and sessions across machines in a database you control.
Optional local models classify the work as building, debugging, planning, or reviewing.
Use it to answer:
- Which agents and models do I use, and how many tokens do they consume?
- How much work involves building, debugging, planning, or reviewing?
- Which sessions belong to the same piece of work, and what became of it?
- Do I have a copy of my session logs if this laptop fails?
With uv installed, try a local export:
uvx agent-usage-tracker --agents claude_code,codex,cursor_cli,pi export --out usage.csv
AUT is a collector and CLI. For history and dashboards, it ships a Docker Compose sink (TimescaleDB and Grafana) that runs on your laptop or a homelab. There is no hosted service.
Quick start · Collectors · Local labels · Privacy · Documentation
What you can track
| Area | What AUT records | What you need |
|---|---|---|
| Usage | Input, output, cache-read, and cache-write tokens; model; project basename | Agent logs, or the optional Cursor API |
| Sessions and activity | Human prompts, turns, interrupts, tool counts, commits, PR links, and related sessions | PostgreSQL |
| Active time | ActivityWatch intervals and manual time entries | PostgreSQL; ActivityWatch is opt-in |
| Outcomes | Commit merge/revert/rework states and your own session verdicts | PostgreSQL and local Git clones |
| Local labels | Work categories, instruction types, and inferred outcomes | Saved model setup and local weights |
| Daily commits | Your commits across local and remote clones, deduplicated across copies | PostgreSQL and configured Git roots |
| Backups | Encrypted, deduplicated copies of logs, AUT configuration, and label files | A configured restic repository |
Token counts are usage, not your subscription bill. Dollar figures derived from them are estimated API-equivalent costs. Local collection works with subscription logs without adding a proxy or requiring an API key.
Quick start
Python 3.11 to 3.15; macOS, Linux, and Windows.
The base install uses the standard library, plus tzdata on Windows.
Try a local export
Install with uv:
uv tool install agent-usage-tracker
aut --agents claude_code,codex,cursor_cli,pi export --out usage.csv
For the newest main instead of the latest release, install from git+https://github.com/rhnfzl/agent-usage-tracker.
No database or configuration file is required for this export. It reads your current user's logs and writes usage rows to a local CSV. Cursor CLI contributes prompt rows, not token counts; choose a Cursor token source below for those. An unreadable source makes export exit nonzero, so a partial file cannot silently count as a complete export.
Keep history in your own database
Install the PostgreSQL extra:
uv tool install "agent-usage-tracker[postgres]"
Create ~/.config/agent-usage-tracker/config.toml with your machine label and database connection:
machine = "laptop"
agents = ["claude_code", "codex", "cursor_cli", "pi"]
[transport]
pg_dsn = "env:AUT_PG_DSN"
Set AUT_PG_DSN to your provisioned database connection.
The database needs AUT's tables and views. The sink stack provides them with one docker compose up;
the deploy runbook describes the sink contract.
Set ledger_timezone to the sink's AUT_TZ.
On macOS and Linux, protect the configuration with chmod 600.
On Windows, restrict its directory permissions to your account.
aut status
aut scan --dry-run
aut scan
The dry run parses logs and reports totals without sending rows. Real scans advance their watermark only after delivery succeeds. Repeated delivery is safe because the sink deduplicates event IDs. Native JSONL collection drains a finite file snapshot, including all capped chunks present when each file is admitted. Later appends, new files and replaced files wait for the next run. On POSIX, acknowledged closed Cursor CLI stores skip SQLite reads while database and WAL metadata stay unchanged.
Webhook-only scans keep session, activity, and time rows in a private local delivery queue.
aut status shows pending rows. After configuring PostgreSQL, scans replay them automatically;
aut retry-delivery also retries the queue directly. Keep the state directory in your backups.
For a full configuration, start from config.example.toml.
Put secrets in your local configuration or environment, never in this repository.
Scheduled jobs do not inherit your shell environment; configure their secrets separately.
Configuration
The configuration reference lists defaults, environment overrides, and local state files.
Use the same secret repo_key_salt across machines if their repository identities must match.
Preserve that salt in backups; replacing it breaks those cross-machine matches.
Collectors
| Agent | Source | Coverage and limits |
|---|---|---|
| Claude Code | ~/.claude/projects/ and Claude homes configured in T3 |
Usage, prompts, sessions, activity, and links |
| T3 Code | ~/.t3/userdata/statev2.sqlite |
Confirmed app prompts and completed app runs after an explicit cutover; native logs retain token usage |
| Codex | ~/.codex/sessions/ |
Usage, reasoning tokens, prompts, sessions, activity, and links |
| Pi | ~/.pi/agent/sessions/ |
Usage, reasoning tokens, prompts, sessions, activity, and links |
| Cursor CLI | ~/.cursor/chats/ and SDK run stores |
Prompts, sessions, activity, and links; no token counts |
| Cursor IDE | Local state.vscdb |
Prompt records and a lower bound on usage |
| Cursor API | Your dashboard account, explicitly enabled | Token usage for the IDE and CLI; no prompt records |
| Cursor SDK | Configured run manifests | Per-run usage from your SDK applications |
| ActivityWatch | Your local server, explicitly enabled | Active-window intervals; review title privacy settings first |
T3 activity collection requires an approved t3_activity_since timestamp in your local configuration:
t3_activity_since = "2026-11-15T00:00:00Z" # replace with your approved prospective cutover
Include "t3" beside your native collectors when agents is explicit.
T3 uses confirmed web/mobile messages and strong native bindings to avoid mirrored prompts.
Provider changes share one t3:<app-thread-id> session. Native logs remain the source of tokens and costs.
T3 turns count completed app runs, which can contain several internal agent turns.
Missing or ambiguous evidence reports degraded coverage. Existing history is not reconciled automatically.
Choose one Cursor token source: cursor, cursor_api, or cursor_sdk.
Combining them can double-count usage. cursor_cli has no tokens and can run beside any of them.
To collect IDE prompts beside API usage, add cursor with cursor_human_only = true.
The collector reference covers source paths, defaults, and ActivityWatch filtering. Collectors use the running user's home and explicitly registered engine homes. They do not search other users' accounts.
Run aut doctor --json to inspect readable sources, parser losses, pending delivery and evidence limits.
Normal scans save a private coverage report and report changed gaps.
A sourced catalog covers 25 coding tools without claiming that each has a qualified reader.
See shared harness coverage for profiles, session associations and publication receipts.
Local labels (aut label)
Optional decision models turn session evidence into categories such as building, debugging, planning, and review. They can also classify your instructions and infer whether a piece of work is resolved, blocked, or still open.
Local estimates read Claude Code, Codex, Cursor CLI, and Pi inputs. Prompts and final replies stay inside the episode's time bounds. Daily work also stops at local midnight, so shared sessions cannot mix separate work days. Cursor replies are omitted because their stores lack reliable per-reply timestamps. Cases without sufficient evidence stay unclassified; uncertain model decisions stay unknown.
| Workflow | Use it for | Setup |
|---|---|---|
| Calibrated labels | Evaluating models against reviewed examples | Review examples, evaluate, and save a model choice |
| Provisional local estimates | Ongoing classification with an existing local recipe | Save label-local.json, install the required runtime, and cache its exact weights |
Collection does not require models, annotation, or cloud spending.
Saved local recipes can combine models; they are not automatically fitted or selected for you.
The MLX backends require Apple silicon. GGUF backends use a separately installed llama-server.
AUT never downloads weights during classification.
An optional writing attribute records explicit
requests for prose deliverables alongside the main work category, using a separate local recipe.
With a saved local recipe:
aut label run --local-estimates --task work_category
For historical work, prepare a job and resume its saved ID:
aut label replay --task work_category --since 2026-01-01 --until 2026-02-01
aut label replay --job JOB_ID --apply --budget-s 600
Preparation previews coverage and freezes private inputs without running models or sending labels.
The end date is exclusive. Resume the same job until complete is true; progress follows successful batch delivery.
Frozen jobs keep their original inputs when new readers are installed.
Mature-outcome catch-up is separately opt-in through label_mature_outcomes; it is disabled by default.
See the local-label guide for model setup, ensembles, cutoffs, calibration, and replay privacy. Provisional charts describe estimates, not verified classification accuracy.
The models
The model reference lists supported backends, pinned downloads, runtime needs, and synthetic timing measurements. Choose and evaluate models for your own tasks; the timing table does not establish classification accuracy.
Private improvement (aut improve)
Optional local diagnosis finds evidence of avoidable recovery and unsupported completion claims. It saves private evidence, provisional model judgments, scoped patch proposals, and controlled command checks. These records stay separate from the normal sink. Installed instructions do not change automatically.
Private studies connect incident evidence, prospective trial policies and fresh follow-up. They preserve rejected runs and distinguish bounded code correctness from general productivity. See the study guide for commands and evidence requirements.
Additional producers can supply private usage, quota and tool observations through the
observation guide. aut observe imports explicit files, renders private quota reports,
and offers an opt-in authenticated receiver. Public exports are local drafts.
Native desktop receipts use aut improve desktop; command success does not establish task acceptance.
aut improve audit --days 7 --limit 30
aut improve status
Local judging uses cached models through the existing label extra.
Bounded reviews preserve completed judgments and resume unfinished work within the configured budget.
aut improve inspect --case CASE_ID writes a private view of a captured attempt and its source references.
Missing or clipped evidence stays explicit; inspection does not upgrade a judgment.
Read the private improvement guide before judging, staging changes, or executing trials.
The guide covers executable judge references, independent agent-task acceptance, and stable wheel installations.
Scheduling
Run AUT on each machine whose logs you want to collect. The supplied timers scan every 15 minutes on macOS and Windows, or every 10 minutes on Linux. The macOS scan also catches up at login and after sleep.
The optional wrapper adds SSH tunnelling, retries, daily commit outcomes, and local labels.
Update the installed package before copying a new wrapper; the wrapper calls aut scan-job.
The scheduler prevents overlapping runs and records daily success only after each step completes.
Failed or unfinished daily steps retry after the next successful scan.
Local scheduled labels require AUT_LABEL=1 and AUT_LABEL_MODE=local in scan.env, plus saved recipes.
An interrupted historical replay resumes when you invoke its saved job again; preparing a job does not install a scheduler.
Follow the timer setup and wrapper reference.
Keep scripted Cursor work out of your human counts
Use aut cursor-run --model MODEL --workspace /path/to/workspace < prompt.txt for scripted requests.
It registers the chat as automated before sending the prompt through your installed cursor-agent account.
Registered prompts do not increase human steer counts; automated turns and child links remain available.
This command can spend your account's credits. Normal collection never invokes it.
Direct Cursor calls bypass this registration; existing database records require a separate audited repair.
Back up your logs
aut backup uses restic to copy agent logs, AUT configuration, label files, and the repository-key salt.
The shipped macOS backup job runs daily at 02:30 and at login.
Backup destinations, passwords, retention, and any offsite copy require your own setup.
The database needs its own backup.
Follow backup and laptop recovery before relying on recovery.
aut status reports the age of the last good backup; aut backup --check checks the repository.
Privacy model
AUT sends rows only to the sink you configure. It publishes nothing itself. Normal collection sends counts and identifiers, not prompt text, tool output, commit messages, or full local paths. Repository identities and references use salted HMAC keys.
Some metadata remains readable: project basenames, session IDs, commit SHAs, skill names, and tool counts.
ActivityWatch can send redacted window titles unless you turn titles off; app names are still sent.
The optional daily_note task sends a generated note.
Local replay jobs retain redacted input text on disk. Keep them and your evaluations outside the public source repository.
The optional teacher command sends sampled Claude Code text through claude -p; local classification does not need it.
Cursor API collection and cursor-run also make account-authenticated network calls when explicitly used.
Read the full privacy and network-call reference before enabling optional collectors or model workflows.
Commands
| Start with | Purpose |
|---|---|
aut status |
Check configuration, progress, and backup age |
aut scan --dry-run |
Inspect parsed totals without sending rows |
aut scan |
Deliver new usage and activity |
aut export --out usage.csv |
Export local usage without a sink |
aut git-days --dry-run |
Preview daily commit counts across configured clones |
aut git-days --local-only |
Collect available local commits while remote machines are offline; mark incomplete coverage |
aut inspect --day YYYY-MM-DD |
Inspect the local evidence behind a day's episodes |
aut backup --check |
Verify your configured restic repository |
Use aut --help or aut <command> --help for options.
The full command reference includes backfills, outcomes, review pages, and model evaluation.
Documentation
| Guide | Read it when you want to... |
|---|---|
| Configuration example | Choose sources, transports, and optional features |
| Command and configuration reference | Look up commands, defaults, local files, privacy rules, or errors |
| Local labels and models | Configure decisions, evaluate models, or classify historical work |
| Scheduling | Install macOS, Linux, or Windows timers |
| Backup and recovery | Preserve logs and recover on another machine |
| Deploy runbook | Provision a self-hosted sink and connect collectors |
| Data contract | Build database views, dashboards, or a website from AUT rows |
Development
From a checkout:
In restricted agent sessions, keep uv's cache inside the checkout before running these commands:
export UV_CACHE_DIR="$PWD/.agent-harness/uv-cache"
uv venv
uv pip install -e ".[test,postgres]" ruff==0.15.11 mypy==2.4.1
uv run --no-sync pytest -q
uv run --no-sync ruff check .
uv run --no-sync mypy
The CI workflow tests Linux, macOS, and Windows across supported Python versions.
SQL integration tests require a scratch database on a TimescaleDB server and psql, through AUT_TEST_PG_DSN with a literal IP address and port; otherwise those tests skip.
To release, raise __version__ in src/agent_usage_tracker/__init__.py, merge, and push the tag v<version>.
The release workflow builds it and publishes it to PyPI through trusted publishing.
Use synthetic fixtures in public contributions. Keep session logs, personal labels, and private benchmarks out of commits.
MIT licensed. See LICENSE.
Metadata
Release files for agent-usage-tracker 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agent_usage_tracker-0.1.0.tar.gz | 845.1 kB | With provenance | Details for agent_usage_tracker-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agent_usage_tracker-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for agent_usage_tracker-0.1.0-py3-none-any.whl |
Total release size: 1.3 MB
Release files / agent_usage_tracker-0.1.0.tar.gz
| Download URL | agent_usage_tracker-0.1.0.tar.gz |
|---|---|
| Size | 845.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
37ab4ed06d1b6c04cb186c24c968cc45cc7a939ecb6634e872f06eb92bde454f
|
|
BLAKE2b-256 checksum How to use checksums |
7e41e5c68a7098d7c40663b84194e54994b51d013af6ed87016c5b4db7bbf2f0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logRelease files / agent_usage_tracker-0.1.0-py3-none-any.whl
| Download URL | agent_usage_tracker-0.1.0-py3-none-any.whl |
|---|---|
| Size | 445.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c23acd354992a84f168921a9e714f1346ad716c3cb7e606927f8d03301a989a6
|
|
BLAKE2b-256 checksum How to use checksums |
65baa431311a8f5c3954a79ab5c05f81a92e6b7e8707721d92ba7343e3b54573
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logSecurity for agent-usage-tracker 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for agent_usage_tracker-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.