Claudraband: как приручить Claude Code и превратить его в постоянного CLI‑ассистента — VogueTech

Что нового

Claudraband — это надстройка над официальным TUI Claude Code (пакет @anthropic-ai/claude-code@2.1.96) для тех, кто живёт в терминале и редакторе.

Главные возможности:

Долгоживущие сессии Claude Code в контролируемом терминале (через tmux или экспериментальный xterm-бэкенд).
Возобновляемые неинтерактивные сценарии: можно вернуться к старому диалогу с Claude Code по session-id и задать новый вопрос.
HTTP-демон для удалённого и headless‑управления сессиями.
ACP‑сервер для интеграции с редакторами и альтернативными фронтендами (например, Toad и Zed).
TypeScript‑библиотека для встраивания этих сценариев в свои инструменты.

Claudraband не заменяет официальный SDK Anthropic и не обходит авторизацию. Он использует реальные сессии Claude Code, которые вы заранее авторизовали.

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

Claudraband запускает официальный TUI Claude Code внутри управляемого терминала:

по умолчанию — внутри tmux;
опционально — через экспериментальный xterm‑бэкенд (--backend xterm).

Поверх этого он:

отслеживает живые сессии в каталоге ~/.claudraband/;
даёт им стабильные идентификаторы (session-id);
позволяет к ним подключаться, продолжать диалог и закрывать их как локально, так и через демон.

Ключевые сущности:

CLI: бинарники claudraband и сокращение cband.
Демон (cband serve): HTTP‑сервер, который управляет сессиями, но под капотом всё равно крутит реальный Claude Code в терминале.
ACP‑сервер (cband acp): интерфейс для клиентов, которые умеют говорить по протоколу ACP (например, плагины редакторов).
TypeScript‑библиотека: даёт программный доступ к тем же сценариям, что и CLI.

Claudraband не трогает OAuth и не внедряется в протоколы Anthropic. Вы логинитесь в Claude Code как обычно, а Claudraband просто управляет его интерактивной сессией.

Что это значит для вас

Для кого полезен Claudraband:

Разработчики, живущие в терминале и Git. Можно запускать Claude Code на ревью коммитов, миграции, рефакторинг и возвращаться к этим сессиям позже.
Пользователи headless‑окружений (серверы, удалённые машины). Демон и xterm‑бэкенд позволяют держать Claude Code как сервис без GUI.
Авторы своих CLI/ботов/инструментов. TypeScript‑библиотека и ACP‑сервер упрощают интеграцию Claude Code в кастомные пайплайны.
Пользователи редакторов с ACP‑поддержкой (например, Toad, Zed). Можно использовать их интерфейс, но под капотом всё равно будет работать Claude Code через Claudraband.

Где Claudraband особенно уместен:

длинные исследовательские сессии, к которым вы возвращаетесь:
- «продолжи анализ прошлой миграции»;
- «что было в результатах того исследования?»;
код‑ревью и аудит изменений в репозитории;
сложные пошаговые задачи (миграции БД, рефакторинг больших модулей), которые вы делаете порциями.

Где он вряд ли нужен:

если вы довольны веб‑интерфейсом Claude Code и не хотите возиться с CLI и tmux;
если вам нужен именно SDK‑уровень (прямые вызовы API Anthropic без TUI).

Claudraband требует уже настроенный и авторизованный Claude Code. Если официальный клиент недоступен в вашей стране без VPN, то Claudraband сам по себе проблему не решит — он опирается на тот же доступ.

Место на рынке

Claudraband играет в другом сегменте, чем SDK от Anthropic или API от OpenAI:

SDK и HTTP‑API дают прямой программный доступ к моделям вроде Claude и GPT.
Claudraband, наоборот, оборачивает TUI Claude Code, не заменяя его.

В отличие от типичных CLI‑обёрток вокруг API:

Claudraband не делает свои запросы к Anthropic, а управляет уже запущенной сессией Claude Code;
он даёт сессионную модель поверх официального TUI: продолжение, attach/detach, HTTP‑демон, ACP.

Прямых конкурентов с тем же подходом (обёртка именно вокруг официального TUI Claude Code с tmux‑сессиями, ACP и демон‑режимом) в исходном описании нет. Claudraband занимает нишу инструмента для power‑user‑ов Claude Code, а не общего API‑клиента.

Установка

Требования

Для работы Claudraband нужны:

Node.js или Bun;
уже авторизованный Claude Code (официальный клиент от Anthropic);
tmux — для основного сценария с локальными и демон‑сессиями.

Установка и разовый запуск

Разовый запуск без глобальной установки:

# one-off
npx @halfwhey/claudraband " review the staged diff "

bunx @halfwhey/claudraband " review the staged diff "

Глобальная установка:

# install once
npm install -g @halfwhey/claudraband

Пакет ставит два бинарника: claudraband и сокращение cband. Рекомендуется использовать cband.

В комплекте поставляется Claude Code версии @anthropic-ai/claude-code@2.1.96. Если нужно подменить бинарник Claude Code, задайте переменную окружения:

