Перейти к содержимому
Headroom
GitHub
ENRU

Установка Headroom

Одна команда на Linux, одна на macOS. Остальное на этой странице — на случай, если понадобится.

Последний релиз0.6.126 сентября 2026 г.Что нового

Запустите установщик

curl -fsSL https://github.com/daniarjabagin/headroom/releases/latest/download/get-headroom.sh | sh

Он ставит в ~/.local статическую сборку под ваш процессор, фоновую службу и то, что нужно вашему рабочему столу: расширение GNOME, виджет Plasma или трей Headroom на любом другом. Права root не нужны.

SHA256SUMS релиза подписан ключом Ed25519, который встроен в установщик и в headroom update. Установщик проверяет подпись через OpenSSL 1.1.1 или новее, а затем сверяет с контрольными суммами каждую загрузку. Если такого OpenSSL нет, он предупредит и обойдётся одними контрольными суммами.

Лишнее можно пропустить: добавьте после sh флаги -s -- --no-gnome, --no-plasma или --no-service (только программа). --tray ставит трей в любом случае, --no-tray — не ставит.

Нужноx86_64 или aarch64пользовательский сеанс systemd и D-BusWayland или X11GNOME 46–50KDE Plasma 6.2+любой системный трей: GTK 4.14+, libadwaita 1.5+Waybar

Добавьте в панель

Службу установщик настроит сам, а трей поставит там, где он нужен. Остальное зависит от рабочего стола.

GNOME

В Wayland один раз выйдите из сеанса и войдите снова, чтобы GNOME Shell увидел новое расширение. Затем включите его:

gnome-extensions enable headroom@daniarjabagin.github.io

KDE Plasma

Откройте обзор виджетов из контекстного меню панели и добавьте на панель Headroom.

Другие рабочие столыТрей Headroom

В Xfce, Cinnamon, MATE, Budgie, LXQt, COSMIC, Hyprland, Sway, niri, river, labwc, Wayfire и на любом другом рабочем столе с системным треем установщик добавит headroom-tray и запустит его. Кольцо Headroom появится в трее: левый щелчок открывает то же окно, что в GNOME и Plasma, правый — меню «Открыть Headroom», «Обновить сейчас», «Настройки…» и «Выйти».

  • Рабочие столы запускают его при каждом входе через автозапуск; он есть и в меню приложений.
  • Если установлен gtk4-layer-shell, в Sway, Hyprland, niri, river, labwc и Wayfire окно открывается у панели, без него — по центру. В X11 оно открывается у значка в трее.
  • Waybar нужен модуль tray. swaybar открывает окно по щелчку, но без меню по правому щелчку.

Тайловые оконные менеджеры запускают его из своего конфига:

sway / i3 config
exec headroom-tray
hyprland.conf
exec-once = headroom-tray

Повесьте на клавишу, чтобы открывать окно и без трея:

headroom-tray --toggle

Или задайте глобальное сочетание клавиш в «Настройки → Общие» трея. В Wayland оно работает через портал GlobalShortcuts, если композитор его поддерживает, в X11 — через перехват клавиш.

i3bar, polybar, tint2 и другие треи X11, которые понимают только XEmbed, покажут его через snixembed. Запустите его раньше headroom-tray:

snixembed --fork

Waybar

headroom waybar выдаёт по строке JSON на каждое изменение, с классом good, warning, critical или neutral. Добавьте модуль в конфиг и в один из списков modules-*:

config.jsonc
"custom/headroom": {
    "exec": "headroom waybar",
    "return-type": "json",
    "format": "{text}",
    "tooltip": true
}

Несколько провайдеров помещаются в один модуль: --providers показывает по значению на провайдера, --window session|weekly|any выбирает окно лимита, а --labels none убирает названия.

headroom waybar --providers claude,codex

Цвета для классов, если хочется:

style.css
#custom-headroom.warning  { color: #ffd60a; }
#custom-headroom.critical { color: #ff453a; }
#custom-headroom.neutral  { opacity: 0.6; }

Другие способы

Пакеты: .deb, .rpm, Arch Linux

В каждом релизе есть пакеты для x86_64 и aarch64. Они ставят в систему /usr/bin/headroom, пользовательскую службу, расширение GNOME и виджет Plasma.

Debian, Ubuntu
sudo apt install ./headroom_*_amd64.deb
Fedora
sudo dnf install ./headroom-*.x86_64.rpm
openSUSE
sudo zypper install ./headroom-*.x86_64.rpm
Arch Linux
sudo pacman -U ./headroom-*-x86_64.pkg.tar.zst

Затем от своего пользователя запустите службу и, в GNOME, включите расширение:

