Monitor open Codex processes, set weekly usage cutoffs, and track AI coding token usage in one desktop dashboard. Reserve part of your Codex allowance with a limit such as 95% used, and switch to a separate limit such as 5% after a reset. Track estimated costs for Codex CLI, Claude Code, Gemini CLI and other tools, with optional private GitHub sync across computers.
The Codex usage tracker works on its own. Tracking other tools requires the separate Splitrail collector. GitHub sign-in is only needed if you enable device sync.
Download the app · Install guide · Codex quota cutoffs · Connect devices · Privacy
1.2.3 fixes collector discovery and All tools sync, adds GPT-6.1 Sol pricing and checks the shared price catalogue automatically. It includes the dedicated Limits page and reset protection.
| What you want | What you need |
|---|---|
| Codex CLI token usage and cost estimates | The desktop app and existing local Codex logs. No Splitrail collector required. Codex-authenticated Pi logs are also supported. |
| Claude Code, Gemini CLI and other supported tools | Splitrail 3.9.1 or newer, available on your PATH. Supported sources depend on the collector. |
| Combined usage across computers | Optional GitHub CLI sign-in and a private repository you control. Each device chooses All tools or Codex as its source. |
| Codex quota display | Optional quota-axi; missing quota tools do not block token tracking or sync. Quota details. |
| Open Codex CLI / app-server processes | Built-in local process monitor: PID, start time, executable, working directory and OS status. |
| Codex weekly quota cutoff and reset protection | Fresh weekly data from quota-axi, selected local Codex processes, and an explicitly armed cutoff. Keep Splitrail open. |
Built with Python and Qt Quick, with soft Pearl and Nord themes. No web server or telemetry. Costs are estimates, not provider bills or subscription charges. Prices are bundled and cached locally; automatic daily checks of the public GitHub catalogue add models without an app update. Custom rates take priority. Turn these checks off under Settings → Model pricing for offline pricing.
Choose your platform on the latest release. Native downloads include Python and dependencies.
| Platform | Download | Open |
|---|---|---|
| Windows 10/11, Intel/AMD 64-bit | splitrail-desktop-windows-x86_64.zip |
Extract All, open the Splitrail folder, double-click Splitrail.exe. |
| macOS 14+, Apple silicon | splitrail-desktop-macos-arm64.zip |
Unzip, drag Splitrail.app to Applications, then open it. |
| Linux, Intel/AMD 64-bit | splitrail-desktop-linux-x86_64.tar.gz |
Extract, then run ./Splitrail/Splitrail. Ubuntu 22.04+ or compatible. |
Keep the extracted folder together. These community builds are unsigned and the Mac app is not notarized; the install guide explains first-open prompts, checksums and Linux libraries. It also provides exact Python installation commands for all three operating systems using the small source-only .pyz, including an Intel Mac option.
First launch shows only the guided setup. Choose Get started to connect devices, or Use on this device to go straight to the dashboard. GitHub is optional and can be connected later in Settings.
- For Codex, choose Settings → Usage & data → Codex. The app reads existing local usage logs.
- For multiple AI coding tools, install the Splitrail collector, then choose Settings → Usage & data → This device or All devices.
- Use Settings → Model pricing → Manage prices to inspect or override rates.
- Change between the light Pearl and dark Nord themes in Settings.
The app defaults to All devices when it finds the collector, otherwise Codex. The All devices label does not enable network sync by itself.
Select Today, Week, Month, Year or All time directly above the dashboard. The arrows (or Alt+Left/Right) cycle through these five presets and wrap at either end. Use the calendar button for a custom range. Today and other single-day ranges show tokens and costs by hour; longer ranges show daily or grouped trends. Models, Tools and History offer searchable tables. Detailed token totals are under Models; pricing and refresh issues are in the notification bell.
./Splitrail/Splitrail --demoOn Windows run .\Splitrail\Splitrail.exe --demo; on macOS run /Applications/Splitrail.app/Contents/MacOS/Splitrail --demo. For the Python download, add --demo to your usual launch command. Demo mode uses synthetic data, does not read usage logs and cannot connect or sync.
See the dark theme and first-run screen
Open Limits in the sidebar. Hover over an ⓘ icon for details; keyboard focus works too. Quota remains a separate page for allowance and reset information.
- Select the Codex engines to protect under Processes.
- Set Stop at, for example 95%. A reading at or above 95% triggers the cutoff, including 96% or 97%.
- Set After reset, for example 5% of the fresh allowance.
- Choose Include new processes if wanted, then Enable cutoff. Disable it before changing limits or restarting blocked processes.
The cutoff starts off on each app launch. Percentages are remembered locally. A detected usage decrease or changed weekly reset window activates the reset limit, which stays in force until disarmed. Once a cutoff triggers, it stays blocked; a later reset does not silently restart work. Splitrail never redeems your banked reset credits.
This is a best-effort local cutoff, not a provider-enforced spending cap. Quota checks run once per minute, and reporting delays or requests already in flight can exceed your chosen percentage. Leave headroom. If fresh quota is unavailable for two minutes, the guard stops protected processes. An app server can contain several conversations, all of which may be interrupted. The process list cannot reliably tell which chat is generating. Only the quota tool's account is measured; processes cannot automatically be matched to accounts. Cloud tasks, other computers, inaccessible processes and independent tool commands are outside the cutoff.
Process scans run every ten seconds only while the Limits page is visible or the guard is armed. They inspect process metadata without reading session histories or continuously sampling CPU usage. Closing Splitrail disables protection. Detection, stopping and platform details.
Local tracking works without GitHub. To combine usage from your own computers:
- Install GitHub CLI on each device.
- Choose Get started during setup, or Settings → GitHub sync → Connect. Continue with the detected account, or choose Sign in with GitHub. Open GitHub and enter the one-time code shown in the app.
- On the first device, choose Create new and name your private repository, such as
splitrail-usage. On additional devices, choose Use existing and enter the sameowner/repository. - Choose whether to sync automatically, then select Enable private sync. This is the explicit step that creates/connects the private repository and enables sharing. Automatic sync is off by default.
- Open the dashboard. Choose Settings → GitHub sync → Sync now for a manual transfer. Under Options, select All tools (requires Splitrail) or Codex as this device's source.
Only daily and hourly usage totals, estimated costs, dates and approved tool/model identifiers are synced. Prompts, responses, credentials, local paths and account/quota data are excluded. A private GitHub repository is access controlled, not end-to-end encrypted. See Privacy and the sync reference.
Avoid double counting: keep each computer's source logs separate. Aggregate sync cannot deduplicate the same logs copied to two computers. Do not manually import the same usage you already sync.
Download only under Settings → GitHub sync → Options lets a computer view remote totals without uploading its own. Disconnecting stops sync and removes downloaded totals locally; it does not delete local logs or your private repository. Automatic refresh and sync require the app to remain open.
| Problem | What to check |
|---|---|
No module named PySide6, ijson or psutil |
Use a native download, or follow the Python install instructions with the same environment for installation and launch. |
| Qt plugin or DLL fails to load on Windows | Update to 1.1.2 or newer, which registers Qt's DLL directory before loading QML. Extract the entire native ZIP; do not move just the executable. |
| No usage appears | Select the correct source in Settings → Usage & data and confirm the source tool has local logs. For tools other than Codex, install Splitrail 3.9.1+ and make sure splitrail --version works. |
| Collector is not found | Check PATH or set SPLITRAIL_BIN to its executable. The built-in Codex reader can still work without it. |
| Sync says “Could not verify Splitrail version” even with the collector installed | Update the GUI to 1.2.3+. Windows could select the GUI's own Splitrail.exe from its launch folder; discovery now searches PATH explicitly and skips the GUI. SPLITRAIL_BIN must point to the separate collector. Version banners on stderr or with colour formatting are supported. Native Linux launches also restore the system library environment for external tools. |
| A model has no cost estimate | Open Notifications, then add a rate under Settings → Model pricing → Manage prices. Tokens remain visible for unknown models. |
| An estimate differs from your bill | Estimates depend on saved usage and configured prices. They cannot reconstruct subscription charges, all service tiers or every billing surcharge. Pricing details. |
| GitHub sync fails | Confirm GitHub CLI is signed in (gh auth status), check repository access and ensure the repository is private. The last successfully downloaded totals are retained after a failed sync. |
| Sync reports “Unable to sync” with local usage available | Update to 1.1.4 or newer. Inconsistent optional hourly reasoning counts could block the entire sync; the app now preserves daily and model totals, omits the invalid hourly detail, and explains chart coverage gaps. Local validation failures also report a specific error. |
| Sync says the Splitrail collector was not found | All tools sync needs the separate collector even if the dashboard is showing Codex. Install Splitrail 3.9.1+, or select Settings → GitHub sync → Options → Share from this device → Codex. Version 1.1.3 reports this cause instead of the generic “Unable to sync” error. On Windows, the app also discovers tools in %USERPROFILE%\.local\bin, %USERPROFILE%\.cargo\bin and %APPDATA%\npm. |
| Linux desktop launch cannot find installed tools | The app also checks ~/.local/bin, ~/.cargo/bin, ~/.npm-global/bin and /usr/local/bin, even when the desktop session has an older PATH. Existing PATH entries keep priority. Custom install locations must be on the desktop's PATH; you can also set SPLITRAIL_BIN to the collector executable. |
| Codex quotas are unavailable | Quota monitoring uses optional tools with their own authentication. It is separate from usage tracking. Setup details. |
| Cannot arm a cutoff | Refresh quota successfully first. The weekly reading needs a recent source timestamp and a future reset time. Select a process or enable protection for newly opened processes. Demo mode cannot arm cutoffs. |
| Codex closes after reaching a limit | Open Limits, hover over the status ⓘ for the reason, then Disable cutoff before restarting. A still-enabled, triggered guard also stops new engines when that option is enabled. |
For bug reports, include your OS, Python version, app version and the error message. Do not attach raw session logs, credentials or real-account screenshots. See Privacy.
- Manual Codex export/import: use Settings → Usage & data → Export / Import, without GitHub. Export format and deduplication.
- Custom model prices: local rate overrides and details about cached/reasoning tokens. Pricing reference.
- CLI commands: export, import, configure sync and sync once from a terminal. Command-line reference.
- Data locations and refresh behavior: settings files, log discovery, privacy boundaries and device limits. Reference guide.
git clone https://github.com/eddieyzhan/Splitrail-Desktop-GUI.git
cd Splitrail-Desktop-GUI
python3 -m venv .venv
source .venv/bin/activate
python -m pip install '.[test]'
splitrail-desktopThe source install includes PySide6, ijson, psutil and the QML interface resources. After activating the environment, run the tests and build the downloadable app:
PYTHONPATH=src python3 -m unittest discover -s tests -v
python3 scripts/build.py
python3 dist/splitrail-desktop.pyz --self-check
python3 dist/splitrail-desktop.pyz --smoke-uiOn Windows PowerShell use $env:PYTHONPATH='src'; python -m unittest discover -s tests -v. The test extra supplies timezone data for Windows. UI tests use the native display on Windows/macOS and the offscreen Qt platform on headless Linux. Use a real display or Xvfb for visual smoke checks. Add --onboarding to preview setup, or --demo --onboarding for an isolated preview. Tests use synthetic data and an in-memory GitHub service; they do not upload real usage. See the source layout.
To build a native archive on the target OS, install scripts/requirements-release.txt, then run python scripts/build_native.py. It bundles allowlisted application resources and the required Qt Quick modules, then tests both packaged screens using synthetic data before creating an archive. codemagic.yaml provides a manual-only macOS check with a 15-minute timeout; it has no automatic triggers or publishing secrets. Use a single run for a release after local checks pass.
The Native release checks GitHub Actions workflow can also be run manually after local checks pass. Select a single platform to avoid repeating builds already verified locally, or choose all for a full release. It uses pinned release dependencies and checks the native collector/sync path as well as the UI. It has no push/tag/PR triggers or publishing credentials; artifacts expire after three days and are published separately after review.
Application code is licensed under MIT. Native downloads include Python, PySide6/Qt and ijson with third-party notices; the .pyz contains only application code and resources. Splitrail Desktop is an independent interface for Splitrail, not affiliated with AI model providers or GitHub.