claude-hud — плагин, который превращает чёрный ящик Claude Code в приборную панель с контекстом, тулами и агентами

claude-hud — плагин, который превращает чёрный ящик Claude Code в приборную панель с контекстом, тулами и агентами

Кто работал с Claude Code больше часа, знает это чувство: терминал молчит, агент что-то делает, контекст куда-то утекает — а ты сидишь и гадаешь, не пора ли делать /compact. Jarrod Watts решил эту проблему за 271 коммит и получил 7 600 звёзд на GitHub за пару дней — сегодня claude-hud на первом месте в trending.

TL;DR: claude-hud — плагин для Claude Code, который добавляет в терминал статусбар с контекстом (процент + визуальная шкала), активными тулами, субагентами и прогрессом задач. Устанавливается тремя командами, обновляется каждые 300 мс, читает нативные данные Claude Code, а не оценки.

Что показывает

claude-hud выводит информацию прямо под строкой ввода Claude Code — без tmux, без отдельного окна, без лишних движений.

Первая строка — проект и контекст:

• Модель — какой моделью работает сессия: [Opus 4.6]
• Проект и git — папка проекта, ветка, dirty-статус, ahead/behind: my-project git:(main) +3 ~2
• Контекстная шкала — визуальный бар с цветовой кодировкой: зелёный до 50%, жёлтый до 80%, красный выше. Рядом — процент: ████░░░░░░ 19%
• Конфиги — сколько CLAUDE.md файлов, правил, MCP-серверов и хуков загружено: 2 CLAUDE.md | 8 rules | 6 MCPs

Вторая строка — rate limit:

• Потребление квоты Pro/Max/Team: 5-часовая и 7-дневная с процентами

Опциональные строки — активность:

• Тулы — спиннер с именем файла, пока Read/Edit/Bash работает: ⟳ Read src/index.ts, а после завершения — агрегация: ✓ TaskOutput ×2
• Агенты — тип субагента, описание задачи, прошедшее время: ✓ Explore: Research patterns (5s)
• Задачи — прогресс по todo-листу: ✓ All complete (5/5) или текущая задача

Зачем это нужно на практике — два сценария.

Сценарий 1: не потерять контекст. Запустил рефакторинг на 20 файлов, агент вызывает Read/Edit в цикле. Без HUD ты увидишь, что контекст закончился, только когда Claude начнёт писать ерунду. С HUD — видишь шкалу на 75% и делаешь /compact заранее.

Сценарий 2: дебаг мульти-агентных сессий. Запустил 3 субагента через Agent tool, один завис. Без HUD — гадаешь, работает он или нет. С HUD — видишь ⟳ Explore: analyzing codebase (45s) и понимаешь, что он ещё думает, а не залип.

Как установить

Три команды в Claude Code:

/plugin marketplace add jarrodwatts/claude-hud
/plugin install claude-hud
/claude-hud:setup

Перезапуск не нужен — HUD появляется сразу. Требуется Claude Code v1.0.80+ и Node.js 18+ (или Bun).

На Linux есть нюанс: если файловая система /tmp монтирована с noexec, нужно задать TMPDIR=~/.cache/tmp до установки.

Настройка

После установки можно вызвать интерактивный конфигуратор:

npx claude-hud-configure

Три готовых пресета:

• Full — все элементы включены: тулы, агенты, задачи, git-статистика
• Essential — активность и git, без rate limit
• Minimal — только модель и контекстный бар

Конфигурация лежит в ~/.claude/plugins/claude-hud/config.json. Можно менять порядок элементов через elementOrder, глубину пути через pathLevels (1-3 уровня директорий), цвета через colors.*, и каждый элемент включать/выключать отдельно.

Пример конфига для тех, кто хочет видеть всё:

{
  "lineLayout": "expanded",
  "pathLevels": 2,
  "elementOrder": ["project", "tools", "context", "usage", "agents", "todos"],
  "display": {
    "showTools": true,
    "showAgents": true,
    "showTodos": true,
    "showConfigCounts": true,
    "showDuration": true
  }
}

Как это работает внутри

