# claude-context

**Repository Path**: maoning325/claude-context

## Basic Information

- **Project Name**: claude-context
- **Description**: 用于 Claude Code statusLine 的本地离线上下文状态栏。自动识别 Claude、GLM、MiniMax、Qwen、Kimi、DeepSeek等模型的上下文窗口大小，分开展示当前上下文占用百分比和当前目录累计用量，避免多模型混用和累计 token污染导致的误报。不依赖远程 API，无需发布到 npm。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-14
- **Last Updated**: 2026-05-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# claude-context-status

用于 Claude Code `statusLine` 的本地离线上下文使用情况状态栏命令。

本工程主要面向把 Claude Code 作为通用编码入口、并接入国产化或第三方模型的使用场景。它重点解决 MiniMax、智谱 GLM、Qwen、Kimi、DeepSeek 等模型上下文窗口不同、状态栏容易误判占用比例的问题。

与偏向单一模型订阅体验的其他展示工具不同，本项目的定位是：

- 本地离线运行，不依赖 npm 发布、远程 API 或网络服务。
- 默认支持常见 Claude、国产化和第三方模型的上下文窗口识别。
- 根据当前模型自动选择上下文窗口，避免 200k、1M、128k 等模型混用时误报。
- 分开展示当前上下文占用和当前目录累计 `Total`，避免累计用量污染上下文百分比。
- Claude 模型作为兼容对象支持，但不是唯一目标。

## 快速开始

### 必须操作 1：本地安装

【必须】在本项目目录中执行：

```bash
npm install
npm run build
npm install -g .
```

本项目不会发布到 npm。不要执行 `npm install -g claude-context-status`，请始终从本地目录安装。

### 必须操作 2：配置 Claude Code

【必须】在 Claude Code 配置中加入：

```json
{
  "statusLine": {
    "type": "command",
    "command": "claude-context-status"
  }
}
```

完成以上两步后，重新打开 Claude Code 会话，让配置重新加载。

## 用量口径

状态栏会把两类 token 分开展示：

- 当前上下文：当前上下文窗口内已占用的 token，只用它计算 `Context xx% used`、进度条和剩余百分比。
- 当前目录累计用量：当前 `cwd` 对应的 transcript usage 累计值，只显示为 `Total`，不参与上下文百分比计算。

这样即使其它目录或整条会话的累计用量超过模型上下文窗口，也不会污染当前目录的 `Total`，也不会出现 `Context 180% used` 这类误导性结果。

当前上下文的计算口径：

1. 优先使用 Claude Code statusline stdin 中的 `context_window.used_percentage`，并按上下文窗口换算成当前用量。
2. 如果没有原生百分比，则使用 `context_window.current_usage` 中的 `input_tokens + cache_creation_input_tokens + cache_read_input_tokens`。
3. 如果只有 `total_input_tokens`，则使用它作为当前上下文用量。
4. 如果 stdin 没有提供当前上下文用量，但提供了 `transcript_path`，则从 transcript 中最后一条匹配 usage 记录提取 `input_tokens + cache_creation_input_tokens + cache_read_input_tokens` 作为当前上下文用量。
5. `output_tokens` 和 `context_window.total_tokens` 不计入当前上下文用量，避免把累计消耗误算成上下文占用。

`Total` 的来源优先级：

1. 如果同时有 `cwd` 和 `transcript_path`，优先统计 transcript 中同一 `cwd` 的 usage 累计。
2. 如果有 `transcript_path` 但没有可用 `cwd`，退回到 transcript 全量累计，优先使用 transcript 中显式累计字段，否则累加 usage。
3. 如果没有可用 transcript，但 stdin 提供了 `total_tokens`、`cumulative_tokens`、`session_tokens` 或 `context_tokens_used`，则使用这些 stdin 累计字段显示 `Total`。

## 压缩次数

如果当前 transcript 可读取，状态栏会显示 `Compact N`。`N` 是当前 transcript 中 Claude Code `compact_boundary` 事件的数量。

`Compact` 表示当前会话被 `/compact` 或自动 compact 压缩过的次数。没有压缩事件时显示 `Compact 0`。`/clear` 会开启新的会话上下文，不计为 compact；如果 Claude Code 切换到新的 transcript，`Compact` 会从 0 重新统计。

`Compact` 是当前会话级指标，不按 `cwd` 过滤；当前目录累计 token 仍只显示在 `Total` 中。

没有发生过 compact 时：

```text
qwen3-coder-plus | Context 37% used | 370k/1M | Compact 0
```

带 compact 的输出示例：

```text
◇ qwen3-coder-plus  Context 37% used  370k/1M  ███████░░░░░░░░░░░░░  63% left  Total 1.8M  Compact 1
```

如果只有累计用量、没有当前上下文窗口用量，会显示：

```text
qwen3-coder-plus | Context unknown | 1M limit | Total 1.8M | Compact 1
```

