██████╗ ███████╗ █████╗ ██████╗ ███████╗    ██╗  ██╗██╗   ██╗██████╗
██╔══██╗██╔════╝██╔══██╗██╔══██╗██╔════╝    ██║  ██║██║   ██║██╔══██╗
██████╔╝█████╗  ███████║██║  ██║███████╗    ███████║██║   ██║██║  ██║
██╔══██╗██╔══╝  ██╔══██║██║  ██║╚════██║    ██╔══██║██║   ██║██║  ██║
██████╔╝███████╗██║  ██║██████╔╝███████║    ██║  ██║╚██████╔╝██████╔╝
╚═════╝ ╚══════╝╚═╝  ╚═╝╚═════╝ ╚══════╝    ╚═╝  ╚═╝ ╚═════╝ ╚═════╝

Доска задач beads и документов проекта на localhost — и строка статуса Claude Code, которая держит на неё живую ссылку.

Что это

Терминал плохо отвечает на два вопроса: что написано в планах этого проекта и как задачи связаны между собой. bd list печатает плоский список, и связь задачи с эпиком теряется в нём первой.

beads-hud отвечает на оба и ставит ответ туда, куда вы и так смотрите:

• строка статуса всегда на виду — сколько задач готово к работе, сколько ждут, сколько занято контекста и денег, и живая ссылка на доску;
• доска по этой ссылке — задачи в четырёх колонках по статусу и все .md файлы проекта, читаемые и правимые на месте.

Одно и другое нужны друг другу: строка знает, что доска поднята для этой папки, а хук поднимает её сам при старте сессии.

⏽ beads-hud http://127.0.0.1:7777 │ bd 20 готово · 2 в работе · 5 ждут │ ctx 43% │ 5ч 38% 1ч19м │ нед 8% │ $34.34 │ Opus 5·1M xhigh

| Сегмент | Что означает | |---|---| | ⏽ beads-hud <адрес> | Доска поднята, адрес — рабочая ссылка (OSC 8). Погасший ⏻ без адреса — сервер не запущен | | bd 20 готово | Задачи из ближайшей .beads вверх по дереву. «в работе» и «ждут» появляются, только когда не ноль | | ctx 43% | Заполнение окна контекста | | 5ч 38% 1ч19м | Пятичасовой лимит и сколько до сброса | | нед 8% | Недельный лимит | | $34.34 | Стоимость сессии | | Opus 5·1M xhigh | Модель и уровень усилий |

Зелёный до 60%, янтарный от 60%, красный от 85%. Все числа, кроме беадсовых, Claude Code сам подаёт строке на вход — ничего не угадывается и не опрашивается.

Установка

npm i -g @roflochinsky/beads-hud
beads-hud install

Вторая команда прописывает в ~/.claude/settings.json строку статуса и хук автозапуска. Она показывает, что изменит, кладёт рядом копию прежнего файла и не забирает чужую строку статуса молча: если там уже что-то не наше — остановится и скажет. Существующие хуки не трогает, свой дописывает рядом.

beads-hud install --dry-run    # показать, что изменится, и выйти
beads-hud install --project    # в .claude/settings.json текущего проекта
beads-hud install --force      # заменить чужую строку статуса
beads-hud uninstall            # убрать только своё

Строка появится в следующей сессии: Claude Code читает настройки при старте. Проверить, что скрипт работает, можно не выходя из текущей:

echo '{"model":{"display_name":"Opus 5"},"context_window":{"used_percentage":10},"cost":{"total_cost_usd":0},"cwd":"'"$PWD"'"}' | beads-hud-statusline

Обе настройки живут в ~/.claude/settings.json (для одного проекта — в .claude/settings.json внутри него):

{
  "statusLine": {
    "type": "command",
    "command": "beads-hud-statusline"
  },
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "beads-hud-up", "timeout": 10 }
        ]
      }
    ]
  }
}

[!NOTE] Файла может не быть — создайте. Если он есть, добавьте недостающие ключи, а не перезаписывайте: statusLine в Claude Code один, и ваш прежний он заменит.

Доска

Открывается по ссылке из строки. Адрес всегда один — http://127.0.0.1:7777, сервер многопроектный: папка выбирается в интерфейсе, а не портом.

Задачи

Колонки по статусам beads: открыто, в работе, заблокировано, закрыто. Карточку можно перетащить: в «в работе» — задача берётся в работу, в «закрыто» — закрывается, обратно в «открыто» — переоткрывается. Колонка «заблокировано» перенос не принимает: блокировка задаётся зависимостями, а не рукой.

Клик по карточке открывает задачу: описание, замысел и кликабельные связи — что её держит, что держит она, кто её дети, какие документы на неё ссылаются.