Claude Code начиная с v1.0.80 поддерживает statusline API — встроенный механизм для кастомных статусбаров. Каждые ~300 мс Claude Code отправляет JSON с текущим состоянием сессии на stdin процесса, указанного в settings.json. Процесс читает JSON, форматирует и отправляет на stdout — терминал рисует результат.

Claude Code → stdin JSON → claude-hud → stdout → терминал
                             ↘ transcript JSONL (тулы, агенты, todos)

claude-hud делает две вещи параллельно: парсит JSON со stdin (контекст, модель, директория) и читает transcript JSONL файл сессии (для отслеживания tool_use/tool_result пар, агентов и todo-записей). Для rate limit — опционально дёргает OAuth API Anthropic через credentials из ~/.claude/.credentials.json, кэшируя ответ на 60 секунд.

Важный момент: это нативные данные Claude Code, не оценки. used_percentage — реальный процент контекстного окна, total_input_tokens и total_output_tokens — реальный расход. Никакой магии и приближений.

Подводные камни

Linux + noexec /tmp. Если /tmp смонтирован с флагом noexec (типичная история на hardened Linux-серверах), установка упадёт с неинформативной ошибкой. Фикс — export TMPDIR=~/.cache/tmp && mkdir -p $TMPDIR. В README это упоминается, но легко пропустить.

Нагрузка на API при включённом rate limit. claude-hud делает запросы к api.anthropic.com/api/oauth/usage каждые 60 секунд (настраивается через usage.cacheTtlSeconds). Если у вас несколько сессий Claude Code параллельно — каждая будет дёргать API отдельно. Для 2-3 сессий это не проблема, но при массовом использовании (CI/CD, batch-скрипты) — лучше выключить usage или увеличить TTL кэша.

Конфликт с oh-my-claudecode. Популярный бандл oh-my-claudecode (9.5K звёзд) включает собственный HUD. Если установить оба — они будут конкурировать за statusline. В Issues oh-my-claudecode уже есть баг-репорты от пользователей, у которых HUD не собрался. Выбирайте что-то одно.

Не работает в headless/CI-режиме. claude-hud полагается на statusline API, который работает только в интерактивном терминале. Если запускаете Claude Code через claude -p "prompt" (headless) — HUD просто не загрузится. Это не баг, а ограничение архитектуры.

Альтернативы

claude-office — фокус на деньгах, а не на активности. Показывает API-эквивалентную стоимость сессии (сегодня / неделя / месяц), ежемесячную экономию по сравнению с прямым API, и квоту плана. Построен на Bun без шага сборки. 5 звёзд — проект молодой, но подход уникальный: если вам важнее понимать, сколько вы тратите, а не что делает агент — это ваш вариант.

Super Simple Statusline — bash-скрипт на 30 строк, который через jq парсит stdin JSON и показывает модель, токены и контекстный бар. Никаких зависимостей, никакой установки плагинов — просто chmod +x и путь в settings.json. Идеально, если не хотите ставить Node.js-плагин ради статусбара.

Встроенный /statusline в Claude Code — начиная с актуальных версий можно написать /statusline show model name and context percentage with a progress bar, и Claude Code сам сгенерирует скрипт. Минимум усилий, но и минимум возможностей — ни тулов, ни агентов, ни rate limit.

Вердикт

Если используешь Claude Code ежедневно и запускаешь сессии дольше 20 минут — ставь claude-hud прямо сейчас, экономия нервов окупится за первый же рефакторинг. Контекстная шкала одна стоит всего плагина — видеть 78% и успеть сделать /compact до того, как агент начнёт галлюцинировать, бесценно. Если нужны только цифры затрат — смотри на claude-office. Если принципиально не хочешь ставить плагины — хватит bash-скрипта на 30 строк.

Как попробовать

1. Убедись, что Claude Code обновлён: claude update
2. Установи плагин: /plugin marketplace add jarrodwatts/claude-hud и затем /plugin install claude-hud
3. Запусти настройку: /claude-hud:setup
4. Для полной конфигурации: npx claude-hud-configure — выбери пресет Full
5. Попробуй запустить сложную задачу и следи за шкалой контекста — теперь /compact можно делать вовремя, а не наугад

Репозиторий: github.com/jarrodwatts/claude-hud — MIT лицензия, 7 600+ звёзд.