Local-first AI usage tracker

Token Tollbooth

Every AI prompt pays a toll. Token Tollbooth shows the meter.

See the meter. Know when to switch. Hand off in one click.

Context-window fill, usage limits and reset times for Claude, Codex, Cursor, Antigravity and more, and a ready-to-paste handoff to a fresh agent when a chat gets too full. It runs on your computer: no accounts, no telemetry.

Coming soon to GitHub How it works

Free and MIT-licensed. First public release coming soon.

Try the meter

Drag the sliders. Watch the city.

This is one toll booth from the desktop bar, with sample numbers. Push a limit up and the light changes, more windows light up, and at 100% the booth locks: the light turns red, the boom gate drops and the dial goes purple until the reset. Fill the context past 75% and the gate drops too: time to hand off to a fresh chat. The city at the top of the page follows along.

Claude Code sample

Running tests

ctx 38% · max 46%

38% CTX
Context
46% 5H
5-hour
31% WK
Weekly

RESETS

  • 5h46%—
  • Wk31%—

Light: Green, all clear.

38%
46%
31%
your clock
The AI tool is…

Handoff sample

From Claude Code · context 84% full

Subject line

Billing API — Add retries to the invoice sync · High · claude-sonnet-5-5 · Nov 18

Recommended setup for the next chat

Set model claude-sonnet-5-5, mode Plan, speed High → paste this handoff

Goal
Invoice sync retries failed webhooks up to 3 times.
Decided
Exponential backoff; no new dependencies.
Changed
sync/invoices.py, tests/test_sync.py
Next
Make the timeout test pass, then update the changelog.

In the real app you review and edit every field first, it is saved and checked on your computer, and then Looks right: save and copy puts it on your clipboard.

How it works

Watch, get warned, hand off

  1. Watch the meter

    Start the dashboard with one Python command, or add the desktop bar on Omarchy. Every chat gets a context gauge, and every tool shows its 5-hour and weekly limits with the time each one resets.

  2. Get warned before the chat bloats

    Green, then amber, then red. At 75% full (you choose the line) the gauge flashes START A NEW CHAT, and a limit near its cap turns the light red before you hit the wall.

  3. Hand off in one click

    Press New chat and get a ready-to-paste handoff: the goal, decisions and next step, plus which model, mode and speed to use. Paste it into a fresh chat, in the same agent or another, and keep going.

Hand off between agents

New chat, paste this, keep going

A chat that is too full costs more with every message. Token Tollbooth turns it into a short, reviewed handoff you paste into a fresh chat, in the same agent or a different one.

  • One button on every gauge and chat card. When a chat crosses the red line, the gauge flashes START A NEW CHAT with New chat and Keep going.
  • A subject line the new chat can name itself from: Project — what it's working on · Speed · model · date, editable, plus Copy chat name for renaming by hand.
  • Setup advice for the next agent. It suggests the model, mode and speed together (“set model X, mode Y, speed Z → paste this handoff”) with Copy full setup. Rule-based: nothing is fetched, and it never changes a setting in any app.
  • Across agents. Hand off from Claude Code to Codex, Cursor, Ollama and others. Model lists per agent start from a built-in list and grow from what it sees on your computer.
  • You stay in charge. Edit the goal, decisions, constraints, changed files, evidence and next action. It is saved and read back on your computer before copy is enabled, and you can download it as Markdown.

Token Tollbooth makes no AI call itself. If you ask the current chat to write the summary, that chat spends its own tokens answering. A shorter handoff can carry less context into the new chat, but no specific savings are promised.

Handoff sample

From Claude Code · context 82% full

Subject line

Billing API — Add retries to the invoice sync · High · claude-sonnet-5-5 · Nov 18

Next agent

Claude CodeCodex CLICursorOllama

Set model claude-sonnet-5-5, mode Plan, speed High → paste this handoff

Goal
Invoice sync retries failed webhooks up to 3 times.
Next
Make the timeout test pass, then update the changelog.
A sample handoff card. Yours is filled from your own chat, on your computer.

Features

Two parts, one repo

A dashboard that runs anywhere Python does, and a native desktop bar for Omarchy.

Dashboard

LinuxWindows (coming soon)macOS (untested)

  • Context speedometers, one per chat, with green, yellow and red zones. At 75% full (you can change it) the gauge flashes START A NEW CHAT.
  • “Why is this chat using so many tokens?” A plain breakdown: files, the same files read again, conversation and empty space.
  • Allowance strip with each 5-hour, daily or weekly window, remaining percentage, reset countdown and an early warning when you are burning through it fast.
  • Ready-to-paste handoffs with setup advice for the next agent: new chat, paste this, keep going. How handoffs work.
  • Tokens and estimated dollars per chat and per task, at API list prices.
  • Opt-in live feeds for Claude Code and Codex CLI, plus API spend reports with your own admin key.
  • Logbook, speed tags, and a watch on the Markdown files your chats keep re-reading.
  • Python standard library only, no packages. Opens at 127.0.0.1:8937.

