Чек-лист установки

English version: 05-installation-checklist.md. Этот файл — русский дубликат; обновляется вместе с 05-installation-checklist.md.

От чистой машины до запущенного демона, его dashboard и первого проекта, с проверкой после каждого шага. Чтобы вместо этого запустить Binnacle в контейнере приложения, см. Binnacle в контейнере; чтобы разрабатывать его из checkout — CONTRIBUTING.ru.md.

1. Что нужно заранее

Инструмент	Для чего	Проверка
Node.js 24	На нём работает Binnacle	node --version
npm	Установка Binnacle; Context7 и ast-grep	npm --version
Git	Любой проект	git --version
uv	Опционально: Serena и Graphify	uv --version

npm поставляется вместе с Node.js. binn init никогда не ставит uv; без него он называет команду, которая его ставит, и оставляет Serena и Graphify вне плана (Внешние инструменты). Remote на GitHub или GitLab рекомендуется, но локального Git достаточно.

2. Установить Binnacle

npm i -g @it-bbox/binnacle
binn --version

binn --version печатает установленную версию, например 0.1.0. Один пакет содержит binn, его демон binnd, dashboard и плагин binnacle, без зависимостей, которые надо скачивать (ADR-0044). Он работает в Linux, macOS и Windows.

Чтобы разово посмотреть без установки, например binn audit, выполните npx -p @it-bbox/binnacle binn audit. Без -p npx запустил бы чужой пакет с именем binn. Остальной чек-лист предполагает установку.

3. Запустить демон

binn daemon start
binn daemon status

binn daemon status говорит, что демон запущен, печатает его address, по умолчанию http://127.0.0.1:7717, и включён ли автозапуск. На один домашний каталог Binnacle работает один демон; binn daemon stop его останавливает.

Чтобы демон запускался при входе в систему, binn init спрашивает об этом, по умолчанию да, а binn daemon autostart on включает автозапуск в любой момент (ADR-0043). Он идёт через ваш собственный менеджер служб:

Платформа	Служба
Linux	пользовательский unit systemd
macOS	LaunchAgent
Windows	задача Планировщика заданий при входе

binn daemon autostart off выключает его. binn daemon autostart без аргумента говорит, включён ли автозапуск, выключен или сломан, и для какого домашнего каталога Binnacle.

Служба запускает демон только с BINNACLE_HOME и PATH, поэтому токен tracker, который лежит в вашей оболочке, BINNACLE_GITHUB_TOKEN или BINNACLE_GITLAB_TOKEN, до него не доходит. Если binn daemon autostart on ставит или чинит службу, или binn init включает её, когда такая переменная задана, а в credentials.json нет токена для этого tracker, команда предупреждает об этом, а binn init повторяет предупреждение в своём Summary. Положите токен в файл учётных данных, как сказано в разделе Учётные данные tracker. Предупреждение называет переменную и ключ файла, но не сам токен, и Binnacle никуда токен не копирует.

4. Открыть dashboard

binn dashboard

Команда открывает dashboard, уже авторизованный, в браузере по умолчанию и печатает его адрес без токена. binn dashboard --print печатает адрес с токеном и ничего не открывает. После первого раза обычный адрес работает в этом браузере как закладка.

5. Настроить проект

В Git-репозитории выполните binn init: один план всего, что он настраивает, с одним подтверждением. Затем проверьте:

binn project list
binn call project_detect

Первая команда показывает репозиторий в списке; вторая печатает его таким, каким его видят MCP-инструменты Binnacle. Если демон остановлен, init оставляет регистрацию вне плана, и её добавляет binn project register. Что настраивает init, шаг за шагом: Новый проект и Существующий проект.

Мод Binnacle для Claude Code

binnacle-mod — необязательный плагин Claude Code из того же пакета (ADR-0047): строка состояния с задачей сессии, токенами, контекстом и лимитами, полоса Ждёт вас, панель, которая открывается своей командой, и всплывающие уведомления, всё — из демона. Он ничего не пишет и без демона ничего не показывает.

binn init спрашивает, ставить ли его, по умолчанию — нет, и только там, где найден Claude Code 2.1.308 или новее и мод ещё не стоит. --mod yes или --mod no отвечают без вопроса; --plan и --apply без флага мод не ставят. Почему вопрос не задан, init пишет в итоге. Поставить мод позже из marketplace binnacle, который binn init добавляет вместе с плагином binnacle:

claude plugin install binnacle-mod@binnacle --scope user

Выключить его и включить снова или удалить — командами самого Claude Code:

claude plugin disable binnacle-mod
claude plugin enable binnacle-mod
claude plugin uninstall binnacle-mod

Когда harness не находит binn

Harness, который отвечает command not found на binn, не видит в своём PATH глобальный каталог исполняемых файлов npm. npm prefix -g печатает глобальный префикс npm:

Платформа	binn — это
Linux, macOS	<prefix>/bin/binn
Windows	<prefix>\binn.cmd

Desktop-приложение Claude Code не читает файл запуска shell, например ~/.bashrc, поэтому заданный там PATH до него не доходит. Положите скрипт-обёртку с именем binn, исполняемым, в каталог, который уже есть в PATH приложения, — в Linux это ~/.local/bin, — с префиксом, записанным явно:

#!/bin/sh
exec "<prefix>/bin/binn" "$@"

Development-ссылка из checkout запускает binn иначе, через pnpm: см. CONTRIBUTING.ru.md, binn в desktop-приложении Claude Code.

Обновление

1. binn daemon stop: запущенный демон держал бы старую версию до перезапуска.
2. npm i -g @it-bbox/binnacle@latest заменяет CLI, демон, dashboard и плагин разом.
3. binn daemon start, затем binn --version печатает новую версию.
4. Если claude plugin list --json показывает binnacle@binnacle, выполните claude plugin marketplace update binnacle, затем claude plugin update binnacle@binnacle, а если стоит и мод — claude plugin update binnacle-mod@binnacle, чтобы Claude Code взял новые навыки и мод. Они есть у сессии, открытой после этого шага.
5. Выполните binn init в проекте ещё раз, чтобы заново поставить навыки Binnacle во все остальные harness. binn audit сообщает о них, пока они устарели.

Настройка

Переменные окружения

Все семь демон читает из своего окружения, поэтому после изменения любой из них перезапустите его. При включённом автозапуске служба запускает демон только с BINNACLE_HOME и PATH: остальные до него не доходят, поэтому храните токены tracker в файле учётных данных.

Переменная	По умолчанию	Значение
BINNACLE_HOME	~/.binnacle	Где Binnacle хранит runtime-файл демона, токен API, хранилище, учётные данные tracker и настройки этой машины. Укажите другой каталог для одноразового экземпляра рядом с настоящим.
BINNACLE_PORT	7717	Порт, к которому привязывается демон. 0 берёт эфемерный порт.
BINNACLE_HOST	127.0.0.1	Адрес, к которому привязывается демон: 127.0.0.1 или 0.0.0.0 в контейнере. С любым другим значением демон не запустится.
BINNACLE_ALLOWED_HOSTS	нет	Значения host:port через запятую, которые демон принимает как Host помимо своего адреса, например порт, который контейнер публикует на хост: 127.0.0.1:7718,localhost:7718. binn dashboard даёт первое из них.
BINNACLE_GIT_TIMEOUT_MS	5000	Сколько может длиться один вызов git только на чтение, прежде чем project.status сообщит, что факты Git недоступны. Увеличьте на медленной файловой системе.
BINNACLE_GITHUB_TOKEN	нет	Токен только на чтение для каждого проекта, чей tracker.provider — github, и для CI каждого проекта, чей Git remote на github.com.
BINNACLE_GITLAB_TOKEN	нет	Токен только на чтение для каждого проекта, чей tracker.provider — gitlab, и для CI каждого проекта, чей Git remote на gitlab.com.

binn говорит на языке вашей локали: по-русски, когда LC_ALL, а без неё LANG, начинается с ru, и по-английски в остальных случаях, включая C и пустую локаль. Коды выхода одинаковы на обоих языках; binn mcp, binn call и любой --json остаются на английском.

Коды выхода

Код	Значение
0	успех
2	ошибка использования
3	операция не удалась
4	демон недоступен

Учётные данные tracker

Проект на GitHub или GitLab issues читается токеном только на чтение; публичному репозиторию токен не нужен. Нужный доступ — в Безопасности и устойчивости.

CI в snapshot читается тем же токеном: из tracker, когда это GitHub или GitLab, а иначе — из первого remote проекта на GitHub или GitLab. Хост remote получает токен, хранимый для него:

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

Для одного хоста или нескольких храните токены в credentials.json в домашнем каталоге Binnacle. Это JSON-объект с ключами — tracker.host проекта так, как его пишет манифест, или github.com либо gitlab.com, если манифест его не пишет:

{
  "github.com": "github_pat_…",
  "gitlab.example.com": "glpat-…"
}

• Сделайте его доступным только владельцу: chmod 600 ~/.binnacle/credentials.json. Файл, который может читать или писать кто-то ещё, не читается вовсе, и snapshot сообщает tracker.credentials_insecure.
• Binnacle читает файл при каждом вызове и никогда его не пишет.
• При каждом вызове демон сначала берёт переменную провайдера, затем запись хоста в файле, а иначе читает анонимно.
• GITHUB_TOKEN и другие общие имена не читаются, и ничего не берётся из gh или glab: их токены обычно могут писать.

Опционально: Obsidian

Установите desktop-приложение Obsidian сами — для представления проекта человеку. Его конфигурация принадлежит этой машине: никогда не коммитьте абсолютный путь к хранилищу в общую конфигурацию проекта.

Файл настроек

Хранилище задаётся в settings.json в домашнем каталоге Binnacle, ~/.binnacle/settings.json, вне любого репозитория. Сделайте его доступным только владельцу, как файл учётных данных:

{
  "obsidian": { "vaultPath": "/home/me/Notes" }
}

Путь абсолютный: собственный каталог хранилища. Демон читает файл при каждом опросе и каждом snapshot, поэтому изменению не нужен перезапуск. Нет файла или нет obsidian.vaultPath — нет проекции и нет пункта внимания.

binn init предлагает путь, когда файл его не называет, из собственного списка хранилищ Obsidian, obsidian.json в каталоге конфигурации Obsidian:

Платформа	Каталог
Linux	~/.config/obsidian или каталог его Flatpak или Snap
macOS	~/Library/Application Support/obsidian
Windows	%APPDATA%\obsidian

• Если там ровно одно хранилище, план записывает его в файл настроек, доступный только владельцу, сохраняя остальные настройки файла.
• Если хранилищ нет или их несколько, он ничего не предлагает, называет найденные и говорит, как задать путь.
• Чтобы выбрать другое хранилище, чем предложенное, отклоните план и отредактируйте файл.
• Уже заданный путь отмечается и не трогается. В репозитории этот шаг ничего не пишет.

В том же файле хранится Parallel limit, parallelLimit (ADR-0041): целое число от 1 до 16 или "auto"; 2, если не задан. Страница Settings в dashboard пишет его через демон, сохраняя все остальные ключи. automation.max_parallel_development_tasks в манифесте проекта побеждает для своего проекта.

В нём же хранятся пороги заполненности контекста, contextPressure (ADR-0046): { tokens, models: { <имя модели>: <токены> } }, порог по умолчанию и число для модели, каждое — целое число не меньше 1 000; 150 000, если не заданы. Страница Settings пишет их так же. telemetry.context_pressure.tokens в манифесте проекта побеждает для своего проекта, для любой модели.

Проекция хранилища

Когда хранилище задано, демон ведёт одностороннюю проекцию каждого зарегистрированного проекта в <Vault>/Projects/<Project>/, где <Project> — project.name манифеста или его id (ADR-0036):

Папка	Что в ней
Product/	roadmap.md, из <knowledge.docs>/roadmap.md; snapshot.md и daily.md, последние отданные snapshot и daily
Specs/<slug>/	spec.md и тикеты спеки, из knowledge.specs
Decisions/	ADR, из knowledge.adr
Research/	остальной Markdown из knowledge.docs, в той же раскладке, без roadmap
90-Graphify/	GRAPH_REPORT.md, отчёт Graphify о последнем успешном построении графа

Раз в минуту он читает ветку по умолчанию каждого проекта. Когда ветка сдвинулась, настройка хранилища изменилась или граф был построен заново, он заново отрисовывает проект из этого коммита, читая через Git: незакоммиченное изменение никогда не попадает в хранилище. Относительные Markdown-ссылки между спроецированными файлами становятся ссылками Obsidian.

Заметки snapshot и daily пишутся каждый раз, когда отдаётся snapshot или daily, из того, что было отдано, без дополнительного обращения к tracker:

• их source — project.snapshot или daily.get, их commit — HEAD вызывающего, а строка served: даёт время;
• обе содержат Waiting for the owner: неотвеченные вопросы, задачи, ждущие одобрения, и задачи ready-for-human, готовые к старту;
• их тикеты и ADR ссылаются на спроецированные заметки;
• их заголовки и строки, которые пишет Binnacle, — на языке документации проекта, knowledge.language манифеста, а если он язык не называет, на английском; русская заметка пишет пункты внимания словами, без их кода, а причину, которая есть у демона только по-английски, — как есть, с пометкой (англ.). Заметки, скопированные из репозитория, и frontmatter остаются как есть при любом языке. Служба автозапуска демона не меняется: язык берётся из манифеста, а не из локали;
• если хранилище не задано, отдача ничего не пишет.

90-Graphify/GRAPH_REPORT.md — это graphify-out/GRAPH_REPORT.md зарегистрированного checkout, с коммитом последнего успешного запуска. Переписывает его только более новый успешный запуск, поэтому неудачный оставляет его как есть, а хранилище, заданное после неудачного запуска, не получает отчёта до следующего успешного.

Без записанного успешного запуска, без отчёта или с capabilities.graphify: false заметки нет, как нет и пункта внимания о ней.

Каждая заметка, которую он пишет, начинается с frontmatter, называющего её сгенерированной, с её источником и коммитом:

---
generated-by: binnacle
source: docs/adr/ADR-0036-the-daemon-maintains-derived-graph-and-vault.md
commit: <hash>
---

• Демон пишет, переписывает и удаляет только файлы с этой меткой: ваша заметка рядом с ними или ваш файл по пути сгенерированной заметки остаётся байт в байт.
• Сгенерированная заметка, чей источник исчез из ветки по умолчанию, удаляется.
• Каждая запись — целый файл, через временное имя и переименование.
• Правка сгенерированной заметки перезаписывается при следующем обновлении и никогда не синхронизируется обратно.
• Удаление папки проекта ничего не теряет: она возвращается при следующем движении ветки или следующем старте демона.

Путь к хранилищу, который не существует, не является каталогом или недоступен для записи, а также файл настроек, который не читается, — это пункт внимания snapshot vault.unwritable.

Экспорт телеметрии

binn init настраивает экспорт OpenTelemetry каждого найденного harness, у которого он есть, в его настройках на уровне пользователя, пунктом своего одного плана. Экспорт идёт на адрес демона, как OTLP JSON поверх HTTP, с выключенным логированием промптов. Адрес — адрес запущенного демона, а иначе http://127.0.0.1: с BINNACLE_PORT или 7717.

Harness	Настройки	Что добавляет план
Claude Code	settings.json в CLAUDE_CONFIG_DIR или ~/.claude, слиянием, с сохранением остального	env: CLAUDE_CODE_ENABLE_TELEMETRY=1, OTEL_LOGS_EXPORTER=otlp, OTEL_EXPORTER_OTLP_PROTOCOL=http/json, OTEL_EXPORTER_OTLP_ENDPOINT=<address>
Codex	config.toml в CODEX_HOME или ~/.codex, дописыванием	[otel] с exporter = { otlp-http = { endpoint = "<address>/v1/logs", protocol = "json" } } и log_user_prompt = false
Gemini CLI	.gemini/settings.json в GEMINI_CLI_HOME или ~, слиянием, с сохранением остального	telemetry: enabled: true, target: "local", otlpEndpoint: "<address>", otlpProtocol: "http", logPrompts: false

• Собственные настройки OpenTelemetry harness, экспортируют ли они куда-то ещё или никуда, не трогаются и называются в Summary: env Claude Code с любой переменной OTEL_, таблица [otel] Codex, блок telemetry Gemini CLI.
• Файл настроек, который не является чистым JSON, например с комментариями, не переписывается: изменение печатается.
• Если демон не запущен и BINNACLE_PORT равен 0, адреса нет, и шаг пропускается.
• Найденный harness, который не экспортирует ничего, что принимает Binnacle, — opencode, ZCode, Antigravity, pi или VS Code, — называется в Summary с причиной.

binn audit читает те же настройки и сообщает для каждого найденного harness, экспортирует ли он в Binnacle (telemetry.export_<harness>). Harness без богатой telemetry никогда не проваливает настройку проекта.