TokenTick
A native macOS app and CLI for tracking Codex usage limits, token usage, estimated API costs, and local storage. A Codex-focused alternative to CodexBar and ccusage.
- Explore usage by day, task, project, and model.
- Monitor current limits and review completed weekly windows.
- Get system notifications when limits reset, with optional confetti or fireworks.
- Estimate when limits will run out or how much allowance will remain at reset, starting with the current cycle's average pace and adapting as new usage observations arrive.
- View available reset credits, their expiry dates, and the credits balance returned by Codex.
- Compare usage by model, usage mode, and reasoning effort.
- Inspect Codex disk usage by category and browse worktree and projectless task directories, with results updating during scans.
- Check recent activity from the menu bar.
- Export detailed usage as JSON with the CLI.
- Background CPU usage below 1%, with peak memory usage just one-fifth that of comparable tools.
- Account for Fast and long-context pricing, avoid double-counting cached input and reasoning output, and deduplicate inherited usage in forked tasks.
Requires macOS 26+ and Apple Silicon. Supports English and Simplified Chinese through macOS language settings. Costs are USD estimates based on public API prices, not subscription charges.
Screenshots
Screenshots use sample data.
Overview and limit forecasts
See current limits, estimated exhaustion or remaining allowance at reset, available resets, and credits alongside token usage and estimated costs.
Model usage and storage summary
Storage details
Usage details
Plan history
Menu bar
Installation
Download an archive from GitHub Releases. Verify it with the matching checksum file:
shasum -a 256 -c <archive-name>.zip.sha256
App
Extract the archive, move TokenTick.app to Applications, and open it. If macOS blocks the ad-hoc signed app, allow it in System Settings → Privacy & Security after confirming the download's source.
Update through Check for Updates… in the app menu or Settings → About.
CLI
In Settings → General → Command line, click Install CLI. TokenTick creates a symbolic link at /usr/local/bin/tokentick. Existing files or other links are not overwritten; the app reports conflicts and permission failures without requesting administrator access.
Keep TokenTick in Applications before installing the CLI. The linked CLI updates with the app. /usr/local/bin is on the default macOS shell PATH. If installation requires additional permissions, an administrator can create /usr/local/bin and install the link manually:
sudo mkdir -p /usr/local/bin
sudo ln -s /Applications/TokenTick.app/Contents/Helpers/tokentick /usr/local/bin/tokentick
For an independent installation, the full distribution also includes bin/tokentick and its required resource bundle. From the extracted directory:
mkdir -p "$HOME/.local/bin"
install -m 755 bin/tokentick "$HOME/.local/bin/tokentick"
ditto bin/TokenTick_TokenTickCore.bundle "$HOME/.local/bin/TokenTick_TokenTickCore.bundle"
Add $HOME/.local/bin to your PATH. This independent copy is updated manually and requires the resource bundle beside it.
Remote devices
Add devices in Settings → Remote Devices using an SSH address or Use Local Folder. Select the Codex data folder itself. Connections can be tested, synced, paused, edited, or removed individually. Remote collection is available in the app.
| Address | Meaning |
|---|
ssh://workstation | Use an existing SSH host alias and discover the Codex directory |
ssh://user@host:2222/home/user/.codex | Specify the user, port, and Codex directory |
ssh://workstation/D:/Users/user/.codex | Specify a Windows Codex directory |
SSH uses your existing system configuration. If the address has no path, TokenTick uses the remote CODEX_HOME or ~/.codex.
Overview groups usage across devices by account. Filter by account in Overview or by device in usage details. When removing a connection, choose whether to keep its collected history. Account limits and storage information remain specific to your local device.
CLI
tokentick sync --scope all
tokentick usage --group day --json
tokentick records --limit 100
tokentick current-limits
Run tokentick --help for filtering, pricing, and export options.
Diagnostics
The macOS app sends crash reports, sanitized operational errors, and session statistics to Sentry. An anonymous installation ID measures active installations and version adoption; it is not a Codex account or a count of people. Error reports include diagnostic messages and related file locations, with credential patterns redacted. Codex conversations, credentials, usage records, and full API responses are not intentionally collected. The CLI does not initialize Sentry.
Testing
Run swift test for Core tests. Set TOKENTICK_TEST_NODE to a Node.js executable with node:sqlite support to include the SQLite query contract tests; otherwise those tests are skipped. With Docker running, script/test_remote_ssh.sh tests incremental collection against an isolated SSH container using temporary keys. It does not use configured remote devices or modify your SSH configuration.
Documentation