sh
systemctl --user enable --now headroom.service
gnome-extensions enable headroom@daniarjabagin.github.io

Сверьте загруженный файл с SHA256SUMS или проверьте его аттестацию сборки через GitHub CLI:

sha256sum -c SHA256SUMS --ignore-missing
gh attestation verify <file> --repo daniarjabagin/headroom

Сам SHA256SUMS подписан ключом релизов Headroom. Сохраните ключ рядом и проверьте подпись:

sh
openssl base64 -d -A -in SHA256SUMS.sig -out SHA256SUMS.sig.raw
openssl pkeyutl -verify -rawin -pubin -inkey release-signing-key.pub.pem -in SHA256SUMS -sigfile SHA256SUMS.sig.raw
Ключ релизов Headroom
Пакеты трея Headroom

Для рабочих столов, кроме GNOME и Plasma, добавьте пакет headroom-tray из того же релиза. Ему нужны пакет headroom, GTK 4.14 и libadwaita 1.5 или новее. Пакеты .rpm и для Arch собраны с gtk4-layer-shell и открывают окно у панели.

Debian, Ubuntu
sudo apt install ./headroom-tray_*_amd64.deb
Fedora
sudo dnf install ./headroom-tray-*.x86_64.rpm
Arch Linux
sudo pacman -U ./headroom-tray-*-x86_64.pkg.tar.zst

Пакет ставит /usr/bin/headroom-tray, пункт меню и /etc/xdg/autostart/headroom-tray.desktop: трей запускается при входе везде, кроме GNOME Shell и Plasma.

Архив со статической сборкой

Тот же архив, что скачивает установщик. Распакуйте его и запустите ./install.sh внутри; флаги те же: --no-gnome, --no-plasma и --no-service.

Сборка из исходников

Нужен Rust 1.98, а для расширения GNOME ещё gnome-extensions, glib-compile-schemas и python3. В клоне репозитория:

sh
git clone https://github.com/daniarjabagin/headroom.git
cd headroom
packaging/install.sh

С флагом --tray скрипт соберёт и поставит ещё и трей Headroom.

Виджет Plasma ставится отдельно:

make -C shell/plasma install

Установите через Homebrew

brew install --cask daniarjabagin/tap/headroom

Cask ставит универсальное приложение и снимает флаг карантина, поэтому Headroom открывается с первого раза, без шагов Gatekeeper.

НужноmacOS 14 Sonoma или новееApple silicon или Intel
Скачать DMG

Скачайте универсальный DMG, откройте его и перетащите Headroom в Программы.

СкачатьHeadroom-0.6.1-universal.dmg16,3 МБ

Приложение пока не прошло нотаризацию, поэтому первый запуск macOS заблокирует:

  1. Откройте Headroom один раз и нажмите «Готово» в предупреждении.
  2. Зайдите в «Системные настройки → Конфиденциальность и безопасность», нажмите «Всё равно открыть» и подтвердите паролем или Touch ID.

Или снимите флаг карантина в Терминале и откройте приложение как обычно:

xattr -dr com.apple.quarantine /Applications/Headroom.app
Собрать самому

Для сборки нужен Xcode со Swift 6. В руководстве по macOS — сборка, файлы, логи и решение проблем.

Руководство по macOS

Размер и нагрузка

Демону в простое нужно ≈15 МБ памяти, короткие пики бывают, когда он перечитывает логи или прайс-листы. Трей с открытым окном занимает ~0,5 % одного ядра вместе с анимацией полосок лимитов, а со скрытым окном — ≈0 %. Окно GNOME ничего не делает, пока закрыто.

Релиз 0.6.1: headroom 12,2 МБ (deb 6,0 МБ, x86_64) · трей 4,6 МБ (deb 2,2 МБ) · DMG для macOS 15,6 МБ · расширение GNOME 248 КБ · виджет Plasma 176 КБ

Первый запуск

При первом запуске Headroom покажет, что нашёл: инструменты, в которые вы уже вошли, у каждого свой переключатель, «Войти» для установленных, но без входа, и где теперь живёт Headroom.

  • GNOME и трей Headroom — окно «Добро пожаловать в Headroom».
  • KDE Plasma — баннер в окне виджета.
  • macOS — первый шаг окна приветствия.

При обновлении с прошлой версии этот шаг пропускается.

Окно «Добро пожаловать в Headroom» в GNOME: найденные провайдеры с переключателями, неустановленные инструменты, добавление аккаунта, кнопки «Начать» и «Выбрать позже»

Войдите один раз

Уже вошли в codex или claude? Эти аккаунты Headroom найдёт сам. Для других провайдеров откройте в окне «Настройки → Аккаунты → Добавить аккаунт…» или добавьте аккаунт из терминала:

