Codex Token Menubar

Local desktop token dashboard for Codex session usage.

It scans local Codex session logs under ~/.codex, indexes them into SQLite, and shows rolling usage windows in a lightweight tray/menu-bar panel without any model calls during normal use.

Highlights

• Rolling windows: 24h, 7d, 30d, and 累计
• Local-first: reads ~/.codex/sessions and ~/.codex/archived_sessions
• Fast refresh: incremental indexing into SQLite
• Compact display: Chinese 万 / 亿 formatting for large token counts
• Cross-platform UI: shared PySide6 tray app for macOS and Windows

Install

Run the app

python3 -m venv .venv
.venv/bin/python -m pip install -e .
source .venv/bin/activate

Set up a development environment

python3 -m venv .venv
.venv/bin/python -m pip install -e ".[dev]"
source .venv/bin/activate

The app reads local Codex data from ~/.codex by default. Override that root for testing with CODEX_HOME=/path/to/.codex.

Quick Start

Refresh the local index:

codex-token-menubar refresh --format json

Open the tray app:

codex-token-menubar-ui

Show CLI summaries:

codex-token-menubar summary --period today --format table
codex-token-menubar summary --period week --format json
codex-token-menubar summary --period month --format table
codex-token-menubar summary --period cumulative --format json
codex-token-menubar doctor --format json

Time Windows

• today = last 24 hours (24h)
• week = last 7 days (7d)
• month = last 30 days (30d)
• cumulative = all indexed history

Output Format

Table output uses compact Chinese token formatting:

• < 10,000 keeps the raw integer
• >= 10,000 uses 万
• >= 100,000,000 uses 亿

JSON output keeps raw integers for machine-readable workflows.

Packaging

Runtime and packaging icons live in src/codex_token_menubar/assets/icons/.

Regenerate icons:

.venv/bin/python scripts/generate_icons.py

Build a macOS app bundle:

./scripts/build_macos.sh

macOS build output:

dist/Codex Token Usage.app
dist/codex-token-menubar-macos.zip

Use the macOS app:

1. Open dist/
2. Double-click Codex Token Usage.app
3. If macOS blocks the app on first launch, right-click it and choose Open
4. After launch, click the menu-bar icon to view token summaries

For regular use, move Codex Token Usage.app into /Applications.

Build a Windows executable:

powershell -ExecutionPolicy Bypass -File .\scripts\build_windows.ps1

Windows build output:

dist\CodexTokenUsage\

Use the Windows app:

1. Open dist\CodexTokenUsage\
2. Double-click CodexTokenUsage.exe
3. After launch, click the tray icon to view token summaries

The Windows build is currently a portable app directory rather than a one-click installer.

Using The App

The desktop app reads local Codex data from ~/.codex by default, so it only needs access to your existing local Codex session logs.

Typical first-run flow:

1. Start the packaged app from dist/
2. Click the tray/menu-bar icon
3. Press Refresh to scan local session logs and update the SQLite index
4. Review the 24h, 7d, 30d, and 累计 cards in the panel

If you prefer the command line, you can refresh data before opening the app:

codex-token-menubar refresh --format json
codex-token-menubar-ui

If the packaged app launches but shows no data, first confirm that local Codex sessions exist under ~/.codex/sessions or ~/.codex/archived_sessions, then use the Refresh action in the panel.

Platform Notes

• macOS and Windows share the same tray/panel layout, icon family, and rolling-window summary semantics.
• macOS packaging uses the bundled .icns asset. Notarization is not included yet.
• Windows packaging uses the bundled .ico asset and the same PyInstaller entrypoint.
• The app assumes direct local filesystem access to Codex logs.

Known Limitation

当前 session statistics are intentionally deferred. v1 ships only stable time-based aggregates: 24h, 7d, 30d, and 累计.

License

MIT