Agent Hours

Agent Hours is a local CLI that measures cumulative Codex agent-hours from completed turns.

See your runtime across profiles and machines, calculate optional Agent Leverage, and make a share card at agenthours.dev.

uvx codex-agent-hour-tracker --share

Requires uv and a local Codex session archive. The package supports Python 3.11–3.14 on macOS, Linux, and Windows. Archive-derived runtime is an estimate: missing records and sparse timestamps affect coverage.

Your Agent-Hour Score

The score is mean cumulative runtime across the 30 most recent completed local calendar days ending yesterday. Zero-use days count. Overlapping turns count independently: three agents running for one hour contribute three agent-hours.

If today is March 1 in a non-leap year, the window is January 30 through February 28. Custom date ranges produce reports, not canonical scores.

The default interactive-only scope excludes exec/batch files. It includes delegated turns and non-batch turns with uncertain source metadata. Use --include-exec to count exec/batch work as well. Every score states its scope.

Install once

uv tool install codex-agent-hour-tracker
agent-hours --share

Or use pipx:

pipx install codex-agent-hour-tracker
codex-agent-hour-tracker --share

Both command names invoke the same tool. Upgrade an existing uv installation with uv tool upgrade codex-agent-hour-tracker.

Calculate Agent Leverage

Supply your human hours for the entire report period:

agent-hours --share --human-hours 160

Or estimate them from a weekly schedule:

agent-hours --share --human-hours-per-week 40

Agent Leverage divides agent runtime by human hours over the same period. A weekly estimate uses weekly hours × calendar days / 7. The output identifies the assumption. The tool does not measure your human work time or infer it from prompt timestamps.

Make a share card

agent-hours --share --format json

Paste this sanitized aggregate JSON into the share studio. Preview and download a square or landscape PNG/SVG in your browser. Calculation and image generation run locally. The website accepts only the public score schema.

--share is the safe default for sharing, but dates, counts, durations, timezone, and optional human-hours assumptions remain a deliberate aggregate disclosure. Review the card before posting it.

Profiles and machines

Repeat --sessions-dir to combine local profile directories:

agent-hours --sessions-dir PROFILE_A/sessions --sessions-dir PROFILE_B/sessions --share

For multiple machines, export private timing metadata on each machine:

mkdir -p reports
agent-hours --export reports/laptop.agent-hours-private.json --label laptop

Transfer those private exports using your own secure file-transfer method, then merge them:

agent-hours --merge reports/laptop.agent-hours-private.json \
  --merge reports/desktop.agent-hours-private.json --share --include-exec

The merge deduplicates turn identifiers before calculating the combined total. Private exports retain all source classes so you can choose the scope when merging. They contain precise timestamps and hashed turn identifiers. Do not upload them to the website or commit them. The tracker does not read account credentials or separate accounts that share a session directory.

Daily and monthly reports

Explicit --start and --end values define an inclusive local-calendar range:

mkdir -p reports
agent-hours --start 2025-01-01 --end 2025-01-30 --monthly \
  > reports/january-summary.txt
agent-hours --start 2025-01-01 --end 2025-01-30 --format csv \
  > reports/january-summary.csv

Text reports include daily distribution, monthly summaries when requested, and human-initiated top-level turn count, mean, and median duration. CSV retains one row per calendar date. Partial-month averages use only the days in the requested range. Use --timezone IANA_ZONE when combining machines with different local timezones.

Full reports and CSVs reveal semi-sensitive activity patterns. Keep generated files in the ignored reports/ directory and review any output before distribution.

What the numbers can tell you

Agent-hours measure runtime, not useful output, human-equivalent labor, or time saved. Benchmarks are dated contextual references, not a personal ranking. See benchmarks and the methodology for populations, denominators, and timing rules.

The scanner retains compact timing metadata without decoding conversation, reasoning, or tool payloads. No session data leaves the machine through the CLI. Compacted records remain supported while completed-turn metadata survives.

Development

uv run python -m unittest discover -s tests -v
node --test tests/site*.mjs
python3 scripts/sync_benchmarks.py --check

The repository has a Python package in src/agent_hour_tracker/, synthetic tests in tests/, and a static website in site/. The export contracts define private merge data and public score data separately. The package benchmark registry generates the website copy through scripts/sync_benchmarks.py.

The optional Codex skill guides collection and sharing workflows. It is not required to install or run the tool.

Read the changelog, security policy, and MIT license.