io.github.psychofictPublished by GitHub account psychofictv1.0.2Updated Nov 5, 2026
OpenAI Codex usage from your local logs: tokens, API-equivalent cost and plan limits.
Reads local OpenAI Codex session logs to report token usage, API-equivalent cost, plan limits and budgets to an assistant.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Follow the launch instructions in the repository.
[codexwatch: every Codex token, counted once]
[PyPI version] [CI] [MIT licence] [Python 3.9 or newer] [No dependencies]
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.
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.
[codexwatch in a terminal: plan limits, totals, a 30-day strip, top models and projects]
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.
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.
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.
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.
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.
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 dashboard: 5-hour and weekly windows, codexhop accounts and the plan-value band]
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).
[Quota forensics: dollars per percent of the weekly window, and a rise the logs cannot explain]
[The dashboard in the light theme] [The dashboard at phone width]
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.
[A share card: plan value, totals, top model and a 30-day strip]
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.
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.
codexwatch mcp is an MCP server, so an agent can check your usage mid-session:
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.
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 switches accounts before the live one runs out. It is off until you run it, and without --apply it only says what it would do:
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.
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.
Copy or sync another machine's ~/.codex (or just its sessions folder) somewhere and add it:
Responses that appear in both places are counted once, by their response id.
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.
Dollar figures are what the same tokens would cost on the OpenAI API at the published Standard price. ChatGPT plans bill a flat fee, so treat them as a measure of how much you used, not a bill. Input tokens include cached and cache-written tokens, and output tokens include reasoning, as in OpenAI's usage object.
The plan figures come from the readings in your logs, so they are as fresh as your last Codex request on this machine. Usage on another machine, in ChatGPT or in cloud tasks counts against the same plan but reaches these logs only with your next request here; that is what the quota report's "rises these logs cannot explain" catches. Fast mode spends plan limits at 2.5 times the Standard rate, and the quota report weights it that way.
docs/how-it-works.md covers the log format, every counting rule and the forensics in detail.
The bundled list covers the models Codex has used, from gpt-5 and o3 to gpt-6-astra, as of 2026-11-04. codexwatch prices lists them with their source. To change one, put it in prices.json in the codexwatch folder (codexwatch prices path):
Prices are USD per million tokens. codexwatch prices update downloads LiteLLM's list to fill gaps; your own file still wins, and codexwatch reprice re-costs your history after any change.
codexwatch reads ~/.codex/sessions (and archived_sessions) and writes only to its own folder: ~/.config/codexwatch on Linux, ~/Library/Application Support/codexwatch on macOS, %APPDATA%\codexwatch on Windows. It makes no network request unless you run prices update, or ask codexhop for readings with limits --refresh, the dashboard's button or autohop. The dashboard listens on 127.0.0.1 only and answers data requests only from its own page, with a token a web page elsewhere cannot read. SECURITY.md has the details.
Python 3.9 or newer; no packages beyond the standard library.
Why is the package called codexwatch-cli? PyPI treats codexwatch as the same name as an unrelated project called codex-watch, so the package carries a suffix. The command is codexwatch, and codexwatch-cli works too. To run it once without installing: uvx codexwatch-cli.
Why do my dollar figures differ from another tool's? Most often because that tool counted forked sessions, subagents or repeated events twice, priced fast mode at the Standard rate, or treated a model with no price as $0. codexwatch doctor lists unpriced models, and export gives you every response to check against.
Does it work with Codex in VS Code, codex exec and the desktop app? Yes, they all write the same logs; codexwatch clients splits usage by where it ran. Codex cloud tasks do not write local logs, so they appear only through their effect on your plan windows.
I use an API key, not a ChatGPT plan. Then there are no plan windows, and the dollar figures are close to your actual bill.
Can I try it without Codex logs? codexwatch demo opens the dashboard on two months of invented usage, kept apart from your real history.
Issues and pull requests are welcome. CONTRIBUTING.md explains how to run the tests (python -m pytest) and how to add a log format or a price.
codexwatch is built by Ebenworks, which also makes codexhop and claudehop, and, with Statotech Systems, the Claude Usage Widget & Token Tracker. The dashboard uses the Geist fonts under the SIL Open Font License.
MIT licence. Not affiliated with, endorsed by, or sponsored by OpenAI. "OpenAI", "Codex" and "ChatGPT" are trademarks of OpenAI, used here only to say what this works with.
Source: README.md at commit fd1380e
Codex token usage and its API-equivalent dollar value for a period: totals, cache hit rate, and the top models and projects. Dollar figures are estimates at OpenAI API prices; tokens of models with no published price are counted separately.
periodWhere the ChatGPT plan's Codex limits stand now: each window's percent used, reset time, burn rate per hour and projected time it fills, read from the newest session log. With codexhop installed, also every saved account's last reading and the account with the most 5-hour room.
Takes no parameters.
What each percentage point of the plan cost in API-equivalent dollars and tokens, per window and per day, plus rises in a window that the local logs cannot explain (usage from another machine, ChatGPT itself or cloud tasks, or a metering change).
windowThe most recent Codex sessions with title, project, models, turns, tokens and dollar value.
limitTokens and API-equivalent dollars per local day, oldest first, with empty days included.
daysThe user's codexwatch budgets (dollar, token or plan-window caps) with how much of each is used and whether it is near or over its limit.
Takes no parameters.
90% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
pipx install codexwatch-cli # or: pip install --user codexwatch-clicodexwatch # the overview in your terminalcodexwatch dashboard # the web dashboardcodex mcp add codexwatch -- codexwatch mcp # OpenAI Codexclaude mcp add codexwatch -- codexwatch mcp # Claude Code$ codexwatch autohop15:41:56 stay work is at 31% of its 5-hour window and 29% weekly; below 92% / 97%, so staycodexwatch budget add --name "Monthly" --usd 300 --every monthcodexwatch budget add --name "atlas daily" --usd 20 --every day --scope project:atlas-apicodexwatch budget add --name "5h headroom" --pct 80 --window 5hcodexwatch budget listcodexwatch sources add ~/sync/laptop-codex --machine laptopcodexwatch machines{"models": {"gpt-6-astra": {"input": 10.0, "cached": 1.0, "cache_write": 12.5, "output": 50.0}}}