claude-hud-statusline

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Claude HUD

Skill by ara.so — Daily 2026 Skills collection.

Claude HUD is a Claude Code plugin that adds a persistent statusline to your terminal showing real-time context window usage, active tool calls, running subagents, and todo progress — always visible below your input prompt.

由ara.so开发的Skill——属于Daily 2026 Skills合集。

Claude HUD是一款Claude Code插件，可为你的终端添加一个持久化状态栏，实时显示上下文窗口使用情况、活跃工具调用、运行中的子Agent以及待办事项进度——始终显示在输入提示下方。

What It Does

功能介绍

Feature	Description
Context health	Visual bar showing how full your context window is (green → yellow → red)
Tool activity	Live display of file reads, edits, and searches as they happen
Agent tracking	Shows which subagents are running and what they're doing
Todo progress	Real-time task completion tracking
Usage limits	Claude subscriber rate limit consumption
Git status	Current branch, dirty state, ahead/behind remote

功能	说明
上下文健康度	可视化进度条，展示上下文窗口的占用程度（绿色→黄色→红色）
工具活动状态	实时显示文件读取、编辑和搜索操作的执行情况
Agent追踪	显示正在运行的子Agent及其当前任务
待办进度	实时跟踪任务完成情况
使用限额	显示Claude订阅用户的速率限额消耗情况
Git状态	当前分支、未提交修改状态、与远程仓库的领先/落后情况

Requirements

系统要求

Claude Code v1.0.80+
Node.js 18+ or Bun

Claude Code v1.0.80+
Node.js 18+ 或 Bun

Installation

安装步骤

Run these commands inside a Claude Code session:

Step 1: Add the marketplace

/plugin marketplace add jarrodwatts/claude-hud

Step 2: Install the plugin

/plugin install claude-hud

Linux users: If you get
EXDEV: cross-device link not permitted
, set TMPDIR first:
bash
mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude

Step 3: Configure the statusline

/claude-hud:setup

Windows users: If setup reports no JavaScript runtime, install Node.js LTS first:
powershell
winget install OpenJS.NodeJS.LTS

Step 4: Restart Claude Code to load the new

statusLine

config.

在Claude Code会话中运行以下命令：

步骤1：添加插件市场源

/plugin marketplace add jarrodwatts/claude-hud

步骤2：安装插件

/plugin install claude-hud

Linux用户注意：若出现
EXDEV: cross-device link not permitted
错误，请先设置TMPDIR：
bash
mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude

步骤3：配置状态栏

/claude-hud:setup

Windows用户注意：若设置时提示无JavaScript运行时，请先安装Node.js LTS版本：
powershell
winget install OpenJS.NodeJS.LTS

步骤4：重启Claude Code以加载新的

statusLine

配置。

What You See

显示效果

Default 2-line layout

默认两行布局

[Opus] │ my-project git:(main*)
Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h)

[Opus] │ my-project git:(main*)
Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h)

With optional lines enabled

启用可选行后的布局

[Opus] │ my-project git:(main*)
Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h)
◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2
◐ explore [haiku]: Finding auth code (2m 15s)
▸ Fix authentication bug (2/5)

[Opus] │ my-project git:(main*)
Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h)
◐ Edit: auth.ts | ✓ Read ×3 | ✓ Grep ×2
◐ explore [haiku]: Finding auth code (2m 15s)
▸ Fix authentication bug (2/5)

Configuration

配置说明

Interactive configuration (recommended)

交互式配置（推荐）

/claude-hud:configure

This opens a guided flow with preset options:

Preset	Shows
Full	Everything — tools, agents, todos, git, usage, duration
Essential	Activity lines + git, minimal clutter
Minimal	Model name and context bar only

/claude-hud:configure

这会打开一个带预设选项的引导式配置流程：

预设方案	显示内容
完整模式	所有内容——工具、Agent、待办事项、Git、使用情况、时长
精简模式	活动行 + Git状态，减少杂乱信息
极简模式	仅显示模型名称和上下文进度条

