Skip to content
PaneflowPaneflow
Docs

Plan usage

See the session and weekly limits of your Claude Code and Codex subscriptions in the Paneflow sidebar, and a year of daily activity per account in Settings. Where the numbers come from and what Paneflow stores.

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.