agentbelt — боковая панель iTerm2 для AI-агентов кодинга

Если вы запускаете Claude Code или Codex прямо в терминале, то рано или поздно замечаете неудобство: агент работает, а вы смотрите на пустой экран и гадаете, что он там делает. Проект agentbelt добавляет в iTerm2 боковую панель, которая показывает сессии агентов, их действия в реальном времени, состояние git и PR, а также проверяет доступность AI API через ваши прокси.

Панель живёт в стандартном Toolbelt iTerm2 и следит за активной вкладкой: переключились на другой таб — сайдбар показывает данные именно его. Раньше проект назывался iterm-toolbelt; старые ссылки работают, а скрипт установки сам переносит существующую установку на новое имя.

Что показывают вкладки

Панель состоит из трёх рабочих вкладок и настроек:

Живая лента действий агента

Это, пожалуй, главная фишка. agentbelt находит процесс claude в активной вкладке, по его tty достаёт id сессии из файла ~/.claude/sessions/<pid>.json и читает транскрипт из ~/.claude/projects/<dir>/<id>.jsonl — только новые записи, без повторов. В итоге видно всё, что делает агент: какую команду выполнил, какой файл и как изменил (с диффом), куда сходил в веб, каких субагентов запустил. Ошибочные вызовы инструментов помечаются отдельно.

Сверху на этой вкладке есть сетевой блок. Он показывает, через какой прокси запущен текущий claude, и для каждого прокси из вашего списка — доходит ли через него каждый агент до своего API (claude → api.anthropic.com, codex → chatgpt.com или api.openai.com). У каждой строки — кнопки: скопировать готовую строку export HTTPS_PROXY=… в буфер обмена или запустить нового claude и codex в текущей папке через выбранный прокси. Список можно дополнить своими серверами с ping и проверкой SSH-доступности, а также туннелями роутера Keenetic.

Прокси для регионов с ограниченным доступом

Отдельная ценность для тех, кто работает там, где AI API заблокированы или ограничены. В docs/proxies.md разобрана готовая схема: небольшой HTTP-прокси с паролем на VPS (gost в Docker, поднимается за пять минут), подключение к нему Claude Code и Codex и защита от превращения в открытый прокси — через файл с секретами, allowlist на фаерволе или публикацию только внутри туннеля WireGuard или AmneziaWG.

Сам agentbelt дальше управляет списком прокси. Каждые 60 секунд он проверяет каждый из них запросом к тому эндпоинту, который реально вызывает соответствующий CLI. Ответ 401 (нет ключа) считается признаком доступности, 403 — признаком региональной блокировки. Агентов можно запускать прямо из панели — через рабочий прокси.

Установка

git clone https://github.com/vakovalskii/agentbelt ~/agentbelt
~/agentbelt/install.sh

Дальше в iTerm2:

1. Включите Python API: Settings → General → Magic → Enable Python API. При первом запуске iTerm2 спросит разрешение на скрипт.
2. Откройте View → Toolbelt и включите вкладки, начинающиеся с «◆». Переключение панели — ⌘⇧B.
3. Во вкладке Sessions нажмите ⚙ — там короткое введение и настройки запуска агентов, например прокси по умолчанию.

Нужны macOS, iTerm2 3.3+ (проверено на 3.7) и python3. Для данных о PR и CI нужен залогиненный gh CLI. Скрипт установки создаёт виртуальное окружение в ~/.config/agentbelt/venv, конфиг ~/.config/agentbelt/config.json и сервис LaunchAgent dev.agentbelt, который стартует при входе в систему и перезапускается после сбоев — например, если связь с iTerm2 API оборвалась после перезапуска терминала или пробуждения Mac. Обновление: git pull && ./install.sh. Удаление: ./uninstall.sh.

В простое сервис расходует около 90 МБ памяти и 0–3% CPU.

Как это устроено

Всё держится на одном Python-процессе:

