cc-cockpit

A Claude Code usage panel for Linux: a tray indicator with a consumption ring,
a local dashboard and a terminal summary.

Everything is read from what Claude Code already writes under ~/.claude — or
under each account's directory, if you run more than one. It makes no network
calls and sends nothing anywhere.

One exception is worth stating plainly: to tell you when your login expires it
opens .credentials.json and reads exactly two fields — the refresh-token
expiry and the plan name. The tokens sitting beside them are never read, never
stored and never printed. See cockpit/auth.py.

The interface follows your OS language — English, Portuguese and Spanish are
bundled — and can be pinned in the config file or with --lang.

What it shows

Usage is measured in API-equivalent USD: what those messages would cost on
the pay-as-you-go API. On a Pro/Max plan none of it is billed — the number works
as a weight unit for consumption and shows how much the plan returns.

The three surfaces

The tray menu is the glance. One section per account with its 5h and 7d
windows, then the day, the month, the sessions open, the ones you can resume and
today's projects. Every session line is a button: clicking it opens a terminal in
that directory resuming that conversation. Shown on the panel picks which
account the label speaks for.

A session line never opens a submenu, and that is not a style choice: on GNOME's
AppIndicator extension an item that carries an icon — every session line does,
for the state dot — exports its submenu correctly and then renders it empty. An
item without an icon submenus fine, which is why Recent sessions folds into a
dropdown and the open ones do not. The detail a session used to expand into —
directory, context window, requests, pid, memory — lives in the dashboard, which
has room for it.

It refreshes every twenty seconds without redrawing. The menu is exported over
dbusmenu and the panel draws it, so adding or removing an item tears the popup
down while you are reading it; a refresh that keeps the same shape only rewrites
the labels that actually changed.

The dashboard is the long look: gauges, sixty days of history, the last
twenty-four hours, projects, blocks, the token mix, models and effort. Open it
from the tray, or cc-cockpit serve --open. With more than one account it grows
a tab bar — one per account, plus All accounts.

Three cards fold: the official curve, the heatmap and the recent sessions. Each
viewer's choice is kept in their own browser, and the recent list ships folded —
it is the one you consult, not the one you watch.

Settings opens a real window rather than a submenu: a menu has nowhere to
type a number, and GNOME's appindicator extension flattens submenus to a single
level anyway. Four tabs — General, Accounts, Limits, Plan — each scrolling on
its own so nothing falls off a short screen, with Save always reachable below
them. Saving applies right away, without a restart.

Install

Debian / Ubuntu — the .deb pulls in the GTK dependencies by itself:

# from the latest release
sudo apt install ./cc-cockpit_0.5.2_all.deb
cc-cockpit setup
nohup cc-cockpit tray >/dev/null 2>&1 &   # tray now, without logging out

Arch — from the AUR:

yay -S cc-cockpit    # or paru, or makepkg -si
cc-cockpit setup
nohup cc-cockpit tray >/dev/null 2>&1 &   # tray now, without logging out

Any distribution — pipx, reusing the system GTK bindings:

sudo apt install python3-gi python3-cairo gir1.2-ayatanaappindicator3-0.1  # tray only
pipx install cc-cockpit --system-site-packages
cc-cockpit setup
nohup cc-cockpit tray >/dev/null 2>&1 &   # tray now, without logging out

--system-site-packages is what lets the virtualenv see PyGObject and pycairo.
Without them the tray is unavailable, and the dashboard and report still work.

From a checkout:

git clone https://github.com/wallacemartinss/cc-cockpit
cd cc-cockpit && ./install.sh
nohup cc-cockpit tray >/dev/null 2>&1 &   # tray now, without logging out

cc-cockpit setup registers the autostart entry, captures the statusline
(see below), checks the tray dependencies and runs the first collection.
cc-cockpit setup --remove undoes the autostart entry.

That autostart entry only fires on the next login, so the last line starts the
tray in the session you are already in — the icon shows up right away, with no
need to log out. It is the same command on every distribution, and it is only
needed once: from the next login on, autostart takes care of it. Running it
again is harmless — a second tray refuses to start and says which pid already
holds it.

cc-cockpit                 # tray + dashboard in the background
cc-cockpit report          # terminal summary
cc-cockpit serve --open    # dashboard only (http://127.0.0.1:8765)
cc-cockpit json            # everything as JSON, for scripting
cc-cockpit collect         # ingest new transcripts and exit
cc-cockpit config          # config path and contents
cc-cockpit accounts        # list the Claude Code accounts it reads
cc-cockpit --lang es report