export CLAUDRABAND_CLAUDE_PATH=/путь/к/своему/claude-code

Как запустить

Локальные постоянные сессии

Базовый сценарий: вы запускаете запрос к Claude Code, а потом возвращаетесь к нему по session-id.

cband " audit the last commit and tell me what looks risky "

cband sessions

cband continue <session-id> " keep going "

cband continue <session-id> --select 2

cband с текстом — запускает новую сессию Claude Code.
cband sessions — показывает список живых отслеживаемых сессий.
cband continue <session-id> — продолжает существующую сессию с новым запросом.
--select 2 — выбирает второй вариант ответа, если их несколько.

Демон и удалённые/headless‑сессии

Если нужно управлять Claude Code как сервисом, поднимите демон:

cband serve --host 127.0.0.1 --port 7842

cband --connect localhost:7842 " start a migration plan "

cband attach <session-id>

cband continue <session-id> --select 2

cband serve поднимает HTTP‑демон на 127.0.0.1:7842.
cband --connect создаёт новую сессию, привязанную к демону.
cband attach подключается к живой сессии.
cband continue продолжает её так же, как и в локальном сценарии.

Демон по умолчанию использует tmux как терминальный рантайм, как и локальный режим. Флаг --connect нужен только при создании новой демон‑сессии. Дальше команды continue, attach и sessions автоматически идут к «владельцу» сессии.

Экспериментальный xterm‑бэкенд

Для случаев, когда tmux недоступен или нужен чисто headless‑fallback, есть опция:

cband --backend xterm " some prompt "

Этот бэкенд:

работает и локально, и в режиме демона;
медленнее, чем tmux;
годится как запасной вариант, но не как основа для долгих интерактивных сессий.

Подробности по бэкендам и ограничениям — в docs/cli.md внутри репозитория.

ACP

Если вы хотите, чтобы другой инструмент управлял Claude через Claudraband, используйте ACP:

cband acp --model opus

# пример с Toad
uvx --from batrachian-toad toad acp 'cband acp -c "--model haiku"'

Claudraband умеет через ACP:

следовать за существующей сессией;
возобновлять её из внешнего клиента.

Поддержка ACP в редакторах и клиентах зависит от конкретного фронтенда, но Claudraband готов работать с ними из коробки.

Модель сессий

Claudraband хранит информацию о сессиях в каталоге ~/.claudraband/.

Базовые команды:

cband sessions — показывает список живых отслеживаемых сессий.
cband continue <session-id> — возобновляет существующую сессию Claude Code, даже если она уже не активна как живой терминальный процесс.
cband attach <session-id> — подключается только к живым сессиям.
cband sessions close ... — закрывает живые отслеживаемые сессии, и локальные, и те, которые работают через демон.

Один из показательных сценариев: вы даёте Claude задание, ждёте результатов, а потом просите его проанализировать собственные прошлые ответы в той же сессии и объяснить, почему он принял те или иные решения.

Интеграция с редакторами через ACP

Toad

Toad может использовать claudraband acp как альтернативный фронтенд для Claude Code. Интерфейс Toad общается с Claudraband по ACP, а тот управляет реальной панелью Claude Code под капотом.

Zed

Редактор Zed тоже умеет подключаться к Claude Code через claudraband acp. Сценарий аналогичный: вы видите интерфейс Zed, но все запросы проходят через Claudraband в реальную сессию Claude Code.

Библиотека и примеры кода

В репозитории Claudraband есть каталог examples/ с запускаемыми примерами на TypeScript. Они показывают, как:

создавать и отслеживать сессии Claude Code программно;
встраивать эти сессии в свои CLI и сервисы;
управлять демоном и ACP‑сервером из кода.

Для полного описания API используйте:

docs/library.md — подробности по TypeScript‑библиотеке;
docs/cli.md — все флаги и команды CLI;
docs/daemon-api.md — описание HTTP‑эндпоинтов демона.

Шпаргалка по командам

Сводка ключевых команд Claudraband:

# Разовый запуск через npx или bunx
npx @halfwhey/claudraband " review the staged diff "

bunx @halfwhey/claudraband " review the staged diff "

# Глобальная установка
npm install -g @halfwhey/claudraband

# Локальная сессия
cband " audit the last commit and tell me what looks risky "

# Список сессий
cband sessions

# Продолжить сессию
cband continue <session-id> " keep going "

# Выбрать второй вариант ответа
cband continue <session-id> --select 2

# Запуск демона
cband serve --host 127.0.0.1 --port 7842

# Создать сессию, привязанную к демону
cband --connect localhost:7842 " start a migration plan "

# Подключиться к живой сессии
cband attach <session-id>

# Продолжить сессию на демоне
cband continue <session-id> --select 2

# ACP‑режим с указанием модели
cband acp --model opus

# Пример интеграции с Toad через ACP
uvx --from batrachian-toad toad acp 'cband acp -c "--model haiku"'