• Локальный HTTP-сервер на 127.0.0.1 отдаёт страницы из папки pages/, а iTerm2 показывает их как вкладки Toolbelt через iterm2.tool.async_register_web_view_tool. Тот же iTerm2 Python API сообщает активную вкладку, её каталог и tty и открывает окна для возобновления сессий.
• Сессии четырёх агентов сканируются прямо из их стандартных папок: ~/.claude/projects/*/*.jsonl, ~/.codex/sessions/*/*/*/*.jsonl, ~/.pi/agent/sessions/*/*.jsonl и ~/.omp/agent/sessions/*/*.jsonl. Результаты кэшируются на диске: первый проход по паре тысяч сессий занимает десятки секунд в фоне, дальше читаются только изменённые файлы.
• Сеть: переменная HTTPS_PROXY читается из окружения работающего claude через ps eww. Прокси из конфига проверяются утилитой curl, при этом URL прокси передаётся через stdin, а не через аргументы команды, чтобы пароль не светился в списке процессов. Серверы из списка получают ping и проверку SSH-баннера. Если в настройках указан роутер Keenetic, сетевой блок показывает ещё и его WireGuard-туннели с состоянием ping-check, временем последнего рукопожатия и порядком резервирования.
• Безопасность: все запускающие эндпоинты принимают только POST с заголовком X-Toolbelt: 1, который чужая веб-страница отправить не может. Пароли прокси вообще не попадают на страницы — настройки получают замаскированные URL, а строка экспорта кладётся в буфер обмена самим сервисом.

Снапшоты окон

Вкладка Sessions умеет сохранять раскладку окон iTerm2: вкладки, сплиты, имена вкладок, каталоги и сессии агентов. Восстановление собирает всё заново в новом окне — включая cd в нужную папку и claude --resume в каждой панели.

Снапшоты хранятся в ~/.config/itermsnap/snaps/ в формате TermDeck, так что приложение TermDeck и панель видят одни и те же снимки. Есть автосохранение раз в 5 минут (включается строкой "autosave": true): срабатывает только при изменениях и запущенном агенте, хранятся последние 20 автоснапшотов, а последний удачный снимок не перезаписывается пустым, если все окна разом закрылись.

Тесты и конфигурация

Логика, не требующая запущенного iTerm2, покрыта тестами: маскирование секретов, чтение транскриптов, сканеры сессий всех четырёх агентов, определение запущенных агентов, команды запуска с прокси, сохранение настроек, сетевые проверки, разбор ответов Keenetic, снапшоты и защита HTTP-эндпоинтов. Тесты гоняются в GitHub Actions на каждый пуш; локально — python3 -m pytest -q tests.

Конфиг лежит в ~/.config/agentbelt/config.json с правами 600 — там может храниться прокси с паролем. Править его можно руками или прямо из панели:

{
  "agents": {
    "claude": {"prefix": "HTTPS_PROXY='http://user:pass@host:port'", "flags": "", "skip_permissions": true},
    "codex":  {"prefix": "", "flags": ""},
    "pi":     {"prefix": "", "flags": ""},
    "omp":    {"prefix": "", "flags": ""}
  },
  "open_in": "window",
  "repo_checks": [
    {"name": "Containers", "file": "docker-compose.yml", "cmd": "docker compose ps --format '{{.Name}} {{.State}}'", "max_lines": 6}
  ]
}

Блок repo_checks — собственные строки во вкладке Git & PR: если файл из поля file есть в корне репозитория, выполняется команда из поля cmd; код выхода 0 показывается зелёным, всё остальное — красным.

Дополнение к встроенной интеграции iTerm2

iTerm2 3.7 уже имеет свою интеграцию с Claude Code: инструмент Session Status, окно Cockpit, Workgroups с диффом и ревью, а в бете 3.7.4 — поддержку Codex. agentbelt не заменяет, а дополняет её: лента действий агента, браузер сессий четырёх CLI с возобновлением, снапшоты окон с восстановлением агентов и git/PR по активной вкладке. Лицензия проекта — MIT.