Desktops

The indicator is a StatusNotifierItem, not a GNOME applet, so it shows up on any
panel that hosts one:

cc-cockpit setup prints what your desktop needs. GNOME is what this is
developed and tested on; the others follow from the protocol, not from separate
code paths. The dashboard and report depend on none of it.

More than one account

A company Claude Code in ~/.claude and a personal one in ~/.claude-pessoal
are two subscriptions, not two folders. Each has its own 5h and 7d windows,
so cc-cockpit keeps them apart everywhere: separate history, separate rate-limit
snapshot, separate calibration.

Accounts are not picked up on their own — a stray copy of a Claude Code
directory is not a second subscription, and adding it silently would be worse
than asking. What the tool does instead is say what it found: setup and the
Settings Accounts tab both list any directory that is not set up as an
account, next to the button that adds it.

cc-cockpit accounts --detect          # register what it found, and say where it looked
cc-cockpit accounts --primary empresa # whose number the tray label shows
cc-cockpit setup                      # re-registers the statusline in each one

Detection looks at ~/.claude*, ~/.config/claude*, $CLAUDE_CONFIG_DIR, and
that same variable inside any Claude Code running right now — which is how it
finds an account kept somewhere the globs would never reach. Anything else:
cc-cockpit accounts --add work=/path/to/its/dir, or Add directory… in the
Settings Accounts tab.

That last step is the one that matters. The statusline payload carries the
account's rate limits but nothing that identifies the account, so each
settings.json gets cc-cockpit statusline --account <id>. Without it,
whichever CLI renders last overwrites the other's percentage, and the tray
reports the wrong subscription with nothing on screen to reveal the swap.

What changes where

The tray label speaks for the primary account, and the ring takes the colour
of whichever account is worst off — a 95% on the one you are not watching
still turns the icon red. The menu gains one section per account and a Shown on
the panel submenu to switch between them.

The dashboard gains a tab per account, plus All accounts. That tab adds
up spend, tokens, projects and models, and deliberately shows one ring per
account instead of a combined percentage: two windows with different ceilings
and different resets have no meaningful sum.

Naming them

Detection names an account after its directory, so ~/.claude becomes
default — a poor label for what is usually the company account. There are two
different things to rename, and they carry different risk:

cc-cockpit accounts --label default=Empresa   # the name shown everywhere
cc-cockpit accounts --rename default=empresa  # the id, moving its history along

The name is editable in the Settings Accounts tab too. The id is not,
because it names accounts/<id>/, which holds months Claude Code has already
pruned; changing it has to move a directory, so it lives in --rename, which
also fixes up the statusline registrations.

By hand

Accounts live in the config file:

"accounts": [
  {"id": "empresa", "label": "Empresa", "dir": "~/.claude"},
  {"id": "pessoal", "label": "Pessoal", "dir": "~/.claude-pessoal"}
],
"primary_account": "empresa"

With nothing configured, everything behaves exactly as before, against
CLAUDE_CONFIG_DIR or ~/.claude. An existing history is moved into
~/.local/share/cc-cockpit/accounts/<id>/ the first time the new version runs.

Configuration

Everything the Settings window writes lives in ~/.config/cc-cockpit/config.json, and any key missing from
the file is written back on start, so new options show up there:

{
  "language": "auto",            // auto (follows the OS) | en | pt | es
  "block_hours": 5,
  "limits": { "block_usd": null, "week_usd": null },  // null = automatic
  "tray_metric": "block",        // block | week | today | none
  "tray_show_cost": true,
  "recent_sessions": 5,          // conversations offered for resuming; 0 turns the list off
  "menu_bar_style": "blocks",    // blocks | shade | fine | dots | squares |
                                 // line | braille | color_blocks | color_dots
  "refresh_seconds": 20,
  "plan_monthly_usd": null,      // e.g. 200 -> shows how many times the plan paid for itself
  "plan_name": "",
  "local_currency": null,        // e.g. {"code":"BRL","symbol":"R$","rate":5.4}
  "dashboard_port": 8765,
  "warn_pct": 70,
  "critical_pct": 90,
  "accounts": [],                // see "More than one account" above
  "primary_account": null        // null = the first one
}

The real numbers, from the statusline

Two things cannot be derived from local transcripts:

1. The limit belongs to the account, not to the CLI. Whatever you consume in
   the Claude app counts against the same window and leaves nothing on disk, so
   a window can start before your first local request.
2. The weekly limit is a fixed window with its own reset time, not the
   rolling 7 days a local reader would assume.

Claude Code pipes a JSON payload into the statusline command on every render,
and it carries exactly what the plan panel shows:

"rate_limits": {
  "five_hour": {"used_percentage": 23, "resets_at": 1788800000},
  "seven_day": {"used_percentage": 3,  "resets_at": 1788790000}
}

Register the capture once — no undocumented endpoint, no token:

cc-cockpit statusline --install

It writes statusLine into ~/.claude/settings.json, keeping a .bak. If you
already had one, it is chained rather than replaced, so its output still shows
in the CLI. The captured payload also carries the context window percentage
per session, which the dashboard shows next to each open session.

From then on the official percentage is the source of truth, and it reveals the
real ceiling — local consumption ÷ official percentage — so the currency
figures stay meaningful too.

When there is no statusline data yet

Numbers fall back, in order of trust: official (statusline) → anchored
(what you typed) → local estimate. The middle one exists because a fresh
install has no capture yet:

cc-cockpit sync --block 23% --block-reset 1h55 --week 3% --week-reset 1h15
cc-cockpit sync            # show anchors, samples and implied ceilings
cc-cockpit sync --reset

Both the tray and the dashboard say which source is in use.

How it works

<account>/projects/**/*.jsonl   transcripts (usage per request)
<account>/sessions/*.json       one entry per live CLI       ─┐
statusline payload (stdin)      official rate limits + context ├─> cockpit/
   ~/.local/share/cc-cockpit/accounts/<id>/events.ndjson <────┘
   ~/.local/share/cc-cockpit/accounts/<id>/panel.json    official snapshot

<account> is CLAUDE_CONFIG_DIR or ~/.claude when nothing is configured,
and each configured account otherwise.

• collector.py reads each transcript from the last offset, so a refresh
  costs ~30 ms even with 190 MB of history.
• Events land in a dedicated NDJSON file. That matters: Claude Code prunes
  transcripts after ~30 days, and from the first collection onward cc-cockpit
  keeps the full history.
• Deduplication by message.id:requestId, so resuming a session is not counted
  twice.
• sessions.py validates each pid against /proc and compares the
  starttime, so a recycled pid is never mistaken for a live session. The
  recent list comes from the transcripts instead — only what is still on disk
  can be resumed — and reads the last 64 KB of each, where Claude Code keeps
  rewriting the generated title and the working directory.
• Prices live in pricing.py: cache writes at 1.25× (5m) and 2× (1h) of input,
  cache reads at 0.1× (0.025× on Fable 5.1). The transcript separates the two
  cache-write TTLs and the calculation uses that split instead of assuming 5m.
• i18n.py holds one catalogue for all three surfaces, plus locale-aware number
  and currency formatting.
• panel.py keeps the official snapshot and appends a line to
  panel-history.ndjson whenever the percentage changes. /api/history reads
  it back for the chart, which is what that file was always for.
• accounts.py owns the roster and hands every stateful module its directory.
  Only money is ever added across accounts — rate limits, ceilings and anchors
  belong to one subscription and are never mixed.
• terminal.py knows twelve terminal emulators and what each wants, so a
  session can be reopened where it lives.
• auth.py reads two fields out of .credentials.json and nothing else. The
  access-token expiry sitting next to them is deliberately ignored: the CLI
  refreshes it by itself every few hours, so showing it would announce an expiry
  that never happens.

Honest limitations

• Without the statusline capture and without limits, the percentage is
  relative to your own history, not to the real plan limit.
• The statusline only refreshes while a CLI session is rendering. That is
  enough — what is not running cannot be consuming — but right after a long
  gap the percentage may lag until the next render.
• Consumption from the Claude app shows up in the official percentage, never in
  the local currency figures, which read Claude Code transcripts only.
• Models released after this version fall back to their family price (opus,
  sonnet, haiku, fable) until they are added to pricing.py.
• <synthetic> rows are responses the CLI generates locally: they show up in
  the request count and cost nothing.
• Opening a terminal on a session starts a new one resuming that
  conversation; it cannot raise the window the session is already in. Window
  activation by pid is not available to an ordinary application on Wayland.
• With several accounts, the All accounts view adds up money but never
  percentages: each subscription has its own window, and one combined ring
  would be a number that does not exist anywhere.

Packaging

packaging/ holds the .deb build script and the Arch PKGBUILD; see
packaging/README.md for the release flow. A v* tag
builds the wheel, the sdist and the .deb, publishes to PyPI and attaches
everything to the GitHub release.

License

MIT — see LICENSE.

Not affiliated with Anthropic.