Manual configuration

手动配置

Edit

~/.claude/plugins/claude-hud/config.json

directly:

json

{
  "lineLayout": "expanded",
  "pathLevels": 2,
  "elementOrder": ["project", "context", "usage", "tools", "agents", "todos"],
  "gitStatus": {
    "enabled": true,
    "showDirty": true,
    "showAheadBehind": true,
    "showFileStats": false
  },
  "display": {
    "showModel": true,
    "showContextBar": true,
    "contextValue": "percent",
    "showUsage": true,
    "usageBarEnabled": true,
    "showTools": true,
    "showAgents": true,
    "showTodos": true,
    "showDuration": false,
    "showSpeed": false,
    "showConfigCounts": false,
    "showMemoryUsage": false,
    "showSessionName": false,
    "showClaudeCodeVersion": false,
    "sevenDayThreshold": 80,
    "showTokenBreakdown": true
  },
  "colors": {
    "context": "green",
    "usage": "brightBlue",
    "warning": "yellow",
    "usageWarning": "brightMagenta",
    "critical": "red",
    "model": "cyan",
    "project": "yellow",
    "git": "magenta",
    "gitBranch": "cyan",
    "label": "dim",
    "custom": "208"
  }
}

直接编辑

~/.claude/plugins/claude-hud/config.json

文件：

json

{
  "lineLayout": "expanded",
  "pathLevels": 2,
  "elementOrder": ["project", "context", "usage", "tools", "agents", "todos"],
  "gitStatus": {
    "enabled": true,
    "showDirty": true,
    "showAheadBehind": true,
    "showFileStats": false
  },
  "display": {
    "showModel": true,
    "showContextBar": true,
    "contextValue": "percent",
    "showUsage": true,
    "usageBarEnabled": true,
    "showTools": true,
    "showAgents": true,
    "showTodos": true,
    "showDuration": false,
    "showSpeed": false,
    "showConfigCounts": false,
    "showMemoryUsage": false,
    "showSessionName": false,
    "showClaudeCodeVersion": false,
    "sevenDayThreshold": 80,
    "showTokenBreakdown": true
  },
  "colors": {
    "context": "green",
    "usage": "brightBlue",
    "warning": "yellow",
    "usageWarning": "brightMagenta",
    "critical": "red",
    "model": "cyan",
    "project": "yellow",
    "git": "magenta",
    "gitBranch": "cyan",
    "label": "dim",
    "custom": "208"
  }
}

Key Configuration Options

关键配置选项

Layout

布局设置

json

{
  "lineLayout": "expanded",   // "expanded" (multi-line) or "compact" (single line)
  "pathLevels": 1             // 1-3 directory levels in project path
}

Path level examples:

```
1
```
→
```
[Opus] │ my-project git:(main)
```
```
2
```
→
```
[Opus] │ apps/my-project git:(main)
```

→

[Opus] │ dev/apps/my-project git:(main)

json

{
  "lineLayout": "expanded",   // "expanded"（多行）或 "compact"（单行）
  "pathLevels": 1             // 项目路径中显示1-3级目录
}

路径层级示例：

```
1
```
→
```
[Opus] │ my-project git:(main)
```
```
2
```
→
```
[Opus] │ apps/my-project git:(main)
```

→

[Opus] │ dev/apps/my-project git:(main)

Context display formats

上下文显示格式

json

{
  "display": {
    "contextValue": "percent"    // "45%"
    // "contextValue": "tokens"  // "45k/200k"
    // "contextValue": "remaining" // "55% remaining"
    // "contextValue": "both"    // "45% (45k/200k)"
  }
}

json

{
  "display": {
    "contextValue": "percent"    // "45%"
    // "contextValue": "tokens"  // "45k/200k"
    // "contextValue": "remaining" // "55% remaining"
    // "contextValue": "both"    // "45% (45k/200k)"
  }
}

Element ordering (expanded layout)

元素排序（多行布局）

json

