Metadata-Version: 2.5
Name: codex-agent-hour-tracker
Version: 0.2.0
Summary: Measure cumulative Codex agent runtime without decoding conversation content.
Project-URL: Homepage, https://agenthours.dev
Project-URL: Repository, https://github.com/tim-osterhus/codex-agent-hour-tracker
Project-URL: Issues, https://github.com/tim-osterhus/codex-agent-hour-tracker/issues
Author-email: Tim Osterhus <tim@millrace.ai>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,analytics,codex,privacy
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.11
Requires-Dist: tzdata>=2025.2; platform_system == 'Windows'
Requires-Dist: tzlocal<6,>=5.3
Description-Content-Type: text/markdown

# 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](https://agenthours.dev).

```bash
uvx codex-agent-hour-tracker --share
```

Requires [uv](https://docs.astral.sh/uv/getting-started/installation/) 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

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

Or use pipx:

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

```bash
agent-hours --share --human-hours 160
```

Or estimate them from a weekly schedule:

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

```bash
agent-hours --share --format json
```

Paste this sanitized aggregate JSON into the [share studio](https://agenthours.dev/#share). 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:

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

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

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

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

```bash
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](https://agenthours.dev/benchmarks/) and the [methodology](docs/methodology.md) 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

```bash
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](docs/exports.md) 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](https://github.com/tim-osterhus/codex-agent-hour-tracker/tree/main/skills/codex-agent-hour-tracker/) guides collection and sharing workflows. It is not required to install or run the tool.

Read the [changelog](CHANGELOG.md), [security policy](SECURITY.md), and [MIT license](LICENSE).