如果 transcript 不可读取，则不会显示 `Compact`。

## 可选操作：用户配置

【可选】不创建配置文件也能运行，命令会使用内置模型表和默认配置。

可选配置文件路径：

```text
~/.claude/context-status.json
```

示例：

```json
{
  "style": "hud",
  "defaultContextTokens": 200000,
  "models": {
    "custom-model": 131072,
    "anthropic/claude-sonnet-4": 500000
  }
}
```

`models` 中的模型名会被规范化：大小写不敏感，`anthropic/`、`zhipu:` 这类 provider 前缀会被忽略。例如 `anthropic/Claude-Sonnet-4` 会按 `claude-sonnet-4` 匹配。

支持的显示风格：

- `hud`：显示模型、当前上下文百分比、当前 token 用量、进度条、剩余百分比和累计用量。
- `minimal`：显示更紧凑的模型、当前上下文 token 用量和累计用量。

常见可选配置：

- 修改显示风格。
- 修改默认上下文窗口。
- 覆盖某个模型的上下文窗口。

上下文窗口优先级：

1. `~/.claude/context-status.json` 的 `models` 覆盖项。
2. Claude Code statusline stdin 中显式提供的上下文窗口。
3. 内置模型表。
4. `defaultContextTokens`。
5. 程序默认值：`200000`。

模型名会做规范化处理。例如 `anthropic/Claude-Sonnet-4` 和 `claude-sonnet-4` 会按同一模型 key 匹配。

## 离线行为

命令不会调用远程 API，也不会访问网络。它只读取：

- Claude Code 通过 stdin 传入的 statusline JSON。
- 必要时读取 Claude Code 提供的本地 transcript 路径。
- 可选的本地用户配置 `~/.claude/context-status.json`。

transcript 解析规则：

- 如果 Claude Code statusline stdin 提供了 `cwd`，transcript 只统计同一 `cwd` 的 usage。
- 当前目录统计时，transcript 中没有 cwd 的行不会计入 `Total`，避免把其它目录或全局会话累计误算进去。
- transcript 中连续重复的 usage 会去重，去重签名包含 `cwd`、模型名、input、output、cache creation 和 cache read，避免 Claude Code 重复写入相同 usage 时放大 `Total`。
- 如果没有可用 cwd，则退回到原来的 transcript 累计逻辑。
- transcript 不存在、不可读或格式不认识时，无法补充 transcript 来源的 `Total`；如果 stdin 已经提供当前上下文用量，仍会正常显示 `Context xx% used`。只有当前上下文用量也拿不到时，才会显示 `Context unknown`。

## 模型上下文窗口

内置模型表覆盖常见 Claude、GLM、MiniMax、Qwen、Kimi、DeepSeek、Gemini、OpenAI 模型，其中国产化和第三方编码模型是主要适配对象。

内置示例：

| 供应商 | 模型匹配规则 | 上下文窗口 |
| --- | --- | ---: |
| Anthropic | `claude-*`、`sonnet*`、`opus*`、`haiku*` | 200k |
| Anthropic | `claude-opus-4-7*`、`claude-opus-4-6*`、`claude-sonnet-4-6*`、`sonnet[1m]` | 1M |
| 智谱 GLM | `glm-5*`、`glm-4.7*`、`glm-4.6*` | 200k |
| 智谱 GLM | `glm-4.5*`、`glm-4-plus*`、`glm-4-air*`、`glm-4-flashx*` | 128k |
| MiniMax | `minimax-m2*` | 204.8k |
| MiniMax | `minimax-m1*` | 1M |
| Qwen | `qwen3-coder-plus*`、`qwen3-coder-flash*`、`qwen3.6-plus*`、`qwen3.5-plus*` | 1M |
| Qwen | `qwen3-coder-480b-a35b-instruct`、`qwen3-coder-30b-a3b-instruct`、`qwen3-max*` | 262,144 |
| Qwen | `qwen-long*` | 10M |
| Kimi | `kimi-k2.5*`、`kimi-k2-0905-preview`、`kimi-k2-thinking*` | 256k |
| DeepSeek | `deepseek-v4*` | 1M |
| Gemini | `gemini-3-*`、`gemini-2.5-pro*`、`gemini-2.5-flash*` | 1,048,576 |
| OpenAI | `gpt-5.2*`、`gpt-5.1*` | 400k |

模型厂商可能调整上下文窗口，同名模型在不同云厂商或聚合服务中也可能有不同限制。用户配置始终优先于内置模型表。

## 输出示例

HUD 风格：

```text
◇ qwen3-coder-plus  Context 37% used  370k/1M  ███████░░░░░░░░░░░░░  63% left  Total 1.8M  Compact 1
```

极简风格：

```text
qwen3-coder-plus | Context 37% used | 370k/1M | Total 1.8M | Compact 1
```