Skip to main content

agent-usage-tracker (aut)

CI Python License: MIT Platforms

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)

Source distribution for agent-usage-tracker 0.1.0
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)

Table of built distributions (wheels) for agent-usage-tracker 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page