Tokex

Tokex is a native macOS menu bar app for tracking local Codex usage.

It reads Codex session logs from your Mac and reports token usage, sessions, requests, active time, and rate-limit data. No account connection, API key, or external service is required.

Features

• Input, cached input, output, and reasoning token usage
• Daily and seven-day summaries
• Session and request counts
• Active session duration
• Interactive usage and trend charts
• 18-week activity heatmap
• Native macOS desktop widgets for the current limit and seven-day trend
• Recent sessions, models, and projects
• One-click opening of verified local sessions in the Codex desktop app
• Rate-limit usage and reset time when present in Codex logs
• Automatic support for Codex ACP sessions started from Zed when they use the same CODEX_HOME
• Optional manual rolling 7-day budget
• Local notifications at a configurable usage threshold
• Configurable session directory and refresh interval
• Light and dark mode
• Reduce Motion, Reduce Transparency, and Increased Contrast support

Install

Tokex requires macOS 14 or later.

Download the latest DMG from GitHub Releases, open it, and drag Tokex.app to Applications.

Release builds are universal and run on Apple Silicon and Intel Macs. They are ad-hoc signed but not notarized by Apple. On first launch, macOS may block the app; open System Settings → Privacy & Security and select Open Anyway for Tokex.

Build from source

Building Tokex requires Swift 5.10 or later and Xcode 15.3 or compatible Command Line Tools.

sh scripts/build-app.sh
open dist/Tokex.app

Create a local DMG with:

sh scripts/package-dmg.sh
open dist/Tokex-*-macOS.dmg

Local builds use an ad-hoc signature and are intended for development. Tokex has no third-party runtime dependencies.

Install Apple's Command Line Tools if swift is not available:

xcode-select --install

Usage

Tokex runs as a menu bar app and does not appear in the Dock. Click its compact usage value in the menu bar to open the dashboard. Minimal mode shows only the remaining percentage; full mode adds today's compact token total on a second line.

To add a desktop widget, launch Tokex once, Control-click the desktop, choose Edit Widgets, search for Tokex, and add Codex Limit or Usage Trend. Widgets read a small aggregate snapshot from the local App Group container; they never scan Codex logs or make network requests themselves.

The default data source is:

~/.codex/sessions

If Tokex is launched with CODEX_HOME in its environment, it uses $CODEX_HOME/sessions. Codex External Agent sessions from Zed are included when they write to that same source. Zed's native Agent is a separate runtime and is not counted unless it produces Codex rollout logs.

The path can be changed in Tokex settings. Existing Codex sessions are required before usage data can be displayed.

On a Mac without Codex data, Tokex opens a setup screen automatically. Install Codex, complete at least one session, and select Check again. Tokex will also retry automatically at the configured refresh interval.

Tokex stores its normalized local history at:

~/Library/Application Support/Tokex/history-v1.json

The WidgetKit extension reads only its compact aggregate snapshot at:

~/Library/Group Containers/group.local.tokex.shared/widget-v1.json

Development

Run the app directly with Swift Package Manager:

swift run Tokex

Run the unit tests and deterministic parser checks:

sh scripts/test.sh

Verify fixtures and local Codex data, when available:

sh scripts/verify.sh

Build and verify the application bundle:

sh scripts/build-app.sh
codesign --verify --deep --strict dist/Tokex.app

The same checks run in GitHub Actions on pull requests and pushes to main.

Releases

Releases follow Semantic Versioning and are published from tags named vMAJOR.MINOR.PATCH.

To publish a release:

1. Update CFBundleShortVersionString and CFBundleVersion in Resources/Info.plist and Resources/TokexWidgets-Info.plist.
2. Commit and push the version change.
3. Create and push the matching tag:

git tag -a v0.9.0 -m "Tokex 0.9.0"
git push origin v0.9.0

The release workflow validates the tag against Info.plist, builds a universal app, creates a DMG, and publishes it with its SHA-256 checksum. See the release guide for details.

Data and privacy

Tokex processes data locally and does not make network requests.

It reads metadata and aggregate usage events from Codex rollout logs, including:

• session_meta
• task_started
• task_complete
• turn_context
• event_msg.token_count

Tokex does not read prompt or response contents, ~/.codex/history.jsonl, or ~/.codex/auth.json.

Data accuracy

• Token totals come from monotonic total_token_usage deltas, with last_token_usage used only for the first event or a cumulative-counter reset.
• Cached tokens are included in input; reasoning tokens are included in output.
• Limit percentage and reset time come directly from the newest current Codex rate-limit sample. After its reset boundary passes, Tokex waits for a new sample instead of assuming that 100% remains.
• Codex logs do not expose a reliable absolute allowance or subscription cost. Tokex leaves those values unavailable; a rolling seven-day budget can be configured manually.
• Codex ACP sessions created by Zed are included when they use the same rollout source. Zed's native Agent is a separate runtime and is not counted without Codex rollout data.

See SECURITY.md for the security policy.

Project structure

Sources/Tokex/          macOS app and SwiftUI interface
Sources/TokexCore/      log parsing, normalization, and local storage
Sources/TokexWidgetShared/ shared aggregate snapshot model
Sources/TokexWidgets/   WidgetKit extension
Tools/TokexVerifier/    deterministic and local-data verification
Resources/              application bundle metadata
scripts/                build and verification scripts
docs/                   architecture and release documentation
.github/workflows/      continuous integration

Additional documentation:

• Changelog
• Architecture
• Release process

Contributing

Contributions are welcome. Read CONTRIBUTING.md before opening a pull request.

Run the project checks before submitting changes:

sh scripts/test.sh
sh scripts/verify.sh
sh scripts/build-app.sh

Security issues should be reported according to SECURITY.md.

License

Tokex is available under the MIT License.