Документация

Что такое AgentMux#

AgentMux — это настольное приложение для управления ИИ-агентами для написания кода — Claude Code, Codex, Gemini CLI, OpenCode, Aider, Cursor CLI, — которые выполняются на удалённых хостах и на этом компьютере. Его основной механизм умещается в одно предложение:

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

Требования#

Компьютер, на котором работает AgentMux

Управляемые хосты

• Удалённые хосты: POSIX-совместимая оболочка, tmux и учётная запись SSH. Отсутствие tmux не помеха — панель установки может его установить. Удалённые Windows-хосты не поддерживаются.
• Этот компьютер (Linux / macOS): достаточно локального tmux — ни sshd, ни учётных данных.
• Этот компьютер (Windows): одна машина даёт два хоста — дистрибутив WSL по умолчанию (где живёт tmux) и нативный Windows (PowerShell, пути и инструментарий Windows — для сборок MSVC, WPF и запуска только что собранного .exe). Нативные сессии сохраняются собственным сессионным демоном AgentMux, так что закрытие окна не останавливает и нативную работу.

По желанию: оркестратор и семантический поиск

Локальной оркестрации и семантическому поиску по памяти требуется Ollama плюс одна чат-модель и одна модель эмбеддингов. Без Ollama всё остальное полностью работоспособно.

Установка#

Каждый выпуск содержит по одной сборке на платформу, собранной GitHub Actions из помеченного тегом коммита, с файлом .sha256 в комплекте. Сборки пока не подписаны и не нотарифицированы, поэтому первый запуск потребует одного дополнительного подтверждения — на каждой платформе своего.

macOS

1. Скачайте agentmux-macos-universal.zip, распакуйте и перетащите AgentMux.app в «Программы».
2. Обработайте предупреждение о неподписанной сборке в зависимости от версии macOS (таблица ниже).
3. После этого приложение открывается как обычно.

Windows

1. Скачайте и распакуйте agentmux-windows-amd64.zip — внутри agentmux.exe и скрипт установки.
2. Запустите двойным щелчком; когда появится SmartScreen, выберите Подробнее → Выполнить в любом случае.
3. Для полноценной установки (в %LOCALAPPDATA%\Programs\AgentMux, с ярлыками на рабочем столе и в меню «Пуск», без прав администратора) выполните из распакованной папки:

powershell -ExecutionPolicy Bypass -File install-windows.ps1

Тот же скрипт с параметром -Uninstall отменяет установку, не трогая данные в %APPDATA%\AgentMux.

Linux

1. Сначала установите зависимость времени выполнения: sudo apt install libwebkit2gtk-4.1-0 в Debian/Ubuntu, sudo dnf install webkit2gtk4.1 в Fedora.
2. Скачайте и распакуйте agentmux-linux-amd64.tar.gz — бинарный файл, значок, .desktop-запись и install.sh.
3. Запустите ./install.sh или сам бинарный файл напрямую.

Проверка загруженных файлов

# к каждому файлу прилагается .sha256:
shasum -a 256 -c agentmux-macos-universal.zip.sha256   # macOS
sha256sum -c agentmux-linux-amd64.tar.gz.sha256        # Linux

Быстрый старт#

Четыре шага до первого управляемого агента. Всё описанное здесь доступно и через палитру команд Ctrl/⌘ K — самый быстрый путь к любому действию.

Шаг 1. Добавьте хост

Удалённому хосту нужны три вещи:

• Адрес и пользователь — те же, что и в ssh user@host.
• Один из трёх способов аутентификации: ssh-agent (рекомендуется — заполнять ничего не нужно), файл ключа (парольная фраза поддерживается) или пароль.
• Jump-хосты (по желанию) — для окружений за бастионом.

Этому компьютеру не нужно ничего, кроме имени — ни sshd, ни учётных данных. В Windows вы увидите два локальных хоста: дистрибутив WSL и нативный Windows. Выбирайте по задаче: Unix-инструментарий — в WSL, MSVC/WPF — в нативный.

Шаг 2. Добавьте проект и рабочую область

Рабочая область — это рабочий каталог на хосте (обычно корень репозитория). Добавить её можно двумя способами:

• Через форму: выберите хост, введите путь.
• Через файловый браузер (быстрее): откройте файлы хоста, найдите каталог и «добавьте как проект» прямо на месте — его имя, путь и хост уже известны.

Шаг 3. Добавьте агента и запустите его

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

# типичные команды запуска, настройте под себя
claude                    # Claude Code
codex                     # OpenAI Codex CLI
gemini                    # Gemini CLI
aider --model sonnet      # Aider
opencode                  # OpenCode

Нажмите Start — и агент уже работает внутри tmux на хосте. API-ключи агента настраиваются на стороне хоста (в конфигурации самого агента или его окружении) — AgentMux их не читает и не проксирует.

Шаг 4. Подключитесь и работайте

Щёлкните по агенту или найдите его по имени через Ctrl/⌘ K. Перед вами настоящий терминал — цвет, мышь, выделение, поиск. Вмешивайтесь и печатайте в любой момент, корректируйте курс агента, возвращайте ему управление — без перезапуска. Боковая панель даёт Start / Stop / Restart / Attach, состояние процесса и последний вывод.

Стена терминалов#

Область терминала делится максимум на девять панелей (3×3), каждая со своей сессией — на одном хосте или на нескольких, и каждая интерактивна независимо:

• Добавить панель: Ctrl/⌘ \. Если есть свободная открытая вкладка, разделение происходит мгновенно; иначе диалог предложит хосты, каталоги рабочих областей, запущенных агентов и открытые вкладки.
• Раскладка адаптируется: панели делят область в пропорциях, а не в пикселях. Слишком узкая для чтения колонка убирается, поэтому в суженном окне стена 3×3 переливается в более высокую сетку, а не в девять щелей.
• Перетаскивайте разделители, чтобы менять размер панелей.
• Временное увеличение: двойной щелчок по вкладке панели (или Ctrl/⌘ ⇧ ↵) разворачивает её на всю область; повторно — возвращает обратно. Разбивка под ней не меняется.
• Панель — это вид, а не сессия: закрытие панели (Ctrl/⌘ ⇧ \) скрывает терминал, но вкладка и её оболочка остаются подключёнными. Количество панелей восстанавливается при следующем запуске.

Горячие клавиши#

Рассылка и подтверждения#

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

• Выбор по проекту, по хосту или отметкой отдельных агентов.
• Статус доставки по каждому агенту; неудачные доставки заметны сразу и повторяются по отдельности.
• Типичные применения: приостановить весь парк, ввести новое требование («с этого момента все сообщения коммитов — на английском»), опросить прогресс по всем агентам.

Работа с хостами#

Панель установки: подготовка нового хоста

Панель установки сначала обследует хост и предлагает только те агентские CLI и среды выполнения, которые он реально поддерживает, объясняя, почему остальные недоступны. Установка идёт внутри tmux, поэтому оборванное соединение не оставит наполовину установленных пакетов. Сам tmux, если его нет, тоже устанавливается отсюда.

Телеметрия хоста

Метрики по каждому хосту собираются одной командой:

• CPU по режимам и по ядрам, память, нагрузка
• Использование диска и пропускная способность, сеть, файловые дескрипторы
• Загрузка NVIDIA GPU, если он есть

SFTP-браузер и редактор

Доступ к файлам идёт по тому же SSH-соединению. Запись атомарна и сопровождается проверкой изменений: если агент, работающий в том же каталоге, изменил файл, сохранение будет отклонено вместо тихой перезаписи — сначала посмотрите, что изменилось, а потом решайте.

Оркестратор и Ollama#

Оркестратор — это операционный помощник на локальной модели: дайте ему цель (например, «выясни, почему agent-3 перестал продвигаться») — и он изучит состояние парка, поднимет прошлый контекст и будет двигаться по одному вызову инструмента за раз. Он выключен, пока вы его не включите.

Предварительные условия

1. Установите Ollama и держите его запущенным.
2. Загрузите одну чат-модель и одну модель эмбеддингов, например:

ollama pull qwen3             # чат-модель (пример — выбирайте под своё железо)
ollama pull nomic-embed-text  # модель эмбеддингов, используется для семантического поиска

