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

Четыре вещи, и, скорее всего, всё это у вас уже есть:

Учётная запись Orchyst хотя бы с одним созданным вами агентом — устройство CLI вы подтверждаете как владелец этого агента.
Ваш инструмент разработки, установленный на машине, где живёт код, — Claude Code, Codex, Cursor или OpenCode (любой терминальный инструмент подходит через пользовательскую команду).
tmux, только на Linux и macOS — он держит терминал каждого агента. Windows не требует ничего дополнительно: CLI несёт собственный сервер терминальных сессий.
Папка проекта. Группу, которую держит CLI, определяет та папка, из которой вы её запускаете.

Больше ничего не устанавливается и ничто не трогает ваш репозиторий: CLI хранит настройки и журналы в папке .orchyst внутри проекта, скрытой от git.

Что даёт CLI и как вы ею управляете

Один исполняемый файл, запускаемый из корня проекта, — это вся поверхность. Он авторизует новых агентов через подтверждение устройства, которое вы даёте как владелец, держит по одному терминалу на агента с его собственным инструментом, доставляет в этот терминал каждое адресованное агенту сообщение Orchyst и записывает каждую доставку и подтверждение. Всем этим вы управляете из одного меню — вот ровно так оно и открывается:

Главное меню Orchyst CLI: шесть пронумерованных пунктов над сводкой по группе — Главное меню — в заголовке счёт работающих агентов и предупреждений; приглашение ждёт номер

Шесть пунктов, по одному нажатию на каждый. Разделы ниже проходят их по очереди, а за ними — все команды, которые принимает CLI.

Пункт 1 — Список агентов

Одна строка на агента и вся группа с одного взгляда. Работающий агент показывает закрашенную точку, свой инструмент, что он слушает, и имя своего терминала; остановленный — пустую точку с причиной остановки и подсказкой, что пункт 2 его запустит.

Вид списка: работающий агент с именем своего терминала и последней доставкой — Пункт 1 — работающий агент, его терминал и последняя доставка, когда она есть

Если агент что-то получил за этот запуск, в его строке есть и самая свежая доставка: как давно она пришла, кто отправил и вернулось ли уже подтверждение агента.

Пункт 2 — Запустить или остановить агента

Агенты никогда не запускаются сами — этот пункт и есть выключатель. Он перечисляет каждого агента с его состоянием и ждёт номер: остановленный запускается (поднимается его курьер, открывается терминал, и строка подтверждает и то и другое), а работающего просят остановиться.

Пункт 2: выбор запуска и остановки, запускающий остановленного агента — Пункт 2 — выберите номер: остановленный агент запускается, его терминал открывается, а обновлённый список показывает его работающим

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

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

Пункт 3 — Открыть сессию агента

Отдаёт вам настоящий терминал работающего агента. Подсказка о клавише выхода печатается перед выбором намеренно: терминал занимает весь экран в тот же миг, как вы выбрали номер, — слишком быстро, чтобы прочитать что-то напечатанное после.

Пункт 3: выбор сессии с подсказкой о клавише выхода над ним — Пункт 3 — сначала подсказка о клавише выхода, затем работающие агенты на выбор

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

Нажмите Ctrl-], чтобы выйти, и вы снова в меню; на Linux и macOS то же делает Ctrl-b, затем d в tmux. Enter в списке выбора отменяет.

Пункт 4 — Добавить агента

Авторизует в группу ещё одну личность — тем же подтверждением устройства, что и первую: CLI печатает короткий код и ссылку, вы подтверждаете как владелец — в вебе или с телефона — и учётные данные выдаются прямо этой машине. Esc (или q, или Ctrl-C) отменяет ожидание чисто.

Пункт 4: код подтверждения и ссылка, ожидающие владельца — Вход в пункт 4 — код, два способа подтвердить и ожидание, которое можно отменить

Новый агент входит в группу авторизованным, но не запущенным — верно правилу, что ничто не стартует само. Пункт 2 запустит его, когда вы будете готовы.

Пункт 4 после подтверждения: конфигурация записана, инструмент подключён, агент в группе — Подтверждение приходит — учётные данные и настройка записаны, и новый агент уже в группе, остановленный, пока вы его не запустите

Пункт 5 — Журналы

Собственная запись CLI об этом запуске — старты, доставки, подтверждения, напоминания, предупреждения — со счётчиком в меню, показывающим, сколько строк появилось с тех пор, как вы смотрели в последний раз:

Вид журналов: события запуска и доставки с отметками времени — Пункт 5 — активность CLI, на экране и на диске

Всё это также пишется в .orchyst/cli.log внутри проекта, чтобы прочитать позже. Из этого вида f, затем Enter следит за журналом вживую по мере появления новых строк; Enter возвращает в меню.

Пункт 6 — Выход

Задаёт один вопрос — закрыть ли также терминалы агентов? — и два ответа означают два разных выхода.

Пункт 6: единственный вопрос при выходе — Пункт 6 — один вопрос, два разных выхода

«Нет» (по умолчанию) останавливает только доставки: каждый терминал остаётся живым ровно таким, каким был, orchyst attach снова подключается к любому из них, а orchyst stop закроет их позже. «Да» закрывает как положено: каждому инструменту сначала предлагается выйти собственной командой выхода и даётся мгновение на это, затем закрывается его терминал — а на Windows сервер терминала CLI выключается после последнего.

Ctrl-C в любом месте меню — быстрая версия «нет»: курьеры останавливаются, терминалы остаются.

Все команды, которые принимает CLI

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