headroom accounts add openrouter

headroom providers покажет все провайдеры и то, как добавить аккаунт для каждого.

Если истёк вход в CLI, кнопка «Войти» на карточке откроет терминал с входом этого CLI. Команда запускается через вашу оболочку, поэтому CLI найдётся в привычном PATH (на macOS — в Terminal). Новый вход Headroom подхватит сам. У аккаунтов, добавленных через Headroom, вместо неё — «Войти снова…».

Из терминала войти снова в аккаунт любого вида можно командой headroom accounts login <id>, id есть в headroom accounts.

Страница настроек «Аккаунты» устроена как на macOS: слева список, справа подробности. Выберите аккаунт, чтобы скрыть или показать его, отметить звёздочкой, переименовать, скрыть отдельные лимиты, передвинуть, войти снова или удалить.

На macOS консольная утилита лежит внутри приложения: /Applications/Headroom.app/Contents/Helpers/headroom.

Проверьте, что всё работает

headroom status выводит все лимиты и расходы. Если служба не запущена, покажет последние сохранённые данные.

headroom status

Нашли ошибку? headroom diagnostics выводит версии, платформу, настройки журнала и состояние аккаунтов — без токенов, почты и id аккаунтов.

$ headroom statusClaude · work@example.com Max 5x Session ━━━━━━━━━━━━━━━━━━━─ 95% left resets in 4h 35m Weekly ━━━━━━━━━━━━━──┃──── 66% left resets in 5d 7h limit in 3d 6h Codex · work@example.com Pro Weekly ━━━━━━━━━━━━━━━━━━━━ 99% left resets in 5d 22h Spend estimated from local logs Today $9.69 9.8M tokens Yesterday $30.46 87M tokens 30 days $285.74 290M tokens
Пример вывода headroom status

Обновления

Раз в день Headroom спрашивает у GitHub, не вышел ли новый релиз. Больше ничего не отправляется, а проверку можно выключить в настройках.

Linux

  • Когда выходит релиз, в окне Headroom появляется «Доступна версия Headroom X».
  • В настройках видно, когда была последняя проверка, а «Проверить сейчас» проверит сразу: в настройках GNOME и Plasma и на странице «О программе» трея.
  • Поставили установщиком — нажмите «Обновить» или выполните headroom update. Он проверит подпись Ed25519 у SHA256SUMS встроенным в Headroom ключом, сверит загрузку и повторит установку с теми же параметрами, что и в первый раз, вместе с треем Headroom.
  • Поставили из пакета — «Как обновить» подскажет, что делать. Скачайте новые пакеты со страницы релиза, headroom-tray тоже, если пользуетесь им, и установите так же, как первые.
  • Собрали из исходников — обновите клон и снова запустите packaging/install.sh.
  • headroom update --check сравнит вашу версию с последним релизом и ничего не установит.

macOS

  • Приложение обновляется само через Sparkle и проверяет подпись EdDSA у каждого обновления.
  • Правый щелчок по значку в строке меню → «Проверить обновления…» — проверка сразу.
  • Если ставили через Homebrew, подойдёт и brew upgrade --cask --greedy headroom.

Удаление

Сохранённая статистика и добавленные аккаунты остаются, пока вы не удалите их отдельно.

Linux

Поставили установщиком — запустите uninstall.sh из архива релиза. Он остановит службу и трей и удалит программу, трей, расширение и виджет.

sh
curl -fsSL https://github.com/daniarjabagin/headroom/releases/download/v0.6.1/headroom-0.6.1-$(uname -m)-linux-musl.tar.gz | tar -xz
bash headroom-0.6.1-$(uname -m)-linux-musl/uninstall.sh

Поставили из пакетов — сначала удалите headroom-tray, если добавляли его.

Debian, Ubuntu
sudo apt remove headroom-tray
Fedora
sudo dnf remove headroom-tray
Arch Linux
sudo pacman -R headroom-tray

Затем остановите службу и удалите пакет:

systemctl --user disable --now headroom.service
Debian, Ubuntu
sudo apt remove headroom
Fedora
sudo dnf remove headroom
openSUSE
sudo zypper remove headroom
Arch Linux
sudo pacman -R headroom

Удалить и данные:

rm -rf ~/.local/state/headroom ~/.cache/headroom ~/.local/share/headroom

macOS

brew uninstall --cask --zap headroom

Поставили через Homebrew — с --zap удалятся ещё настройки, логи и кэш. API-ключи останутся, пока вы не удалите их в приложении «Связка ключей».