{
  "elementOrder": ["project", "context", "usage", "memory", "environment", "tools", "agents", "todos"]
}

Omit any entry from the array to hide it entirely.

json

{
  "elementOrder": ["project", "context", "usage", "memory", "environment", "tools", "agents", "todos"]
}

从数组中移除任意元素即可完全隐藏该内容。

Git status options

Git状态选项

json

{
  "gitStatus": {
    "enabled": true,
    "showDirty": true,         // "main*" for uncommitted changes
    "showAheadBehind": true,   // "main ↑2 ↓1"
    "showFileStats": true      // "main* !3 +1 ?2" (modified/added/deleted/untracked)
  }
}

json

{
  "gitStatus": {
    "enabled": true,
    "showDirty": true,         // 未提交修改显示为"main*"
    "showAheadBehind": true,   // "main ↑2 ↓1"
    "showFileStats": true      // "main* !3 +1 ?2"（已修改/已添加/已删除/未跟踪）
  }
}

Colors

颜色设置

Supported values: named colors (

dim

red

green

yellow

magenta

cyan

brightBlue

brightMagenta

), 256-color numbers (

0-255

), or hex (

#rrggbb

json

{
  "colors": {
    "context": "#00FF88",
    "model": "208",
    "project": "#FF6600"
  }
}

支持的取值：命名颜色（

dim

red

green

yellow

magenta

cyan

brightBlue

brightMagenta

）、256色编号（

0-255

）或十六进制颜色码（

#rrggbb

）。

json

{
  "colors": {
    "context": "#00FF88",
    "model": "208",
    "project": "#FF6600"
  }
}

How It Works

工作原理

Claude HUD uses Claude Code's native statusline API — no separate window, no tmux needed:

Claude Code → stdin JSON → claude-hud → stdout → terminal statusline
           ↘ transcript JSONL (tools, agents, todos parsed live)

Token data comes directly from Claude Code (not estimated)
Scales with reported context window size including 1M-context sessions
Parses transcript for tool/agent activity
Updates every ~300ms

Claude HUD使用Claude Code原生的statusline API——无需额外窗口，无需tmux：

Claude Code → stdin JSON → claude-hud → stdout → terminal statusline
           ↘ transcript JSONL（实时解析工具、Agent、待办事项）

Token数据直接来自Claude Code（非估算值）
支持报告的所有上下文窗口大小，包括1M上下文会话
解析对话记录以获取工具/Agent活动信息
每约300ms更新一次

Common Patterns

常用配置方案

Minimal setup for focused work

专注工作的极简配置

json

{
  "lineLayout": "compact",
  "display": {
    "showModel": true,
    "showContextBar": true,
    "contextValue": "percent",
    "showUsage": false,
    "showTools": false,
    "showAgents": false,
    "showTodos": false
  }
}

json

{
  "lineLayout": "compact",
  "display": {
    "showModel": true,
    "showContextBar": true,
    "contextValue": "percent",
    "showUsage": false,
    "showTools": false,
    "showAgents": false,
    "showTodos": false
  }
}

Full monitoring setup

全面监控配置

json

{
  "lineLayout": "expanded",
  "pathLevels": 2,
  "gitStatus": {
    "enabled": true,
    "showDirty": true,
    "showAheadBehind": true,
    "showFileStats": true
  },
  "display": {
    "showTools": true,
    "showAgents": true,
    "showTodos": true,
    "showDuration": true,
    "showMemoryUsage": true,
    "showConfigCounts": true,
    "contextValue": "both",
    "showTokenBreakdown": true
  }
}

json

{
  "lineLayout": "expanded",
  "pathLevels": 2,
  "gitStatus": {
    "enabled": true,
    "showDirty": true,
    "showAheadBehind": true,
    "showFileStats": true
  },
  "display": {
    "showTools": true,
    "showAgents": true,
    "showTodos": true,
    "showDuration": true,
    "showMemoryUsage": true,
    "showConfigCounts": true,
    "contextValue": "both",
    "showTokenBreakdown": true
  }
}

Always show 7-day usage

始终显示7天使用情况

json

{
  "display": {
    "showUsage": true,
    "sevenDayThreshold": 0
  }
}

Output:

Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h) | ██████████ 85% (2d / 7d)

