摘要本文介绍一个Claude Code 自定义状态栏工具 claude-code-statusline并带你完成安装与 Claude Code 接入配置显示模型、Git、上下文、token 和任务用时等并通过终端界面或 CLI 配置主状态栏、子 Agent 行及可选实时指标。一、为什么给 Claude Code 加一个状态栏用 Claude Code 做任务时除了看回复内容我们还会关心当前使用什么模型、正在操作哪个目录、Git 工作区有没有变化、上下文还剩多少以及这次任务已经运行了多久。claude-code-statusline这个工具把这些信息集中到会话底部并提供可配置的子 Agent 状态行。主栏支持 60 个显示项子 Agent 行支持 14 个显示项可以按自己的工作习惯选择和排序。刚开始使用时保留模型、目录、Git、上下文余量和任务用时就够了。下面从安装开始逐步配出一套日常可用的界面。二、准备环境完成安装与接入2026.10.18 更新TypeScript 重构与 npm 安装仓库已使用TypeScript 重构原 Python 实现。从v3.0.0开始软件包通过 npm 分发后续新版不再支持通过 pipx 安装或更新Python/pipx 方式保留用于历史版本。工具版本安装与更新方式软件包名v2.0.0 及之前Python pipxpipx 支持的最后一个版本为 v2.0.0fbincon-claude-code-statuslinev3.0.0 及之后Node.js npmnpm 分发的首个正式版本为 v3.0.0fbincon/claude-code-statusline已有 pipx 安装的用户请先阅读第七节新增的“从 Python/pipx 迁移到 npm”再切换安装方式。1. 准备新版运行环境平台运行环境Linux / WSLNode.js 22.x 或 24.xx64Windows 10/11Node.js 22.x 或 24.xx64macOS 14Node.js 22.x 或 24.xIntel / Apple SiliconWindows ARM 设备使用 x64 Node 仿真原生 Windows ARM64 和 32 位运行时暂不在支持范围。WSL 用户在 WSL 内安装并使用同一环境中的 Claude Code。先准备 Node.js、npm 和 Claude Code CLI在终端检查node --version npm --version claude --version要显示 Git 信息还需让git --version正常运行。新版 npm 包已包含受支持平台的原生依赖正常安装和运行无需 Python、pipx 或编译器。2. 安装 npm 软件包首次安装新版在 Bash、Zsh 或 PowerShell 中执行npm install --global --ignore-scripts fbincon/claude-code-statusline安装后确保 npm 的全局命令目录位于 PATH 中调整 PATH 后重新打开终端。运行命令仍为claude-statusline。Windows 的 npm 入口使用claude-statusline.cmd本节新增步骤及后文通用配置命令均按此替换原文中的claude-statusline.exe对应历史 Python/pipx 安装。3. 将新版接入 Claude Code在终端依次执行Windows 将命令名替换为claude-statusline.cmdclaude-statusline --version claude-statusline install --dry-run claude-statusline install claude-statusline doctor--version确认实际运行的是新版install --dry-run预览接入改动install写入本工具的 Claude Code 接入doctor检查环境与接入状态。npm 安装软件包后还需要执行接入步骤。检查通过后在受信任终端重启 Claude Code加载状态栏、命令和插件。兼容宿主上的两个编辑器入口默认启用保留已有明确关闭偏好原生计时与高级实时采集的新安装默认值见第六节更新。若遇到已有状态栏或同名入口冲突按新版冲突处理说明检查归属后处理。以下保留原 Python/pipx 安装与接入内容适用于 v2.0.0 及之前。如需明确安装最后一个 Python 版可执行pipx install fbincon-claude-code-statusline2.0.0这一路径不会安装 npm 新版。1. 检查前置环境平台Python 环境Linux / WSLPython 3.10Windows 10/11CPython 3.10–3.14x86/x64自动安装 windows-curses 依赖macOS 14提供 curses 的 CPython 3.10–3.14Intel / Apple SiliconWindows ARM 设备可使用 x64 Python 仿真原生 ARM64 Python 暂不在支持范围。WSL 用户在 WSL 内完成安装并使用同一环境中的 Claude Code。在 Linux、WSL、macOS 终端检查 Pythonpython3--versionWindows PowerShell 使用 Python 启动器检查未安装启动器时可用python --versionpy--version还需要 pipx用它管理这个命令行工具。缺少环境时按 Python 官方下载页选择表中支持的版本按 pipx 官方安装说明完成安装再检查pipx --version claude --version要显示 Git 信息还需让git --version能正常运行。2. 安装软件包下面的单行命令适用于 Bash、Zsh 和 PowerShellpipx install fbincon-claude-code-statusline pipx ensurepath执行后重新打开终端让 PATH 更新生效。安装包名是fbincon-claude-code-statusline运行命令是claude-statusline。Windows 将下文的命令名替换为claude-statusline.exe参数相同。3. 接入 Claude Code在新终端依次执行claude-statusline --version claude-statusline install --dry-run claude-statusline install claude-statusline doctor第一条确认工具可用--dry-run预览接入修改install写入接入配置doctor检查当前环境与集成状态。软件包安装和 Claude Code 接入是两个步骤。检查通过后在受信任终端重启 Claude Code底部应出现状态栏。已有第三方状态栏或同名配置入口时先按冲突处理说明处理。三、先读懂状态栏里的信息信息主要含义模型与 effort当前模型以及宿主提供的思考强度当前目录当前会话所在的工作目录Git分支、与上游的提交差距、工作区变化Context remaining当前上下文窗口的剩余比例使用限额宿主提供的五小时、每周或网关额度Token当前会话累计记录的输入、缓存和输出用量Task total time当前或最近一次人类任务的总耗时Git 中的↑N、↓N表示领先、落后上游的提交数●N是暂存文件数~N是未暂存文件数?N是未跟踪文件数!N是冲突文件数。非 Git 目录会省略这一项。Context 73% left表示上下文窗口还剩约 73%。它与账户限额、会话累计 token 分别统计。tokens中hit是缓存读取输入miss是普通输入与缓存创建之和out是输出统计包含可发现的子 Agent transcript。任务计时包含排队、用户等待、所属子 Agent 工作和主 Agent 收尾。⏱表示运行✓表示成功■表示中断✗表示失败。需要排除已核实的用户等待时可另选task-active-timer只有原生计时观测完整时才显示。这些字段依赖宿主输入或本地记录缺失时可能省略。完整口径见显示项与指标定义。四、通过终端界面调整显示内容1. 先用独立 TUI 配置在 Claude Code 外的真实终端运行claude-statusline configure窗口至少需要 64×18。进入后可以看到四个页面页面用途Main选择主状态栏条目调整顺序Subagents配置子 Agent 独立行Settings设置颜色、格式、目录样式、刷新行为及预设Layout设置分行、条目优先级和最大宽度图 1Main 页面。下方 Preview 使用固定样例数据用于检查排版。可以先在 Main 页选一个条目用 Space 开关再用左右方向键调整顺序输入文字可筛选条目。需要修改单项标签、图标或格式时选中后按 CtrlE。独立外部 TUI 按键操作Tab / ShiftTab切换页面↑ / ↓、Space、← / →选择、开关、排序或调整设置值CtrlE / CtrlG打开逐项格式返回或取消输入CtrlS完成字段输入后保存完整草稿Esc先取消输入未处于输入状态时放弃草稿退出Enter 在项目页可保存在高级字段中用于编辑或确认输入。保存整份配置统一用 CtrlS更容易记住。回到 Claude Code 后下一次状态栏刷新会使用新配置。2. 在 Claude Code 内启动配置下面两条命令输入到Claude Code 会话按需选择一个命令打开位置Claude Code 版本/statusline-configure支持的外部终端中打开同一个 TUI2.1.258/statusline-configure-native当前会话内的 Client 配置面板2.1.287外部入口在 Linux 使用 tmux 或 GNOME Terminal在 macOS 使用 tmux 或 Terminal.app在 Windows 使用新控制台启动器不可用时使用独立configure。会话内 Client 打开后先点击面板区域再用键盘。它的保存方式是S 保存留页、F 保存并退出、Q 放弃未保存修改取消字段输入用 CtrlG。按页面底部提示操作即可。各入口共享当前用户的配置对该配置目录下的 Claude Code 项目生效。/statusline-config则提供问答配置会使用模型回合状态栏渲染本身读取宿主输入和本地状态不额外发起网络请求或消耗模型 token。下面展示会话内配置面板。截图中的Preview 是固定样例数据会话底部的主状态栏显示会话数据。Linux会话内 Main、Subagents、Settings、LayoutMain选择主状态栏条目并调整顺序。Subagents配置子 Agent 独立行及条目顺序。Settings调整外观、刷新行为与显示格式。Layout设置分行、条目优先级与最大宽度。五、三组可以直接使用的配置以下命令都在系统终端执行。前两组是主栏的两种选择第三组单独配置子 Agent 行。set-items会替换该栏启用集合并确定顺序想追加某项时用enable。1. 精简开发视图claude-statusline config set-items model-with-effort current-dir git context-remaining task-timer claude-statusline config set directory-style home claude-statusline config set separator-style compact claude-statusline config show这组保留模型、目录、Git、上下文余量和任务用时。home会将主目录前缀缩写为~compact使用紧凑分隔符show可确认保存结果。如果希望主栏分为两行接着执行claude-statusline config layout explicit model-with-effort,current-dir,git context-remaining,task-timer每个参数表示一行逗号连接同行条目顺序与刚才启用的条目一致。在 Layout 页也能设置行边界并为重要条目分配较高优先级、为长目录限制宽度。图 2Layout 页面截图中的 Preview 为样例数据。自动布局会折行显式布局在宽度不足时按限制截短并精简低优先级项。2. 限额与 token 视图claude-statusline config set-items five-hour-limit weekly-limit spend-limit tokens claude-statusline config layout auto适合主要关注用量的场景。spend-limit依赖宿主和网关提供的额度数据账户或端点未提供时会省略选择显示项不会让缺失数据自动出现。3. 子 Agent 状态行子 Agent 行需要 Claude Code 2.1.205逐任务 effort 需 2.1.214。默认已启用自定义行可设置为claude-statusline config subagents set-items status-elapsed name model-with-effort context-remaining task claude-statusline config set subagent-hide-completed on claude-statusline config set subagent-row-limit 6真实任务运行子 Agent 时每行会展示对应任务的状态与用时、名称、模型、上下文和任务标签。上述设置隐藏已完成代理最多显示六行。主栏仍属于主会话每条子 Agent 行使用自己的任务数据子 Agent 的tokens表示上下文占用。图 3Subagents 页面及样例预览展示子 Agent 行的可配置内容。4. 用预设起步保存自己的方案也可以从minimal、developer、monitoring、multi-agent四套预设开始。例如先预览再应用开发预设claude-statusline config preset developer --dry-run claude-statusline config preset developer预设展开后仍可编辑。在 Settings 中调整颜色、数字和模型名称格式Main/Subagents 中的 CtrlE 可覆盖单项格式。满意后导出到当前目录的新文件claude-statusline config export ./statusline.json在另一台已安装并接入工具的电脑上将文件放到当前目录先检查再导入claude-statusline config import ./statusline.json --dry-run claude-statusline config import ./statusline.json文件已存在时导出请换一个文件名。可移植配置包含显示设置及工具管理的刷新等选项运行状态和插件接入偏好需在各机器分别管理。六、按需开启实时指标2026.10.18 更新npm 版新安装默认关闭原生计时和高级实时采集并保留已有明确偏好。只启用原生计时可执行claude-statusline install --native-timing启用完整采集使用下文的claude-statusline install --live-metrics。两者均要求 Claude Code 2.1.289执行后运行doctor并重启 Claude Code。以下原文保留其中“新安装默认采集原生计时”的描述适用于历史 Python 版。需要查看运行状态、活动 Agent 数量、结构化任务进度和最近工具时先确认 Claude Code 为 2.1.289在系统终端执行claude-statusline install --live-metrics claude-statusline config enable run-state permission-mode active-agents task-progress last-tool claude-statusline doctor检查后重启 Claude Code加载采集器后续运行任务时观察新增字段。这一步同时涉及采集器接入和显示项选择仅在编辑器中勾选字段还不够。高级实时指标默认关闭与兼容宿主新安装默认采集的原生计时元数据分别管理。没有有效观测时显示—有限覆盖或最近观测可能带*。其中任务进度来自结构化任务记录不能据此推算还剩多久。七、常见问题、升级与卸载2026.10.18 更新npm 版排查、更新、迁移与卸载以下新增说明适用于 v3.0.0 及之后Windows 使用claude-statusline.cmd。原 Python/pipx 说明保留在本节后半部分。1. npm 安装后找不到命令全局安装后先检查软件包与安装前缀npm list --global --depth0 npm prefix --global确认 npm 的全局命令目录已加入 PATH调整后重新打开终端。LinuxWSLmacOS 可用command -v claude-statusline核对入口Windows PowerShell 可用Get-Command claude-statusline.cmd。若仍指向 Python/pipx 旧版先按下方迁移步骤处理同名入口。2. 更新已全局安装的 npm 版先退出 Claude Code 和配置编辑器再执行npm install --global --ignore-scripts fbincon/claude-code-statusline claude-statusline --version claude-statusline install claude-statusline doctor检查通过后重启 Claude Code。重新执行 npm 安装命令会更新软件包随后仍需执行install同步命令路径、hooks、skills 和插件资源。pipx upgrade只管理历史 Python 包不能更新到 v3.x。如果采用下方的独立目录安装更新时保持同一个--prefix ./statusline-node通过同一 Node/JavaScript 入口执行--version、install和doctor全局 npm 更新命令不更新该独立目录。3. 从 Python/pipx 迁移到 npm切换前先退出 Claude Code 和配置编辑器备份整个 Claude 配置目录默认~/.claude使用CLAUDE_CONFIG_DIR时备份对应目录记录原 Python 命令的绝对路径与版本并保留原 pipx 环境用于回退。新旧版不要同时向同一配置目录写入。为避开 PATH 中已有的同名 Python 命令可先在一个长期保留的位置使用独立目录安装。以下命令从该位置执行将新版安装到./statusline-node并明确使用 Node 入口完成接入npm install --prefix ./statusline-node --ignore-scripts fbincon/claude-code-statusline3.1.0 node ./statusline-node/node_modules/fbincon/claude-code-statusline/bin/claude-statusline.js --version node ./statusline-node/node_modules/fbincon/claude-code-statusline/bin/claude-statusline.js install --dry-run node ./statusline-node/node_modules/fbincon/claude-code-statusline/bin/claude-statusline.js install node ./statusline-node/node_modules/fbincon/claude-code-statusline/bin/claude-statusline.js doctor使用自定义配置目录时为上述install和doctor命令传入相同的--config-dir。检查通过后重启 Claude Code接入会绑定实际 Node 和 JavaScript 入口因此使用期间须保留该安装目录和 Node 可执行文件。独立目录安装不会把终端里的claude-statusline自动切换到新版后续配置、更新和卸载应继续通过上述node .../claude-statusline.js入口操作。已有显示配置、明确的编辑器与采集偏好及无关 Claude 设置会保留。不要用 npm--force覆盖归属不明的同名命令。如需保留 Python 回退环境可继续使用独立目录如需改用全局 npm 命令在新版验证通过后先用pipx list核实旧包名称再用pipx uninstall fbincon-claude-code-statusline移除对应旧包随后按第二节完成全局 npm 安装和接入。确认全局版本接入正常后再删除独立安装目录。需要回退时按新版迁移与恢复指南恢复切换前兼容备份和原 Python 接入。4. 卸载 npm 版先退出 Claude Code 和配置编辑器在命令仍可用时移除接入再卸载软件包。对于全局 npm 安装claude-statusline uninstall --dry-run claude-statusline uninstall npm uninstall --global fbincon/claude-code-statusline仅在接入卸载成功后执行最后一条。工具会移除归属本工具的接入资源保留第三方设置以及显示配置、偏好、缓存、任务状态和备份便于重装复用。若使用独立目录安装通过同一node .../claude-statusline.js入口依次执行uninstall --dry-run和uninstall确认成功后再删除当初专门创建的statusline-node安装目录。npm uninstall --global不负责移除这类独立目录安装。以下保留原常见问题、Python/pipx 升级与卸载内容。涉及 pipx 或.exe的步骤适用于 v2.0.0 及之前npm 版请使用以上更新说明。找不到命令先运行pipx list确认包已安装再执行pipx ensurepath并重新打开终端。Windows 使用claude-statusline.exe。状态栏没出现运行claude-statusline doctor检查 PATH、接入是否完成、显示项是否为空以及宿主是否禁用了 hooks/statusline接入修复后重启 Claude Code。若提示因信任被跳过按宿主提示完成对应信任操作。配置入口不可用检查claude --version、安装偏好和插件状态。不兼容入口会暂挂宿主升级后重新执行install与doctor。macOS 的会话内 Client 仍有已记录的交互限制可使用独立 TUI 或 CLI。部分数据暂时缺失首次真实模型响应前transcript 或用量信息可能尚未产生限额和 effort 等字段也取决于宿主是否提供。doctor的[WARN]表示有降级情况需结合具体提示判断。升级时先退出 Claude Code在终端执行pipx upgrade fbincon-claude-code-statusline claude-statusline install claude-statusline doctor随后重启 Claude Code。软件包升级后还要同步接入。若使用过本仓库旧分发名先核实安装来源再按包名迁移说明处理。卸载时先退出 Claude Code再移除接入最后卸载软件包claude-statusline uninstall --dry-run claude-statusline uninstall pipx uninstall fbincon-claude-code-statusline显示配置、运行状态和备份会保留便于重装复用。更多排查步骤见完整使用指南。八、项目与文档入口项目使用 MIT 许可证。源码、发行包和详细文档可从以下入口获取GitHub 主仓库Gitee 同步仓库npm 软件包TypeScript 版中文使用指南CLI 参考保留 Python 版供参考PyPI 软件包最后一个版本为 v2.0.0v2.0.0 中文使用指南最后一个 Python 版欢迎结合自己的开发习惯调整显示内容。