Слева — виды работ: все задачи, без эпика, эпики (каждый отдельной строкой), фичи, баги, верификация, прочее. Вид сам по себе является местом назначения: все баги в одном месте, все фичи в одном.

Документы

Все .md проекта, разложенные канбаном — по папкам или по работе, которая на них ссылается. Зелёный огонёк на карточке означает, что на документ ссылается хотя бы одна задача; серый — что документ не привязан ни к чему.

Чтение и правка

Документ открывается с человеческой типографикой — засечные заголовки, колонка не шире 780px, таблицы, код, цитаты, картинки.

Правится он на месте: клик по абзацу превращает его в исходный markdown.

Ctrl+Enter сохраняет, Esc отменяет, пустая правка удаляет абзац. Всё, что вне правимого абзаца, остаётся в файле байт в байт: сервер режет документ на блоки со смещениями и вклеивает правку по ним.

Тёмная по умолчанию, светлая по кнопке внизу рейки. Обе собраны из одного набора токенов.

| Клавиша | Действие | |---|---| | n | Новая задача | | Ctrl+Enter | Сохранить абзац | | Esc | Закрыть форму, отменить правку, закрыть задачу, выйти из документа |

Как это работает

| Часть | Роль | |---|---| | beads-hud | Сервер доски. Работает, пока его не остановят | | beads-hud-up | Хук SessionStart. Если сервер жив — молчит и ничего не дублирует | | beads-hud-statusline | Строка статуса. Чистый sh плюс jq, около 20 мс на отрисовку | | beads-hud-open | Открывает браузер: wslview, затем xdg-open, затем powershell.exe | | beads-hud install | Прописывает строку статуса и хук в настройки Claude Code; uninstall убирает только своё | | ~/.cache/beads-hud/server.json | Состояние сервера: адрес и pid | | ~/.cache/beads-hud/bd-*.json | Кэш беадсовых чисел для строки |

Единственный источник правды — база beads. Своего состояния beads-hud не хранит. Пишет только через bd: создать, закрыть, взять в работу, переоткрыть. Файлы .md пишет напрямую и строго внутри выбранного проекта.

| Источник | Что берёт | |---|---| | bd list --json | Задачи, статусы, приоритеты, типы | | bd graph --all --json | Связи: parent-child и blocks | | bd stats --json | Числа для строки статуса | | Файлы .md проекта | Документы; пропускает node_modules, .git, dist и скрытые каталоги |

Проекты ищутся в ~/code и в домашнем каталоге: папка попадает в список, если в ней есть .git, .beads или хотя бы один .md. За пределы домашнего каталога сервер не ходит.

bd stats занимает около 0.4 секунды — непозволительно много для того, что перерисовывается каждый ход. Строка печатает кэш и, если ему больше 30 секунд, отцепляет обновление себе за спину. Демона нет: обновление живёт ровно столько, сколько одна команда. Пока кэша нет — сегмента нет, а не ноль вместо числа.

Документы и задачи приходят раздельно. На большом проекте (384 задачи, 174 файла) документы открыты через 0.6 секунды, а задачи считаются ещё четырнадцать — и всё это время можно читать, а не смотреть в пустоту. Пока задачи не пришли, доска говорит об этом прямо.

cd /путь/к/проекту
beads-hud            # или: node /путь/к/beads-hud/server.mjs

| Переменная | Что делает | |---|---| | BEADS_HUD_PORT | Порт вместо 7777 | | BEADS_HUD_NO_OPEN=1 | Не открывать браузер при автозапуске |

Браузер открывается сам, когда хук действительно поднял сервер; если сервер уже работал, вкладка не открывается. Вручную — beads-hud-open.

Кликать ссылку в статус-строке не стоит: её рисует интерфейс Claude Code, а VS Code ищет ссылки в обычном выводе терминала.

Требования

• Node ≥ 22
• bd в PATH — источник задач
• jq в PATH — строку статуса рисует shell, а не Node: пустой запуск Node занимает 36 мс, вся отрисовка на sh — 20 мс
• POSIX-шелл: Linux, macOS, WSL

[!WARNING] В нативной Windows строка статуса работать не будет — beads-hud-statusline это shell-скрипт. Доска и сервер работают везде, где есть Node.

В рантайме одна зависимость — marked. Шрифты лежат в public/fonts и раздаются локально, интернет не нужен: Golos Text на интерфейс, Source Serif 4 на заголовки и чтение, JetBrains Mono на идентификаторы и код.

Известное ограничение

bd graph --all --json отдаёт связи только по открытым задачам. Поэтому у закрытой задачи не видно блокировок, а эпик, все дети которого закрыты, теряет детей в интерфейсе.

Лицензия

MIT