Paneflow 会为你电脑上的每个账户显示 Claude Code 和 Codex 订阅的已用额度：
侧边栏底部的胶囊、显示每个账户详情的气泡，以及 Settings 中展示一年每日活动的
**Usage** 页面。Paneflow 从不读取你的凭据或令牌，也从不自行调用用量 API。

## 账户 [#accounts]

一个账户就是一个智能体加一个配置目录。Paneflow 会列出默认的 `~/.claude` 和
`~/.codex` 目录、每个在环境中设置了 `CLAUDE_CONFIG_DIR` 或 `CODEX_HOME` 的空间，
以及每个这样设置的智能体配置。指向同一目录的两个空间共享一个账户。通过 API 密钥
（`ANTHROPIC_API_KEY`、`OPENAI_API_KEY`）计费的账户没有套餐限额，并会如实显示。

## 侧边栏胶囊 [#the-sidebar-capsule]

胶囊位于筛选框和 Settings 按钮之间。它的圆环和百分比显示活动空间各账户中最紧的
限额；如果该空间没有设置账户，则显示默认账户中最紧的限额。圆环低于 80% 时使用
强调色，达到 80% 起变为琥珀色，达到 95% 起变为红色。将鼠标悬停在胶囊上，可查看
它所对应的账户和时间窗口。

点击胶囊，或在它获得焦点时按 Enter 或 Space，即可打开气泡。每个账户会显示会话
窗口和每周窗口及其进度条，进度条的提示中显示重置时间，另有一行本周节奏：要么是
按当前节奏你将达到每周限额的时间，要么是到重置时你将用掉的本周额度比例。底部的
**Open usage settings** 会打开 Usage 页面。

要隐藏胶囊，请在 **Customize sidebar › Show** 中关闭 **Usage**，或将
`sidebar_show.usage` 设为 `false`。如果没有 Claude Code 或 Codex 账户，胶囊不会
出现。

## Usage 页面 [#the-usage-page]

**Settings › Usage** 为每个账户显示一张卡片，包含两个圆环（外圈为本周，内圈为
会话）、重置时间和节奏行。**Refresh** 会向每个账户查询当前限额。

在 **Activity by agent** 下，过去 53 周内有活动的每个账户都会有一个每天一格的
活动记录表。可在 **Turns**、**Tokens**（输入和输出，不含缓存）和 **Active time**
之间切换指标。所有记录表共用同一刻度，因此无论是哪个智能体，格子颜色越深表示
活动越多。将鼠标悬停在某一天上，或用 Tab 进入记录表后用方向键逐日移动，即可
查看当天每个智能体的计数。

Paneflow 自行统计这些活动，数据来自在本机 Paneflow 面板中运行的智能体。它不了解
在其他地方运行的会话。

### 导入过往活动 [#import-past-activity]

Paneflow 首次以空的活动账本启动时，会在后台读取你已有的 Claude Code 对话记录
（每个 Claude 配置目录中的 `projects/**/*.jsonl`）和 Codex 会话文件，补全它尚未
统计的日期。页面底部的 **Import past activity** 会重新运行导入。重复导入绝不会把
同一天计算两次，当天始终交给实时统计。

导入会先读取最新的文件，在读取 10,000 个文件或 2 GB 后停止。提前停止时，页面会
显示 **Imported the last \{n\} days**。Claude Code 默认保留对话记录 30 天（其设置
中的 `cleanupPeriodDays`），因此更早的日期保持为空。

## 限额从何而来 [#where-the-limits-come-from]

Paneflow 只从智能体自己的程序读取限额，这些程序使用你自己的账号登录：

- **Claude Code 状态行。** 当你安装 Claude Code 集成且没有自己的状态行时，
  Paneflow 会把 Claude 设置中的 `statusLine` 设为 `paneflow-ai-hook StatusLine`。
  每次响应后，Claude Code 会把它报告的限额传给该命令，Paneflow 再将其转发给胶囊。
  该命令不输出任何内容，因此你的状态行保持为空。
- **已安装的 Claude Code 和 Codex 二进制文件。** 当你打开气泡或刷新 Usage 页面
  时，Paneflow 会向已安装的 `claude` 查询用量（不发送消息），并向
  `codex app-server` 查询速率限制。每个账户最多每 30 秒查询一次。
- **Codex 会话文件。** 每个 Codex 回合结束后，Paneflow 会读取 Codex 写入其最新
  会话文件中的限额。

每个账户以最近一次读取的结果为准。

### 如果你有自己的状态行 [#if-you-have-your-own-status-line]

Paneflow 从不更改你配置的状态行。它会改为从已安装的 Claude Code 二进制文件读取
限额，因此胶囊照常工作。在读取成功之前，该账户会显示："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."

## Paneflow 存储的内容 [#what-paneflow-stores]

所有内容都保存在 Paneflow home（`~/.paneflow`，Windows 上为
`%USERPROFILE%\.paneflow`）的 `usage` 文件夹中：

- `usage/plans.json`：每个账户各时间窗口的已用百分比和重置时间、读取时间以及
  智能体版本。
- `usage/ledger.json`：每个账户在过去 400 天中每一天的回合数、活跃时长以及输入
  和输出 token 数，另外还有它所读取的对话记录的路径和读取位置。它不存储任何
  提示词或响应文本。

## 关闭 [#turn-it-off]

在 `paneflow.json` 中将 `usage.plan_limits` 设为 `false` 即可隐藏胶囊。下次
Paneflow 刷新其 Claude Code 集成时（启动时或运行
`paneflow integrations install claude-code` 时），也会移除它设置的状态行。
`paneflow integrations remove claude-code` 同样会将其移除。