Процесс одобрения

• Каждая операция, изменяющая хост, ждёт вашего явного одобрения. Карточка одобрения показывает инструмент, его полные аргументы, целевой хост и обоснование, приведённое моделью.
• Разрушительные операции подтверждаются на любом хосте, независимо от уровня доверия к нему.
• Инструменты — фиксированный белый список, каждому уровень риска присвоен при объявлении раз и навсегда. Выполнение проходит единый шлюз: уровень риска × степень доверия к хосту × то, что запустило прогон.
• Вывод с удалённых хостов попадает в модель с пометкой «данные»; текст, похожий на инструкции, помечается флагом на карточке одобрения и в журнале решений (защита от инъекций промптов).
• Каждый шаг каждого прогона записывается — включая предложения, которые были отклонены или остались без ответа.

Плановые обходы

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

Навыки и память

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

Семантика жизненного цикла#

Усвойте эти правила — и момента «я что, только что потерял задачу?» у вас не будет никогда:

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

Go 1.25+ и Node 20+. Сначала собирается фронтенд (он встраивается в бинарный файл), затем Go:

git clone git@github.com:tan-zhuo/AgentMux.git
cd AgentMux
cd frontend && npm install && npm run build && cd ..
go build -o agentmux .
./agentmux

Linux требует заголовков WebKitGTK и тега сборки gtk3:

sudo apt-get install -y build-essential pkg-config libgtk-3-dev libwebkit2gtk-4.1-dev
go build -tags gtk3 -o agentmux .

Windows — для GUI-файла, запускаемого двойным щелчком, без консольного окна:

go build -ldflags "-H windowsgui" -o agentmux.exe .

Подробности (тестирование, подготовка выпуска) — в docs/development.md.

Устранение неполадок#

macOS сообщает, что приложение «повреждено», или не открывает его

Это обычная преграда для неподписанных сборок, а не повреждение файла. Следуйте таблице в разделе «Установка» или исправьте одной командой: xattr -dr com.apple.quarantine /Applications/AgentMux.app.

Linux не запускается / не хватает библиотеки

Почти всегда дело в рантайме WebKitGTK. Debian/Ubuntu: sudo apt install libwebkit2gtk-4.1-0; Fedora: sudo dnf install webkit2gtk4.1.

Windows: окно вообще не появляется

У GUI-сборок нет консоли для вывода ошибок. Загляните в startup-error.log в каталоге данных (%APPDATA%\AgentMux) — настоящая причина сбоя записана там.

«Host key mismatch» при подключении

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

Строка состояния сообщает, что системное хранилище недоступно

Мастер-ключ шифрования обычно хранится в системном хранилище (Keychain / Диспетчер учётных данных / Secret Service). Там, где хранилища нет (обычное дело на минималистичных рабочих столах Linux), AgentMux переключается на файл с правами 0600 и сообщает об этом в строке состояния. Ничего не ломается; чтобы вернуть хранение в системном хранилище на Linux, установите и включите gnome-keyring или другую реализацию Secret Service.

На целевом хосте нет tmux

Откройте панель установки этого хоста — tmux есть в списке, и AgentMux установит его подходящим пакетным менеджером.

Оркестратор / семантический поиск недоступны

Убедитесь, что Ollama запущен (ollama list показывает ваши модели) и что загружены и чат-модель, и модель эмбеддингов. Без Ollama эти две функции остаются выключенными; всё остальное не затронуто.

Где мои данные?

Всё состояние — один файл SQLite в каталоге данных приложения (%APPDATA%\AgentMux в Windows). Резервная копия этого каталога — резервная копия всего; удалите его для полного сброса. Учётные данные хранятся зашифрованными AES-256-GCM, а ключ — в системном хранилище ОС.

Где получить помощь#

• Создайте задачу на GitHub — платформа, версия и startup-error.log (если есть) заметно ускорят разбор.
• Внутреннее устройство оркестратора (шлюз инструментов, уровни доверия, слои памяти и навыков) описано в проектном документе оркестратора.
• Блог автора: tanzhuo.xyz