json

{
  "display": {
    "showUsage": true,
    "sevenDayThreshold": 0
  }
}

输出示例：

Context █████░░░░░ 45% │ Usage ██░░░░░░░░ 25% (1h 30m / 5h) | ██████████ 85% (2d / 7d)

Troubleshooting

常见问题排查

HUD not appearing after setup

Fully restart Claude Code (quit and re-run
```
claude
```
in terminal)
On macOS, ensure you've fully quit the app, not just closed the window

Config not applying

Check for JSON syntax errors — invalid JSON silently falls back to defaults

Validate:

cat ~/.claude/plugins/claude-hud/config.json | node -e "JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'))"

Delete config and run
```
/claude-hud:configure
```
to regenerate

Git status missing

Verify you're in a git repository (
```
git status
```
)
Ensure
```
gitStatus.enabled
```
is not
```
false
```
in config

Tool/agent/todo lines not showing

These are hidden by default — enable with
```
showTools
```
,
```
showAgents
```
,
```
showTodos
```
Lines only render when there's active activity to display

Usage limits not showing

Requires a Claude subscriber account (not API key only)
AWS Bedrock users see
```
Bedrock
```
label; usage is managed in AWS console instead
Usage data may be empty until after the first model response in a new session
Older Claude Code versions that don't emit
```
rate_limits
```
won't show subscriber usage

Linux cross-device error on install

bash

mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude

设置后HUD未显示

完全重启Claude Code（退出后重新在终端运行
```
claude
```
命令）
在macOS上，确保完全退出应用，而不仅仅是关闭窗口

配置未生效

检查JSON语法错误——无效的JSON会自动回退到默认配置

验证命令：

cat ~/.claude/plugins/claude-hud/config.json | node -e "JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'))"

删除配置文件后运行
```
/claude-hud:configure
```
重新生成

Git状态未显示

确认当前目录是Git仓库（运行
```
git status
```
检查）
确保配置中
```
gitStatus.enabled
```
不为
```
false
```

工具/Agent/待办事项行未显示

这些内容默认隐藏——需通过
```
showTools
```
、
```
showAgents
```
、
```
showTodos
```
启用
仅当存在相关活动时才会显示对应行

使用限额未显示

需要Claude订阅用户账户（仅API密钥无法使用此功能）
AWS Bedrock用户会看到
```
Bedrock
```
标签；使用情况需在AWS控制台中查看
新会话中需等待首次模型响应后才会显示使用数据
旧版本Claude Code若不输出
```
rate_limits
```
信息，则无法显示订阅用户的使用情况

Linux安装时出现跨设备错误

bash

mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude

Then run /plugin install claude-hud inside that session

然后在该会话中运行/plugin install claude-hud


**Windows: no JavaScript runtime found**
```powershell
winget install OpenJS.NodeJS.LTS


**Windows：未找到JavaScript运行时**
```powershell
winget install OpenJS.NodeJS.LTS

Restart shell, then run /claude-hud:setup again

重启终端后，重新运行/claude-hud:setup

undefined

undefined

Plugin Commands Reference

插件命令参考

Command	Description
`/plugin marketplace add jarrodwatts/claude-hud`	Register the plugin source
`/plugin install claude-hud`	Install the plugin
`/claude-hud:setup`	Initial setup wizard, writes `statusLine` config
`/claude-hud:configure`	Interactive configuration with preview

命令	说明
`/plugin marketplace add jarrodwatts/claude-hud`	注册插件源
`/plugin install claude-hud`	安装插件
`/claude-hud:setup`	初始设置向导，写入 `statusLine` 配置
`/claude-hud:configure`	带预览的交互式配置

Config File Location

配置文件位置

~/.claude/plugins/claude-hud/config.json

~/.claude/plugins/claude-hud/config.json