Поставили из DMG — закройте Headroom через его меню и перенесите из «Программ» в Корзину.

Вопросы и ответы.

Коротко о том, что спрашивают первым делом.

Headroom бесплатный?

Да. Исходный код открыт под лицензией MIT; не входят в неё только название и логотип Headroom. Если он вам пригодился, поставьте звезду на GitHub — так его найдут другие.

На каких системах он работает?

У GNOME Shell 46–50 и KDE Plasma 6.2+ свои оболочки. Xfce, Cinnamon, MATE, Budgie, LXQt, Hyprland, Sway, niri, COSMIC и любому другому рабочему столу с системным треем достаётся трей Headroom, для Waybar есть модуль. x86_64 или aarch64, Wayland или X11. На Mac — macOS 14 Sonoma и новее, Apple silicon или Intel.

Он куда-нибудь отправляет мои данные?

Нет. Headroom обращается только к вашим провайдерам, берёт открытые прайс-листы и раз в день спрашивает у GitHub, не вышел ли новый релиз. Страницы статуса сервисов читаются, только если вы их включили. Телеметрии и своего сервера нет.

Что будет при первом запуске?

Откроется окно «Вот что мы нашли»: инструменты для кода, в которые вы вошли, с переключателем у каждого, и вход для тех, что установлены, но без входа. Нажмите «Начать» — или «Выбрать позже» и выберите в настройках.

Почему в карточке написано «Пауза»?

Прогноз для лимитов на сессию строится по темпу последнего отрезка активной работы. Когда Claude Code или Codex останавливаются, карточка пишет «Пауза · хватит ≈3 ч работы» — на сколько работы хватит остатка в том же темпе, вместо отсчёта до исчерпания, которого не будет. Недельные и более длинные лимиты считаются по среднему за окно.

Как запустить его на macOS?

После Homebrew выполните open -a Headroom — флаг карантина cask снимает сам. Окно приветствия покажет, где Headroom в строке меню, и предложит «Открывать при входе». Нотаризации пока нет, поэтому из DMG откройте приложение один раз, затем нажмите «Всё равно открыть» в «Системных настройках → Конфиденциальность и безопасность».

Как приходят обновления?

На Linux окно покажет «Доступна версия Headroom X». Если ставили одной командой, нажмите «Обновить» или выполните headroom update — трей обновится вместе со всем. Если из пакета, «Как обновить» подскажет, что делать. В настройках есть «Проверить сейчас». На macOS Sparkle обновляет приложение сам, а проверить сразу можно правым кликом по значку → «Проверить обновления…».

Видны ли цифры, когда я показываю экран?

В GNOME — нет: с включённым «Скрывать цифры при демонстрации экрана» (так по умолчанию) в панели остаётся только знак, а в окне — ••, пока демонстрация не закончится. На macOS окно и значки в строке меню не попадают в скриншоты, запись и демонстрацию экрана. Plasma и трей демонстрацию распознать не могут, поэтому такой настройки у них нет.

Что такое страницы статуса сервисов?

Проверка публичных страниц статуса Claude, Codex, Copilot, Cursor, Devin, Kimi Code, Moonshot API, MiniMax, Kilo Code, Warp и Poe, которую вы включаете сами. Если у вашего провайдера инцидент или сбой, карточка скажет об этом и даст ссылку на страницу. По умолчанию выключено.

Может ли скрипт проверить лимиты перед запуском агента?

Да. headroom guard --min 20 --window weekly возвращает 0, когда во всех проверенных недельных лимитах осталось не меньше 20 %, 1, когда какой-то ниже, и 2, когда свежих данных нет. Так headroom guard --min 15 && claude -p … запустит агента, только если запас есть.

Как добавить ещё аккаунт или провайдера?

В окне откройте «Настройки → Аккаунты → Добавить аккаунт…», выберите одного из 19 провайдеров и войдите или вставьте ключ. Из терминала — headroom accounts add с нужным провайдером, например codex.

Можно показать два аккаунта одного сервиса как один?

Да. Включите в настройках «Объединять аккаунты одного сервиса» — по умолчанию это выключено. В карточке появится полоса с сегментом на каждый аккаунт, ближайший сброс и общий прогноз темпа. Работает в GNOME, Plasma, трее и на macOS.

Что будет, если провайдер сломается?

Этот аккаунт покажет ошибку в окне, а остальные продолжат работать. Если провайдер лишь ограничил запросы, карточка сохранит последние цифры и тихую строку «повтор в …», а паузы между попытками растут от 5 до 60 минут. Если вход CLI истёк, «Войти» откроет терминал со входом самого CLI, и Headroom сам заметит, когда вы войдёте заново.