Omarchy desktop bar

OmarchyHyprlandQuickshell

  • A toll booth for each AI tool: Claude, Codex, Cursor, Antigravity and more, apps and command-line tools alike.
  • Dials for context, the 5-hour limit and the weekly limit, with a red, amber or green traffic light.
  • Purple LOCKED · until Mon 3 AM when an allowance is used up, and a RESETS schedule for every limit.
  • Live status such as “Thinking…”, “Running tests” or “Waiting for your approval”.
  • A living night city behind each booth: windows flicker, car lights travel the road, traffic follows whether the tool is working, idle or off, more windows light up as usage grows, and the city goes into a purple blackout when the allowance is spent. The sky warms at dusk and dawn, and the moon crosses the sky.
  • Usage numbers come from ai-usagebar by AkitaOnRails (MIT). Thank you.

Private by design

Your usage stays on your machine

Token Tollbooth has no server, no account and no telemetry. There is nothing to sign up for, and nothing is sent to us.

  • Local only

    The dashboard listens on 127.0.0.1, so only your own computer can open it. Settings and saved handoffs live in a folder next to the app.

  • Reads as little as it can

    To show “Thinking…” or “Running tests”, the desktop bar reads local session files for timestamps, tool names, file names and the first word of commands. Chat text is never read out.

  • Opt-in, and you can see where it goes

    Live feeds are off until you turn them on. The only network requests are the ones that fetch your own usage straight from your AI providers: the bar's percentages through ai-usagebar, and the dashboard's optional API spend report.

  • Open source

    MIT-licensed. Read every line before you run it once the repository is public.

Install

Coming soon

The repository is being prepared for its first public release. Until then, here is what getting started will look like.

Dashboard

Needs Python 3.10 or newer. Nothing else to install, no API key.

# preview: available with the first release
git clone https://github.com/TokenTollbooth/tokentollbooth
cd tokentollbooth
python3 token_tollbooth.py
# then open http://127.0.0.1:8937

Starts with clearly labelled sample data. Windows support is coming soon.

Omarchy desktop bar

The bar lives in the omarchy-plugin/ folder of the same repository. It needs Omarchy (Hyprland and Quickshell), Python 3 and ai-usagebar for the usage numbers.

Step-by-step install instructions arrive with the release.

The code opens on GitHub with the first public release, coming soon.

FAQ

Questions

Why is my dial purple?

Purple means locked: that allowance, for example your weekly limit, is used up. Nothing is broken. The provider will not take more work on that plan until the window resets, and the badge tells you when, for example LOCKED · until Mon 3 AM. The light turns a steady red and the boom gate comes down, and on the desktop bar the city behind the booth goes into a purple blackout until then. (A blinking red light means a Token Tollbooth alert instead.)

Does it send my data anywhere?

Not to us: there is no server, account or telemetry. Everything is processed on your computer. The only outgoing requests fetch your own usage from your own AI providers (the bar's percentages through ai-usagebar, and the dashboard's optional API spend report, which is off unless you add an admin key).

Which AI tools does it support?

The desktop bar has booths for Claude (desktop app and Claude Code), Codex (desktop app and CLI), Cursor CLI and Antigravity CLI, plus other providers ai-usagebar knows about. The dashboard has live feeds for Claude Code and Codex CLI, API spend for Anthropic and OpenAI, and can import counters from any tool as JSON.

How do handoffs work, and does it call an AI?

When a chat gets too full, press New chat (or the handoff button on any gauge or chat card). With live feeds on, Token Tollbooth builds a draft from the local log: your last few messages, the AI's last reply, the folder, the files read and how full the chat was, kept in memory with key-like strings removed. Without live feeds, it gives you a short request to paste into the current chat, and you paste the reply back. Either way you review and edit the goal, decisions, constraints, changed files and next action, it suggests a model, mode and speed for the next agent, and Looks right: save and copy saves it locally and copies it.

Token Tollbooth itself never calls an AI. If you ask the current chat for the summary, that chat spends its own tokens answering. A shorter handoff may carry less context, but no specific savings are guaranteed.

What is the “toll”?

Every message you send re-sends the whole conversation so far. The fuller a chat's context window, the more each prompt costs in tokens and allowance. Token Tollbooth shows how full each chat is and, when it is time, hands you a short summary to paste into a fresh chat.

Does it work on Windows or macOS?

Linux today. Windows support is being finished and is coming soon. macOS will probably work but is not confirmed yet. The desktop bar is for Omarchy only.

Is it made by Anthropic, OpenAI, Cursor or Google?

No. Token Tollbooth is an independent project by Waffle Iron Labs and is not affiliated with Anthropic, OpenAI, Anysphere or Google. Product names are used only to say which tools it works with.

What does it cost?

Nothing. It is free, MIT-licensed software.