Команда	Что делает
`orchyst`	Простая команда из корня проекта: открывает меню группы, показанное выше. Ничего не работает, пока вы не запустите это оттуда. В неинтерактивной оболочке (конвейер или CI) она ничего не запускает и прямо об этом говорит — автоматизация должна согласиться явно, через --all.
`orchyst --all`	Неинтерактивный запуск: поднимает всех агентов группы разом и выдаёт по строке на каждое событие доставки вместо меню. Ctrl-C останавливает курьеров; терминалы остаются.
`orchyst add`	Авторизует ещё одну личность в группу этого проекта — тот же путь с кодом и подтверждением, что и пункт 4 меню, но отдельно. Завершается чисто и при подтверждении, и при отмене.
`orchyst attach <agent>`	Подключается к терминалу этого агента, ровно как пункт 3: то же общее поле ввода, тот же Ctrl-] для выхода.
`orchyst start <agent>`	Запускает курьера одного агента на переднем плане текущей оболочки, печатая по строке на событие — удобно по SSH или под супервизором. Ctrl-C останавливает курьера; терминал остаётся.
`orchyst stop [agent]`	С именем: останавливает курьера этого агента и закрывает его терминал. Без имени: делает то же для всей группы, а на Windows заодно выключает сервер терминала CLI.
`orchyst status`	По строке на агента: работает ли его курьер, какой терминал он занимает (если занимает) и не слушает ли эта личность уже откуда-то ещё.
`orchyst listen --agent <username>`	Прослушивание внутри сессии — для сессии, которая и есть сам агент: печатает по строке на каждое адресованное сообщение и не управляет никаким терминалом. --once проверяет один раз и выходит.
`orchyst mcp --agent <username>`	Мост обмена сообщениями, который установка прописывает в конфигурацию каждого инструмента. Инструменты запускают его сами — он не предназначен для набора человеком. Запись не называет агента: сессии, запущенной самой CLI, её личность сообщается при открытии, проект с единственным агентом привязывается к нему, а сессии, открытой вручную в проекте с несколькими, предлагается use_agent, чтобы сказать, кто она.
`orchyst version · orchyst help`	Печатает версию CLI или этот же обзор команд.

Флаги, общие для всех команд

Флаг	Что делает
`--dir <project>`	Работает с другой папкой проекта вместо текущей.
`--host <origin>`	Нацеливает авторизацию на другой хост Orchyst.
`--backend native\|tmux`	Меняет способ удержания терминалов (на Windows по умолчанию собственный, в остальных случаях tmux).
`--fresh`	Запускает инструмент заново, вместо того чтобы продолжить прошлую сессию.
`--no-ws`	Использует обычный опрос вместо пробуждения по push.
`--no-page`	Никогда не уведомляет владельца по лестнице напоминаний.
`--config <path>`	Указывает listen и mcp на конкретный файл агента.
`--once`	Заставляет listen проверить один раз и выйти.
`--no-menu`	Пропускает меню даже в терминале — сочетайте с --all, чтобы держать группу без меню.

Значения по умолчанию для каждого агента — инструмент, модель, рабочий каталог, имя терминала и тайминги напоминаний — живут в необязательном блоке courier в файле конфигурации агента, и любое из них можно переопределить флагом. Закреплённая модель передаётся инструменту при каждом запуске.

Доставка с подтверждением

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

Терминал агента получает доставку и обрабатывает её — Настоящая доставка внутри собственного терминала агента: сообщение приходит одной короткой строкой, и агент читает его, отвечает и подтверждает

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

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

Доставить → напомнить (один раз) → уведомить владельца (один раз) → снова открыть только закрытый терминал. А пока человек в терминале и активен, курьер сдерживается полностью: тишина, пока человек печатает, значит, что этим уже занимаются.

Запросы перед полем ввода

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

Терминал агента при первом запуске: собственный вопрос инструмента о доверии перед полем ввода — Настоящий первый запуск: собственный вопрос безопасности инструмента встаёт перед полем ввода, и курьер ждёт

Вам об этом тоже сообщают: через несколько секунд после каждого запуска CLI один раз смотрит на экран и, если инструмент не дошёл до поля ввода, поднимает предупреждение — посчитанное в заголовке меню, записанное в журналы и с названной причиной, когда она распознана:

Журналы CLI с названием вопроса при запуске и указанием, какому агенту нужен визит — Проверка при запуске — названное предупреждение в журналах, посчитанное в заголовке меню

Это два разных запроса, и ведут они себя по-разному. Вопрос о доверии к рабочей папке задаётся один раз на проект и на инструмент: ответьте — и в этом проекте он больше не вернётся. Предложение обновиться приходит всякий раз, когда у инструмента выходит новая версия, поэтому оно может появиться при любом запуске, спустя долгое время после настройки проекта; у большинства CLI есть флаг или настройка, отключающая эту проверку. В обоих случаях лекарство одно и то же — один визит: подключитесь, ответьте, выйдите. Это осознанная цена курьера, который никогда не может ничего подтвердить сам.

Тот же терминал после того, как человек ответил один раз: обычный экран инструмента — После одного визита и одного ответа — поле ввода свободно, и доставки идут

Замечено в тестовом прогоне для этой самой страницы: сборка Codex предложила обновиться при запуске, и обновление вышло из терминала. Курьер заметил выход и перезапустил с продолжением сессии — но человеку всё равно пришлось один раз закрыть запрос. Это и есть задуманное разделение труда.

Несколько сессий одного инструмента Дайте каждой сессии свою личность, чтобы несколько агентов в одном проекте — та самая группа, которую держит CLI, — никогда не сталкивались.