codexwatch

codexwatch shows where your OpenAI Codex usage goes: tokens and their API-equivalent cost per day, project, model, session and tool, your plan's 5-hour and weekly limits as they stand now, and what each percent of those limits cost you. By default it reads only the session logs Codex already writes on your machine, never opens your login, and makes no network request; fetching prices and refreshing codexhop accounts are things you ask for.

pipx install codexwatch-cli  # or: pip install --user codexwatch-cli

codexwatch # the overview in your terminal codexwatch dashboard # the web dashboard

You need nothing beyond the Codex logs already on this machine, so the first command already has your numbers. On Linux, ./install.sh --tray --desktop from a clone also adds an app-menu entry, a desktop shortcut and the tray.

What it does differently

Every response is counted once

Codex gives each model response an id. codexwatch keys every row on it, so a forked session that copies its parent's history, a subagent, a repeated token event or the same logs synced from another machine never add tokens twice. Those are the four ways Codex usage has been overcounted, and each one has a test that reproduces it.

Your plan limits come from your own logs

After every response Codex writes the plan's rate-limit reading into the session log: how full the 5-hour and weekly windows are and when they reset. codexwatch reads those, so the live figures need no network call and no login.

Quota forensics

Because each reading follows a known response, codexwatch can set the tokens spent in a window against how far the window moved. You get an exchange rate (dollars of API usage per percent of your plan, per window and per day) and a flag on any rise your local logs do not account for, such as usage from another machine or from ChatGPT itself.

Fast on large logs

Lines are filtered on their first bytes, so tool output and reasoning text are never decoded, and a growing session is read from where the last scan stopped. On the machine it was built on, 1.85 GB of logs in 59 sessions took about 2 seconds to scan the first time (measured, 2026-11-04); later scans read only new lines.

Prices you can check

Every bundled price was copied from OpenAI's pricing pages, with the date and the page. A model with no published price is shown as unpriced and left out of dollar totals, never counted as $0. Fast mode is priced at the Fast tier, and prompts over 272K tokens at the long-context rate.

The dashboard

codexwatch dashboard opens a page on 127.0.0.1. It works offline, follows your system's light or dark setting, and refreshes as you work.

The top of the page is your plan: both windows with their reset times, the burn rate over the last hour, the time the window fills at that pace, and what you have spent since it reset. The red band below compares the last 30 days of usage with what your plan costs. After that come the totals for the period you pick, a daily chart, models and projects, quota forensics, recent sessions, a weekday-by-hour map, tool calls, and how your work ran (CLI, IDE or codex exec, Standard or Fast, main sessions or subagents).

Light theme and phone

Share card

codexwatch card writes a 1200 × 630 image of your month, and the dashboard's Share card button saves it as SVG or PNG. It leads with what your plan returned. Project names stay off the card unless you pass --projects, because a project name can be a client's name.

Plan prices come from OpenAI's Codex pricing page. Enterprise and Edu have no public price, so set yours with codexwatch config set plan_price 60.

In your menu bar, tray, status bar and prompt

codexwatch bar -f FORMAT prints one line, or a small menu, in the shape each bar expects. It reads only new log lines, so calling it every few seconds is cheap.

Desktop notifications fire as a window passes 75%, 90% and 100%, once each per window. The tray sends them, or run codexwatch notify from a timer.

Ask about it from Codex or Claude

codexwatch mcp is an MCP server, so an agent can check your usage mid-session:

codex mcp add codexwatch -- codexwatch mcp     # OpenAI Codex

claude mcp add codexwatch -- codexwatch mcp # Claude Code

Then ask "how much of my 5-hour window is left?" or "what did this week cost?". The tools are usage_summary, plan_limits, quota_forensics, sessions, daily and budget_status. The server is in the official MCP Registry as io.github.psychofict/codexwatch.

Several ChatGPT accounts

codexhop keeps several ChatGPT logins for Codex and switches between them. When it is installed, codexwatch shows every account's latest reading and the one with the most room, names the account behind each plan window in the quota report, and codexwatch limits --refresh asks codexhop for fresh readings of all of them. codexwatch itself never opens a login file; it runs codexhop for anything that needs one.

codexwatch autohop moves Codex to another of your saved accounts when the live one is nearly spent. It is for accounts that are yours, such as a personal plan and your own seat in a company workspace, never a login someone shared with you; each account keeps its own limits, and OpenAI's terms of use apply to each one. It is off until you run it, and without --apply it only says what it would do:

$ codexwatch autohop

15:41:56 stay work is at 31% of its 5-hour window and 29% weekly; below 92% / 97%, so stay

With --apply it hops when the live account reaches 92% of its 5-hour window or 97% of its week, only to an account with at least 25% of its 5-hour window free, and at most once every 20 minutes. Every number can be changed in the autohop block of config.json. extras/systemd runs it every 3 minutes, and creating a file called autohop.off in the codexwatch folder stops it.

Budgets

codexwatch budget add --name "Monthly" --usd 300 --every month

codexwatch budget add --name "atlas daily" --usd 20 --every day --scope project:atlas-api codexwatch budget add --name "5h headroom" --pct 80 --window 5h codexwatch budget list

A dollar or token budget adds up API-equivalent usage over the local calendar day, week (from Monday) or month, for everything or one project or model. A percent budget watches the plan's own window. Each sends a notification at 80% of its limit (--notify-pct) and again when it is spent. codexwatch budget check exits 1 when any budget is over, for scripts and CI.

Several machines

Copy or sync another machine's ~/.codex (or just its sessions folder) somewhere and add it:

codexwatch sources add ~/sync/laptop-codex --machine laptop

codexwatch machines

Responses that appear in both places are counted once, by their response id.

Commands

Every report takes -p/--period (today, 7d, 30d, week, month, year, all, 2026-10, 2026-10-31), --since and --until, filters (--project, --model, --client, --machine, --account) and --json.

| scan | Read new log lin