Know where your Codex usage goes.

Ledger is an open-source, local-first usage analytics dashboard for Codex. It turns the usage telemetry already persisted on your machine into a clear view of tokens, projects, models, sessions, per-turn context growth, cache efficiency, trends, and observed quota windows.

No Ledger account. No cloud backend. No telemetry.

Recommended: install Ledger for Codex as a Plugin and ask Codex to open or analyze your local usage. Prefer a plain script? Clone the repo and run one Python command.

See it in 30 seconds

Question	Ledger shows you
How much have I used?	Total observable tokens + period comparison
Am I consuming too fast?	Burn rate + observed quota-window pacing
Where did it go?	Project, model, and model × project breakdowns
Why was a session so large?	Tokens / turn, context growth, peak turn, cache reuse, and transparent drivers
What changed?	Previous-period deltas + rule-based usage insights
Is the data leaving my machine?	No. Parsing and reports are local by default

_{The screenshot uses synthetic demo data. Ledger does not ship anyone's real usage history.}

Why Ledger?

Codex can do a lot of work, but the raw usage trail is hard to reason about at a glance.

Without Ledger	With Ledger
“Where did my usage go?”	Project and model attribution
“Why was this session so large?”	Session health, context growth, peak turn, and transparent drivers
“Is today unusual?”	Burn rate, outliers, and previous-period comparison
“Did cache help?”	Cache hit and cached / uncached input breakdown
“How much quota is left?”	Observed 5-hour / weekly snapshots when Codex persisted them

Ledger does not invent an account quota from token totals. If Codex did not persist a rate-limit snapshot, the quota cards say it is unavailable.

What Ledger shows you

Understand your usage observable token totals burn rate tokens per session / turn cache hit rate previous-period comparison	See where it goes project breakdown model breakdown model × project matrix token timeline token composition
Understand sessions tokens / turn first-vs-last context growth peak turn detection session health using your own baseline session detail + transparent consumption drivers	Spot changes rule-based usage insights period-over-period deltas task outliers observed quota pacing when available

Install as a Codex Plugin · recommended

Ledger is packaged as a portable Agent Plugin with a bundled ledger-analysis Skill. No MCP server or external account is required in v0.2.

1. Add the GitHub marketplace

codex plugin marketplace add ctdaniel/codex-ledger

2. Install Ledger for Codex

Open the Plugin directory in ChatGPT desktop or Codex CLI, choose the Ledger for Codex marketplace, and install Ledger for Codex. In Codex CLI, use /plugins to open the plugin browser.

Start a new session after installation if the new Skill does not appear immediately. The Codex IDE extension does not currently provide the plugin browser, so use ChatGPT desktop or Codex CLI for installation.

3. Ask Codex

Open my Codex usage dashboard.

Analyze my Codex usage for the last 7 days.

Show me my 5 most expensive Codex tasks.

The bundled Skill runs the local parser, starts the private local dashboard, and can analyze the sanitized normalized payload without dumping raw rollout logs into the conversation.

Plugin installation behavior can vary by supported client. The marketplace command and package format follow the current OpenAI Plugin documentation. The direct local method below remains available even when a client does not expose Plugins.

Update Ledger

If you installed Ledger as a Codex Plugin

The codex terminal command comes from Codex CLI. Installing Ledger from ChatGPT desktop does not automatically install the CLI on your shell.

Check whether Codex CLI is available:

command -v codex
codex --version

If your terminal says codex: command not found, install the current Codex CLI on macOS / Linux with OpenAI's installer:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Then open a new terminal and verify:

codex --version

Refresh the Ledger marketplace snapshot:

codex plugin marketplace upgrade codex-ledger

You can inspect configured marketplaces first if needed:

codex plugin marketplace list

After upgrading, start Codex, open /plugins, confirm Ledger for Codex is installed, then start a new session so the updated Skill is loaded.

If Ledger was installed through a workspace-synced GitHub marketplace, an admin can instead use Workspace settings → Plugins → Marketplaces → Sync now. If an individually imported plugin shows a Refresh action, that action refreshes the plugin source.

If you cloned the repository directly

cd codex-ledger
git pull
python3 scripts/ledger.py --open

Run locally

Ledger has no npm dependencies and no build step. Python 3 parses your local Codex session telemetry and serves the dashboard on 127.0.0.1. With --open, the Refresh data button rescans ~/.codex immediately — no model call and no Codex quota is used for the refresh itself.

git clone https://github.com/ctdaniel/codex-ledger.git
cd codex-ledger
python3 scripts/ledger.py --open

With --open, Ledger:

reads $CODEX_HOME or ~/.codex,
scans the most recent 90 days of persisted sessions,
keeps only normalized usage metadata,
writes the report to ~/.codex/ledger/latest/,
starts a local-only HTTP server on 127.0.0.1,
opens the dashboard in your browser,
rescans local Codex telemetry whenever you click Refresh data.

Keep the terminal process running while you use live refresh. Press Ctrl+C to stop it. If you open the generated index.html directly with file://, it is a static snapshot and cannot rescan local files from the browser sandbox.

Useful options:

# Parse all discoverable persisted sessions
python3 scripts/ledger.py --days 0 --open

# Write to a different local directory
python3 scripts/ledger.py --output ./ledger-report --open

# Serve without opening a browser
python3 scripts/ledger.py --serve

# Print the sanitized normalized payload instead of generating a report
python3 scripts/ledger.py --json

Want to inspect the interface without reading Codex data? Open the repository's index.html; it uses deterministic synthetic demo fixtures.

Using Ledger

Dashboard

Use Today / Last 7 days / Last 30 days / Custom and filter by project, task, or model. All derived cards, charts, insights, rankings, and task details recalculate from the same filtered dataset.

Ledger distinguishes three kinds of information:

Observed — directly present in locally persisted Codex telemetry.
Calculated — derived locally from observed records.
Estimated — a forecast or rate-weighted heuristic; never presented as official billing or quota data.

From Codex

With the Plugin installed, try:

Why was my most expensive Codex session so large?

Which sessions have the fastest context growth?

Did my tokens per turn increase versus the previous period?

Which long sessions also have unusually low cache reuse?

Do I have an observed quota snapshot right now?

How it works

The parser currently reads Codex's persisted local rollout JSONL on a best-effort basis. It uses per-request last_token_usage events; it deliberately does not sum cumulative total_token_usage snapshots, which would overcount the same usage repeatedly.

For project attribution, Ledger keeps only the final directory name from cwd. The local report may also include the persisted session/thread title so you can identify tasks.

Privacy

Your usage data should stay yours.

Ledger is local-first by design.

✅ no Ledger account
✅ no cloud backend required
✅ no telemetry
✅ no prompt-body upload
✅ no assistant/tool-output upload
✅ no code or repository-content upload
✅ no API key or auth-file collection
✅ full local paths are stripped from the generated report

The generated local dashboard can contain session titles and project-folder basenames because those are needed for useful attribution. They remain on your machine unless you explicitly share the generated report or a screenshot.

The repository's demo data is synthetic. Files matching local report / snapshot patterns are ignored by Git.

Data coverage & limitations

Ledger v0.2 intentionally avoids pretending that local telemetry is a formal billing or context-window API.

Codex's persisted local session format can evolve; the parser is best-effort and covered by fixtures/tests.
Sessions without persisted last_token_usage events cannot contribute token records.
Context Growth uses observed per-turn input tokens as a local proxy; it is not official context-window occupancy.
Session Health is relative to your own local usage distribution, not an external benchmark or a quality score.
Quota cards are shown only when a persisted rate_limits snapshot is observed.
Refresh data rescans quota snapshots already persisted by Codex; it cannot force Codex to query the account quota service. When an observed reset boundary passes, Ledger hides the old percentage instead of showing a stale value. Use Codex once, then click Refresh data to load the next persisted snapshot.
Ledger never converts token totals into an invented 5-hour or weekly quota percentage.
Generation speed appears only when usable duration telemetry is present.
Model rate-weighted intensity appears only for models with a known built-in mapping; otherwise it is left unavailable.

If Codex changes its local telemetry format, please open an issue with a sanitized schema sample, never a raw session containing private content.

Plugin package

Ledger's repository root is also its portable Agent Plugin package:

codex-ledger/
├── plugin.json                       # Agent Plugins 1.0 portable manifest
├── .codex-plugin/plugin.json         # Codex compatibility fallback
├── skills/
│   └── ledger-analysis/
│       ├── SKILL.md
│       └── references/
├── scripts/
│   └── ledger.py                     # local, dependency-free parser
├── .agents/plugins/marketplace.json  # GitHub marketplace catalog
├── index.html
├── app.css
├── app.js
└── assets/

The Plugin is intentionally Skill-first in v0.2. A local MCP server is not required just to read files already available on your machine and render the dashboard.

Development

Run the checks:

python3 -m unittest discover -s tests -v
node --check app.js
python3 -m json.tool plugin.json >/dev/null
python3 -m json.tool .agents/plugins/marketplace.json >/dev/null

See CONTRIBUTING.md for contribution guidelines and docs/DESIGN.md for the current interface notes.

Roadmap

Available in v0.2.1

Planned

tool / file / MCP-call observability where local telemetry supports it
richer parser coverage diagnostics
exportable privacy-safe reports
optional local MCP interface if it materially improves the workflow
additional AI coding-agent adapters
stronger anomaly detection

No dates promised — contributions are welcome.

Why open source?

Usage visibility should not be a paid feature.

Ledger is free and open so anyone can inspect exactly what is parsed, how metrics are calculated, and what stays local. If the underlying Codex format changes, the community can fix the adapter without waiting for a black box service.

License

If Ledger makes your Codex usage easier to understand, a ⭐ helps more people find it.

Name		Name	Last commit message	Last commit date
.agents/plugins		.agents/plugins
.codex-plugin		.codex-plugin
.github		.github
assets		assets
docs		docs
scripts		scripts
skills/ledger-analysis		skills/ledger-analysis
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
README.zh-CN.md		README.zh-CN.md
SECURITY.md		SECURITY.md
app.css		app.css
app.js		app.js
index.html		index.html
plugin.json		plugin.json
quota-snapshot.example.js		quota-snapshot.example.js
quota-snapshot.example.json		quota-snapshot.example.json

Navigation Menu

Repository files navigation

Know where your Codex usage goes.

See it in 30 seconds

Why Ledger?

What Ledger shows you

Understand your usage

See where it goes

Understand sessions

Spot changes

Install as a Codex Plugin · recommended

1. Add the GitHub marketplace

2. Install Ledger for Codex

3. Ask Codex

Update Ledger

If you installed Ledger as a Codex Plugin

If you cloned the repository directly

Run locally

Using Ledger

Dashboard

From Codex

How it works

Privacy

Your usage data should stay yours.

Data coverage & limitations

Plugin package

Development

Roadmap

Available in v0.2.1

Planned

Why open source?

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Know where your Codex usage goes.

See it in 30 seconds

Why Ledger?

What Ledger shows you

Understand your usage

See where it goes

Understand sessions

Spot changes

Install as a Codex Plugin · recommended

1. Add the GitHub marketplace

2. Install Ledger for Codex

3. Ask Codex

Update Ledger

If you installed Ledger as a Codex Plugin

If you cloned the repository directly

Run locally

Using Ledger

Dashboard

From Codex

How it works

Privacy

Your usage data should stay yours.

Data coverage & limitations

Plugin package

Development

Roadmap

Available in v0.2.1

Planned

Why open source?

License

About

Topics

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages