Paneflow shows how much of your Claude Code and Codex subscriptions you have
used, for every account on your computer: a capsule in the sidebar footer,
a bubble with the detail of each account, and a **Usage** page in Settings
with a year of daily activity. Paneflow never reads your credentials or
tokens and never calls a usage API itself.

## Accounts

An account is one agent plus one config directory. Paneflow lists the
default `~/.claude` and `~/.codex` directories, every space that sets
`CLAUDE_CONFIG_DIR` or `CODEX_HOME` in its environment, and every agent
profile that does. Two spaces that point at the same directory share one
account. An account billed through an API key (`ANTHROPIC_API_KEY`,
`OPENAI_API_KEY`) has no plan limits and says so.

## The sidebar capsule

The capsule sits between the filter and the Settings button. Its ring and
percentage show the most constraining limit of the active space's accounts,
or of the default accounts when the space sets none. The ring takes the
accent color below 80 %, amber from 80 %, and red from 95 %. Hover it for
the account and the window it describes.

Click the capsule, or press Enter or Space on it, to open the bubble. Each
account shows its session and weekly windows with a meter, the reset time in
the meter's tooltip, and a pace line for the week: either the time you
reach the weekly limit at your current pace, or the share of the week you
will have used when it resets. **Open usage settings** at the bottom opens
the Usage page.

To hide the capsule, turn off **Usage** in **Customize sidebar › Show**, or
set `sidebar_show.usage` to `false`. With no Claude Code or Codex account,
the capsule does not appear.

## The Usage page

**Settings › Usage** shows one tile per account with two rings, the week
outside and the session inside, the reset times, and the pace line.
**Refresh** asks every account for its current limits.

Under **Activity by agent**, each account with activity in the last 53 weeks
gets a register of one cell per day. Switch the metric between **Turns**,
**Tokens** (input and output, cache excluded), and **Active time**. All
registers share one scale, so a darker cell means more activity whatever the
agent. Hover a day, or move through the days with the arrow keys after
tabbing into a register, to read every agent's count for that day.

Paneflow counts this activity itself, from the agents that run in its panes
on this computer. It does not know about sessions run elsewhere.

### Import past activity

The first time Paneflow starts with an empty activity ledger, it reads your
existing Claude Code transcripts (`projects/**/*.jsonl` in each Claude config
directory) and Codex session files in the background, and fills in the days
it does not count yet. **Import past activity** at the bottom of the page
runs the import again. Importing twice never counts a day twice, and today
is always left to the live count.

The import reads the newest files first and stops after 10,000 files or
2 GB. When it stops early, the page says **Imported the last \{n\} days**.
Claude Code keeps transcripts for 30 days by default (`cleanupPeriodDays`
in its settings), so older days stay empty.

## Where the limits come from

Paneflow reads limits only from the agents' own programs, signed in with
your own login:

- **Claude Code status line.** When you install the Claude Code integration
  and have no status line of your own, Paneflow sets `statusLine` in the
  Claude settings to `paneflow-ai-hook StatusLine`. After each response,
  Claude Code passes it the limits it reports, and Paneflow forwards them to
  the capsule. It prints nothing, so your status line stays empty.
- **The installed Claude Code and Codex binaries.** When you open the bubble
  or refresh the Usage page, Paneflow asks the installed `claude` for its
  usage, without sending a message, and asks `codex app-server` for its rate
  limits. Each account is asked at most once every 30 seconds.
- **Codex session files.** After each Codex turn, Paneflow reads the limits
  Codex wrote in its newest session file.

The most recent reading of an account wins.

### If you have your own status line

Paneflow never changes a status line you configured. It reads your limits
from the installed Claude Code binary instead, so the capsule works the
same. Until that reading succeeds, the account shows: "Claude Code has not
reported plan limits for \{folder\} yet. Check that it is installed and
signed in for this folder, then reopen this panel."

## What Paneflow stores

Everything stays in the `usage` folder of the Paneflow home (`~/.paneflow`,
`%USERPROFILE%\.paneflow` on Windows):

- `usage/plans.json`: for each account, the used percentage and reset time
  of each window, when it was read, and the agent version.
- `usage/ledger.json`: for each account and day of the last 400 days, the
  number of turns, the active time, and the input and output tokens, plus
  the path and read position of the transcripts it reads. It stores no
  prompt or response text.

## Turn it off

Set `usage.plan_limits` to `false` in `paneflow.json` to hide the capsule.
The next time Paneflow refreshes its Claude Code integration, at startup or
with `paneflow integrations install claude-code`, it also removes the status
line it set. `paneflow integrations remove claude-code` removes it as well.