workmux: параллельные AI-агенты в tmux и git worktrees

8 сентября 2026 г.

#cli#developer-tools#git#tmux#workflow
Скриншот workmux: параллельные задачи в окнах tmux

Почему workmux?

Параллельная работа. Ведите несколько задач одновременно, каждую со своим AI-агентом. Никакого stash’а, никаких переключений веток, никаких конфликтов.

Одно окно — одна задача. Интуитивная ментальная модель. У каждой задачи своё состояние терминала, сессия редактора, dev-сервер и AI-агент. Переключить контекст — значит переключить вкладку.

Автоматическая настройка. Новые worktree’ы создаются «сломанными»: без .env, без node_modules, без dev-сервера. workmux умеет копировать конфигурационные файлы, создавать символические ссылки на зависимости и выполнять команды установки при создании.

Очистка одной командой. workmux merge охватывает полный жизненный цикл: сливает ветку, удаляет worktree, закрывает окно tmux и удаляет локальную ветку.

Терминальный рабочий процесс. Стройте поверх своей терминальной среды, а не поверх очередного агентного GUI, которого не будет через год. Если у вас ещё нет такой среды — tmux стоит освоить.

Не знакомы с worktree’ами? Читайте раздел Почему git worktrees?.

Возможности

  • Создавать git worktree’ы с соответствующими окнами tmux одной командой (add)

  • Сливать ветки и убирать всё лишнее (worktree, окно tmux, ветки) одной командой (merge)

  • Дашборд для мониторинга агентов, просмотра изменений и отправки команд

  • Боковая панель для постоянного отображения статуса всех агентов во всех окнах tmux

  • Делегировать задачи агентам worktree через навык /worktree

  • Отображать статус агента в именах окон tmux

  • Автоматически задавать предпочитаемую раскладку панелей tmux (редактор, шелл, наблюдатели и т.д.)

  • Запускать хуки после создания (установка зависимостей, настройка БД и т.д.)

  • Копировать или символически ссылаться на конфигурационные файлы (.env, node_modules) в новые worktree’ы

  • Изолировать агентов в контейнерах или виртуальных машинах для повышенной безопасности

  • Автоматически генерировать имена веток из промптов с помощью LLM

  • Автодополнение в шелле

Что говорят пользователи

  • «Я использую (и очень люблю) workmux — он объединяет tmux, git worktree’ы и CLI-агентов в продуманный рабочий процесс.» — Coolin96 на Hacker News

  • «Большое спасибо за работу над workmux! Это инструмент, который я давно хотел видеть.» — rstacruz на GitHub

  • «Он стал моим повседневным инструментом — идеальный уровень абстракции над tmux и git, не мешающий работе и не скрывающий базовые инструменты.» — cisaacstern на GitHub

  • «Я упоминаю workmux при каждом удобном случае, потому что это идеальный клей между worktree’ами, агентами и окнами tmux.» — dedbrizz на Threads

  • «С тех пор как я открыл для себя workmux, я в деле. Отличный драйвер для параллельных агентов, если вы любите tmux и хотите сохранить свой конфиг.» — MatijaSosic на X

  • «Использование workmux с хорошо настроенным tmux стало глотком свежего воздуха.» — sbeirakh_il на X

  • «Использую уже около месяца, и это сплошь положительные впечатления.» — gabrielrockson_ на X

  • «Я по-прежнему не вижу смысла в Herdr. workmux добавляет статусы busy/question/done, сам управляет worktree’ами и многое другое. И всё это поверх уже существующей конфигурации tmux.» — 13hcoks на X

  • «Хотите современные возможности терминального рабочего пространства, не отказываясь от своей настройки? Вот как сохранить Tmux и ускорить рабочий процесс с помощью Workmux.» — Sam Natale на YouTube

Установка

Bash YOLO

curl -fsSL https://raw.githubusercontent.com/raine/workmux/main/scripts/install.sh | bash

Homebrew (macOS/Linux)

brew install raine/workmux/workmux
Details

Cargo (требует rustup):

cargo install workmux

mise:

mise use -g cargo:raine/workmux

Nix (настройка flake и home-manager):

nix profile install github:raine/workmux

Для ручной установки смотрите готовые бинарные файлы.

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

Примечание

workmux требует терминального мультиплексора. Убедитесь, что у вас установлен и запущен tmux (или WezTerm / Kitty / Zellij), прежде чем начать. Смотрите My tmux setup, если вам нужна отправная точка.

  1. Инициализация конфигурации (необязательно):

    workmux init

    Создаёт файл .workmux.yaml для настройки рабочего процесса (раскладки панелей, команды настройки, файловые операции и т.д.). workmux работает из коробки с разумными значениями по умолчанию, поэтому этот шаг необязателен.

  2. Создать новый worktree и окно tmux:

    workmux add new-feature

    Это действие:

    • Создаст git worktree по пути <project_root>/../<project_name>__worktrees/new-feature

    • Скопирует конфигурационные файлы и создаст символические ссылки на зависимости (если настроено)

    • Выполнит все команды настройки post_create

    • Создаст окно tmux с именем wm-new-feature (префикс можно настроить)

    • Настроит вашу конфигурированную или стандартную раскладку панелей tmux

    • Автоматически переключит tmux-клиент на новое окно

  3. Делайте своё дело

  4. Завершение и очистка

    Локальное слияние: Выполните workmux merge, чтобы слить ветку в базовую и убрать всё лишнее за один шаг.

    Рабочий процесс с PR: Отправьте изменения и откройте PR. После слияния выполните workmux remove для очистки.

Конфигурация

workmux использует двухуровневую систему конфигурации:

  • Глобальная (~/.config/workmux/config.yaml): личные значения по умолчанию для всех проектов

  • Проектная (.workmux.yaml): переопределения, специфичные для проекта

Настройки проекта переопределяют глобальные. При запуске workmux из подкаталога он идёт вверх по дереву в поисках ближайшего .workmux.yaml, что позволяет использовать вложенные конфиги для монорепозиториев. Подробнее — в руководстве по монорепозиториям. Для списков хуков (post_create, pre_merge, pre_remove) и списков файловых операций (files.copy, files.symlink) можно использовать "<global>", чтобы включить глобальные значения вместе с проектными. Другие настройки, например panes, полностью заменяются при их определении в конфиге проекта.

Пример глобальной конфигурации

~/.config/workmux/config.yaml:

nerdfont: true # Включить иконки nerdfont (запрашивается при первом запуске)
merge_strategy: rebase # По умолчанию использовать rebase при workmux merge
merge_keep: true # По умолчанию сохранять worktree, окно и ветку после слияния
agent: claude

panes:
  - command: <agent> # Запустить настроенный агент (например, claude)
    focus: true
  - split: horizontal # Вторая панель со стандартным шеллом

Пример проектной конфигурации

.workmux.yaml:

post_create:
  - '<global>'
  - mise use

files:
  symlink:
    - '<global>' # Включить глобальные символические ссылки (node_modules)
    - .pnpm-store # Добавить символическую ссылку, специфичную для проекта

panes:
  - command: pnpm install
    focus: true
  - command: <agent>
    split: horizontal
  - command: pnpm run dev
    split: vertical

Реальный пример смотрите в собственном .workmux.yaml проекта workmux.

Параметры конфигурации

Большинство параметров имеют разумные значения по умолчанию. Настраивайте только то, что хотите изменить.

Основные параметры

Параметр Описание По умолчанию

main_branch

Ветка для слияния

Определяется автоматически

base_branch

Базовая ветка по умолчанию для новых worktree’ов, или auto для эффективной главной ветки

Текущая ветка

worktree_dir

Каталог для worktree’ов (абсолютный или относительный). Поддерживает ~ и {project}.

<project>__worktrees/

window_prefix

Префикс для имён окон/сессий tmux. Поддерживает {project}.

wm-

mode

Режим tmux (window или session)

window

window_placement

Размещение нового окна tmux (after_current или rightmost)

after_current

agent

Агент по умолчанию для заполнителя <agent>

claude

agents

Именованные команды агентов (документация, только глобальные)

{}

merge_strategy

Стратегия слияния по умолчанию (merge, rebase, squash)

merge

merge_keep

По умолчанию сохранять ресурсы после workmux merge

false

theme

Цветовая схема дашборда (пользовательские цвета)

default (авто тёмная/светлая)

Установите base_branch: auto, чтобы создавать независимые потоки работы от эффективной главной ветки каждого репозитория. workmux использует настроенный main_branch, затем локальный origin/HEAD, main или master. Определение использует локальное состояние Git и не выполняет fetch. Если base_branch не указан, ветки по-прежнему создаются от текущей ветки.

Параметры именования

Параметр Описание По умолчанию

worktree_naming

Способ формирования имён из веток

full

worktree_prefix

Префикс для каталогов worktree и окон

нет

Стратегии worktree_naming:

  • full: использовать полное имя ветки (слэши заменяются дефисами)

  • basename: использовать только часть после последнего / (например, prj-123/feature → feature)

Панели (Panes)

Задайте раскладку панелей мультиплексора с помощью массива panes. Для нескольких окон в режиме сессии используйте вместо этого windows (они взаимоисключающие).

panes:
  - command: <agent>
    name: agent
    focus: true
  - command: npm run dev
    name: dev
    split: horizontal
    size: 15

Каждая панель поддерживает:

Параметр Описание По умолчанию

name

Отображаемое имя панели (в настоящее время применяется бэкендом Zellij)

—

command

Команда для выполнения (см. заполнители агентов)

Шелл

focus

Получает ли эта панель фокус

false

zoom

Развернуть панель на весь экран (подразумевает focus: true)

false

split

Направление разделения (horizontal или vertical)

—

size

Абсолютный размер в строках/ячейках

50%

percentage

Размер в процентах (1–100)

50%
Заполнители агентов

  • <agent>: подставляет настроенного агента (из конфига agent или флага --agent)

Встроенные агенты (claude, gemini, agy, codex, opencode, kiro-cli, vibe, pi, omp, grok) автоматически определяются при использовании в качестве буквальных команд и автоматически получают инъекцию промпта, без необходимости использовать заполнитель <agent> или соответствующую настройку agent:

panes:
  - command: 'claude --dangerously-skip-permissions'
    focus: true
  - command: 'codex --yolo'
    split: vertical

Каждый агент получает промпт (через -p/-P/-e) в правильном формате для этого агента. Автоопределение сопоставляет имя исполняемого файла независимо от флагов или пути.

Поддержка Antigravity CLI охватывает определение команд, инъекцию промпта и отслеживание статуса через хуки жизненного цикла, устанавливаемые командой workmux setup.

Именованные раскладки

Определите переиспользуемые раскладки панелей в словаре layouts и выбирайте нужную при создании worktree с помощью флага -l/--layout:

layouts:
  design:
    panes:
      - command: <agent>
        focus: true
      - command: <agent:codex>
        split: vertical
  review:
    panes:
      - command: <agent>
workmux add my-feature -l design

При использовании -l панели раскладки заменяют верхнеуровневые panes для данного worktree. Все остальные настройки (хуки, файлы, агент и т.д.) берутся из верхнего уровня как обычно. Флаг -l нельзя комбинировать с --agent.

Файловые операции

Новые worktree’ы — это чистые копии без игнорируемых git’ом файлов (.env, node_modules и т.д.). Используйте files, чтобы автоматически копировать или создавать символические ссылки на всё необходимое для каждого worktree:

files:
  copy:
    - .env
  symlink:
    - .next/cache # Общий кэш сборки для всех worktree'ов

И copy, и symlink принимают glob-паттерны.

Чтобы повторно применить файловые операции к существующему worktree (например, после обновления конфига), выполните workmux sync-files из его каталога. Используйте --all для синхронизации всех worktree’ов сразу.

Хуки жизненного цикла

Выполняйте команды в определённых точках жизненного цикла worktree, например для установки зависимостей или запуска миграций БД. Все хуки запускаются из каталога worktree в качестве рабочего каталога (или каталога вложенного конфига для вложенных конфигов) и получают переменные окружения: WM_HANDLE, WM_WORKTREE_PATH, WM_PROJECT_ROOT, WM_CONFIG_DIR.

hook_shell — это список argv, содержащий исполняемый файл и его аргументы. workmux добавляет каждую команду хука в качестве последнего аргумента. По умолчанию используется ["bash", "-c"] для совместимости. Пути, специфичные для машины, следует помещать в глобальную конфигурацию:

hook_shell: ["/opt/homebrew/bin/bash", "-c"]

Проект может переопределить полный список argv или унаследовать глобальное значение, не указывая hook_shell. Список argv должен содержать непустой исполняемый файл. Флаги шелла и обработка ошибок применяются только при явном включении.

WM_CONFIG_DIR указывает на каталог, содержащий использованный .workmux.yaml, который может отличаться от WM_WORKTREE_PATH при использовании вложенных конфигов.

Хук Когда выполняется Дополнительные переменные окружения

post_create

После создания worktree, до открытия окна tmux

—

pre_merge

Перед слиянием (прерывает при ошибке)

WM_BRANCH_NAME, WM_TARGET_BRANCH

pre_remove

Перед удалением worktree (прерывает при ошибке)

—

Пример:

post_create:
  - direnv allow

pre_merge:
  - just check

Иконки статуса агента

Настройте иконки, отображаемые в именах окон tmux:

status_icons:
  working: '🤖' # Агент обрабатывает задачу
  waiting: '💬' # Агент ожидает ввода (автоматически сбрасывается при фокусировке)
  done: '✅' # Агент завершил задачу (автоматически сбрасывается при фокусировке)

Агенты в состоянии «working», не производящие вывода в панель в течение 10 секунд, автоматически определяются как прерванные.

Установите status_format: false, чтобы отключить автоматическое изменение формата tmux.

Поведение по умолчанию

  • По умолчанию worktree’ы создаются в каталоге <project>__worktrees, соседнем с вашим проектом

  • Если конфигурация panes не определена, workmux предоставляет собственные значения по умолчанию:

    • Для проектов с файлом CLAUDE.md: открывает настроенного агента (см. параметр agent) в первой панели, по умолчанию claude, если ничего не задано

    • Для всех остальных проектов: открывает стандартный шелл

    • Оба варианта включают вторую панель, разделённую горизонтально

  • Команды post_create необязательны и выполняются только при их настройке

Автоматическая настройка с панелями

Используйте конфигурацию panes для автоматизации настройки окружения. В отличие от хуков post_create, которые должны завершиться до открытия окна tmux, команды панелей выполняются немедленно внутри нового окна.

Это можно использовать для:

  • Установки зависимостей: запустите npm install или cargo build в активной панели для мониторинга прогресса

  • Запуска сервисов: автоматически запускайте dev-серверы, контейнеры БД или файловые наблюдатели

  • Запуска агентов: инициализируйте AI-агентов с конкретным контекстом

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

Запуск установки зависимостей (например, pnpm install) в команде панели, а не в post_create, имеет ключевое преимущество: вы сразу получаете доступ к окну tmux, пока установка выполняется в фоне. С post_create вам пришлось бы ждать завершения установки, прежде чем окно вообще откроется. Это также означает, что AI-агенты могут сразу начать работу в своей панели, пока зависимости устанавливаются параллельно.

panes:
  # Панель 1: Установить зависимости, затем запустить dev-сервер
  - command: pnpm install && pnpm run dev

  # Панель 2: AI-агент
  - command: <agent>
    split: horizontal
    focus: true

Структура каталогов

Вот как workmux организует ваши worktree’ы по умолчанию:

~/projects/
├── my-project/               <-- Основной каталог проекта
│   ├── src/
│   ├── package.json
│   └── .workmux.yaml
│
└── my-project__worktrees/    <-- Worktree'ы, созданные workmux
    ├── feature-A/            <-- Изолированное рабочее пространство для ветки 'feature-A'
    │   ├── src/
    │   └── package.json
    │
    └── bugfix-B/             <-- Изолированное рабочее пространство для ветки 'bugfix-B'
        ├── src/
        └── package.json

Каждый worktree — это отдельный рабочий каталог для разных веток, использующих одно и то же git-репозиторий. Это позволяет работать над несколькими ветками одновременно без конфликтов.

Расположение каталога worktree можно настроить с помощью параметра worktree_dir (см. Параметры конфигурации). Значение поддерживает ~ для домашнего каталога и заполнитель {project}, который заменяется именем каталога основного worktree. Это позволяет одной глобальной конфигурации хранить все worktree’ы каждого репозитория в одном корневом каталоге, например worktree_dir: ~/.workmux/{project}.

Псевдоним шелла (рекомендуется)

Для ускорения ввода создайте псевдоним workmux → wm:

alias wm='workmux'

Команды

  • add — создать новый worktree и окно tmux

  • merge — слить ветку и убрать всё лишнее

  • rebase — переместить ветку worktree на базовую ветку

  • remove (rm) — удалить worktree’ы без слияния

  • list — вывести список всех worktree’ов со статусом

  • open — открыть окно tmux для существующего worktree

  • close — закрыть окно tmux worktree (сам worktree сохраняется)

  • resurrect — восстановить окна worktree после сбоя

  • path — получить путь в файловой системе для worktree

  • dashboard — показать TUI-дашборд всех активных агентов

  • sidebar — переключить компактную боковую панель статуса агентов в tmux

  • reap-agents — завершить отслеживаемые процессы агентов старше заданного порога

  • config edit — открыть глобальный конфигурационный файл для редактирования

  • init — создать конфигурационный файл

  • sandbox — управление песочницами (контейнер/Lima)

  • claude prune — очистить устаревшие записи Claude Code

  • completions — сгенерировать автодополнение для шелла

  • docs — показать подробную документацию

workmux add <branch-name>

Создаёт новый git worktree с соответствующим окном tmux и сразу переключает вас на него. Если ветка не существует, она будет создана автоматически.

  • <branch-name>: имя создаваемой или уже существующей ветки, ссылка на удалённую ветку (например, origin/feature-branch) или ссылка на форк GitHub (например, user:branch). Удалённые ветки и форки автоматически загружаются и создают локальную ветку с производным именем. Для форков локальная ветка формируется как user-branch (например, someuser:feature создаёт локальную ветку someuser-feature). Необязателен при использовании --pr.

Параметры

  • --base <branch|commit|tag>: указать базовую ветку, коммит или тег для ветвления при создании новой ветки. Переопределяет конфиг base_branch. Значение auto в конфиге использует эффективную главную ветку. Без обоих этих параметров workmux использует текущую ветку.

  • --pr <number|url>: извлечь pull request GitHub по его номеру или полному URL в новый worktree.

    • Требует установленной и аутентифицированной утилиты gh.

    • URL имеет вид https://github.com/<owner>/<repository>/pull/<number>;.

    • Имя локальной ветки по умолчанию соответствует имени ветки в PR, но его можно переопределить (например, workmux add custom-name --pr 123).

    • Если такая локальная ветка уже существует и не имеет worktree, она будет переиспользована.

  • -A, --auto-name: сгенерировать имя ветки из промпта с помощью LLM. Смотрите Автоматическая генерация имён веток.

  • --name <name>: переопределить имя каталога worktree и окна tmux. По умолчанию они формируются из имени ветки (в виде слага). Нельзя использовать при генерации нескольких worktree’ов (--count, --foreach или несколько --agent).

  • -b, --background: создать окно tmux в фоне без переключения на него. Полезно с --prompt-editor.

  • -w, --with-changes: перенести незафиксированные изменения из текущего worktree в новый, затем сбросить исходный worktree в чистое состояние. Полезно, когда вы начали работу в main и хотите перенести изменения в новый worktree.

  • --patch: интерактивно выбрать, какие изменения перенести (требует --with-changes). Открывает интерактивный запрос для выбора фрагментов для stash.

  • -u, --include-untracked: также перенести неотслеживаемые файлы (требует --with-changes). По умолчанию переносятся только изменённые и отслеживаемые файлы.

  • -p, --prompt <text>: задать встроенный промпт, который автоматически будет передан в панели AI-агентов.

  • -P, --prompt-file <path>: указать путь к файлу, содержимое которого будет использовано как промпт.

  • -e, --prompt-editor: открыть $EDITOR (или $VISUAL) для интерактивного написания промпта.

  • --prompt-file-only: записать файл промпта в worktree без инъекции в команды агентов. Панель агента не требуется. Полезно, когда ваш редактор имеет встроенного агента, читающего .workmux/PROMPT-*.md напрямую.

  • -l, --layout <name>: использовать именованную раскладку панелей из конфига вместо стандартных панелей. Нельзя комбинировать с --agent.

  • -a, --agent <name>: агент(ы) для worktree(s). Можно указывать несколько раз для создания отдельного worktree для каждого агента. Переопределяет agent из конфигурационного файла.

  • -W, --wait: блокировать до закрытия созданного окна tmux. Полезно для скриптинга, когда нужно дождаться завершения работы агента. Агент может сигнализировать о завершении, запустив workmux remove --keep-branch.

  • -o, --open-if-exists: если worktree для ветки уже существует, открыть его вместо ошибки. Аналогично tmux new-session -A. Полезно, когда вы не знаете или не важно, существует ли worktree.

  • -s, --session: создать сессию tmux вместо окна. Подробнее — в разделе о режиме сессии.

  • --dry-run: вывести итоговый путь worktree, ветку, базу, цель мультиплексора, файловые операции и хуки после создания без фактического создания или изменения чего-либо.

  • --config <path>: использовать альтернативный конфигурационный файл для этого вызова. Всё равно объединяется с глобальным конфигом.

  • --fork: форкнуть последний разговор из текущего worktree в новый. Агент продолжит работу с контекстом форкнутого разговора. Используйте --fork=<session-id> для форка конкретной сессии (поддерживается совпадение по префиксу). Поддерживается Claude Code и Codex.

Параметры пропуска шагов

Эти параметры позволяют пропустить дорогостоящие шаги настройки, когда они не нужны (например, для изменений только в документации):

  • -H, --no-hooks: пропустить выполнение команд post_create

  • -F, --no-file-ops: пропустить операции копирования/создания ссылок (например, пропустить создание ссылки на node_modules)

  • -C, --no-pane-cmds: пропустить выполнение команд панелей (панели открываются с обычными шеллами)

Что происходит

  1. Определяется дескриптор (handle) worktree путём формирования слага из имени ветки (например, feature/auth становится feature-auth). Можно переопределить флагом --name.

  2. Создаётся git worktree по пути <worktree_dir>/<handle> (каталог worktree_dir настраивается и по умолчанию является соседним каталогом вашего проекта).

  3. Выполняются настроенные файловые операции (копирование/создание ссылок).

  4. Выполняются команды post_create, если они определены (запускаются до открытия окна tmux, поэтому держите их быстрыми).

  5. Создаётся новое окно tmux с именем <window_prefix><handle> (например, wm-feature-auth при window_prefix: wm-).

  6. Настраивается заданная раскладка панелей tmux.

  7. Tmux-клиент автоматически переключается на новое окно.

В режиме окон tmux без --parent-session $TMUX_PANE идентифицирует вызывающую панель и её родительскую сессию. Если $TMUX_PANE отсутствует или устарел, workmux использует рабочие каталоги живых панелей, если их ближайшее совпадение указывает на одну сессию. Сервер tmux с одной сессией — последний запасной вариант. При сохраняющейся неоднозначности требуется --parent-session <name>. Рабочий каталог позволяет определить git-репозиторий и даёт только косвенные данные для размещения в tmux.

Примеры

Базовое использование
# Создать новую ветку и worktree
workmux add user-auth

# Использовать существующую ветку
workmux add existing-work

# Создать новую ветку от конкретной базы
workmux add hotfix --base production

# Создать worktree из удалённой ветки (создаёт локальную ветку "user-auth-pr")
workmux add origin/user-auth-pr

# Удалённые ветки со слэшами тоже работают (создаёт локальную ветку "feature/foo")
workmux add origin/feature/foo

# Предварительный просмотр плана без фактического создания
workmux add feature/parallel-task --dry-run

# Создать worktree в фоне без переключения на него
workmux add feature/parallel-task --background

# Использовать пользовательское имя для каталога worktree и окна tmux
workmux add feature/long-descriptive-branch-name --name short

# Открыть существующий worktree, если он есть, иначе создать (идемпотентно)
workmux add my-feature -o
Извлечение pull request’ов и веток форков
# Извлечь PR #123. Локальная ветка будет названа по ветке PR.
workmux add --pr 123

# Извлечь pull request по полному URL GitHub с пользовательской локальной веткой
workmux add --pr https://github.com/raine/workmux/pull/456 fix/api-bug

# Извлечь ветку форка в формате owner:branch из GitHub (скопировать из интерфейса GitHub)
# Создаёт локальную ветку "someuser-feature-branch", отслеживающую форк
workmux add someuser:feature-branch
Перенос изменений в новый worktree
# Перенести незафиксированные изменения в новый worktree (включая неотслеживаемые файлы)
workmux add feature/new-thing --with-changes -u

# Перенести только изменённые/отслеживаемые файлы (без неотслеживаемых)
workmux add fix/bug --with-changes

# Интерактивно выбрать, какие изменения перенести
workmux add feature/partial --with-changes --patch
Промпты для AI-агентов
# Создать worktree с встроенным промптом для AI-агентов
workmux add feature/ai --prompt "Implement user authentication with OAuth"

# Переопределить агента по умолчанию для конкретного worktree
workmux add feature/testing -a gemini

# Создать worktree с промптом из файла
workmux add feature/refactor --prompt-file task-description.md

# Открыть редактор для интерактивного написания промпта
workmux add feature/new-api --prompt-editor

# Только записать файл промпта (для редакторов со встроенными агентами, например neovim)
workmux add feature/task -P task.md --prompt-file-only
Пропуск шагов настройки
# Пропустить дорогостоящую настройку для изменений только в документации
workmux add docs-update --no-hooks --no-file-ops --no-pane-cmds

# Пропустить только файловые операции (например, node_modules не нужны)
workmux add quick-fix --no-file-ops
Скриптинг с --wait
# Блокировать до завершения агента и закрытия окна
workmux add feature/api --wait -p "Implement the REST API, then run: workmux remove --keep-branch"

# Использовать в скрипте для последовательных задач агентов
for task in task1.md task2.md task3.md; do
  workmux add "task-$(basename $task .md)" --wait -P "$task"
done

Интеграция с AI-агентами

При передаче промпта через --prompt, --prompt-file или --prompt-editor workmux автоматически инжектирует промпт в панели, запускающие настроенную команду агента (например, claude, codex, opencode, gemini, agy, kiro-cli, vibe, pi, omp, grok или любой другой, заданный через конфиг agent или флаг --agent) без необходимости изменять .workmux.yaml:

  • Панели с командой, соответствующей настроенному агенту, автоматически запускаются с заданным промптом.

  • Конфигурация панелей в .workmux.yaml может быть простой (например, panes: [{ command: "<agent>" }]), а инъекцией промпта во время выполнения занимается workmux.

Это означает, что вы можете запускать AI-агентов с промптами под конкретные задачи, не изменяя конфигурацию проекта для каждой задачи.

Если ваш редактор имеет встроенного агента (например, neovim с плагином-агентом), используйте --prompt-file-only, чтобы записать промпт в .workmux/PROMPT-<branch>.md без необходимости в панели агента. Редактор сможет обнаружить и обработать файл при запуске. Это также можно постоянно настроить в конфиге с помощью prompt_file_only: true.

Автоматическая генерация имён веток

Флаг --auto-name (-A) генерирует имя ветки из вашего промпта с помощью LLM. Используемый инструмент зависит от конфигурации:

  1. Если задан auto_name.command: используется эта команда как есть

  2. Если config.agent — известный агент (claude, gemini, agy, codex, opencode, kiro-cli, vibe, pi, omp): используется CLI агента с быстрой/дешёвой моделью

  3. Ни то ни другое: используется CLI-инструмент llm

Использование
# Открывает редактор для промпта, генерирует имя ветки
workmux add -A

# С встроенным промптом
workmux add -A -p "Add OAuth authentication"

# С файлом промпта
workmux add -A -P task-spec.md
Требования

Если настроен agent (например, agent: claude), workmux автоматически использует CLI этого агента для именования веток. Никакой дополнительной настройки, кроме установленного агента, не требуется.

Если агент не настроен и не задан auto_name.command, workmux использует CLI-инструмент llm:

pipx install llm

Настройте модель (например, OpenAI):

llm keys set openai
# Или используйте локальную модель
llm install llm-ollama

Если задан auto_name.command, llm не требуется.

Значения агентов по умолчанию

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

Агент Команда для авто-именования

claude

claude --model haiku -p

gemini

gemini -m gemini-2.5-flash-lite -p

codex

codex exec --config model_reasoning_effort="low" -m gpt-5.1-codex-mini

opencode

opencode run

kiro-cli

kiro-cli chat --no-interactive

pi

pi -p

omp

omp -p

Чтобы при настроенном агенте вернуться к llm, установите auto_name.command: "llm".

Конфигурация

При необходимости настройте поведение авто-именования в .workmux.yaml:

auto_name:
  model: 'gemini-2.5-flash-lite'
  background: true # Всегда запускать в фоне при использовании --auto-name
  system_prompt: |
    Generate a concise git branch name based on the task description.

    Rules:
    - Use kebab-case (lowercase with hyphens)
    - Keep it short: 1-3 words, max 4 if necessary
    - Focus on the core task/feature, not implementation details
    - No prefixes like feat/, fix/, chore/

    Examples of good branch names:
    - "Add dark mode toggle" → dark-mode
    - "Fix the search results not showing" → fix-search
    - "Refactor the authentication module" → auth-refactor
    - "Add CSV export to reports" → export-csv
    - "Shell completion is broken" → shell-completion

    Output ONLY the branch name, nothing else.

Чтобы использовать конкретный инструмент, задайте auto_name.command. Строка команды разбивается на программу и аргументы, а составленный промпт передаётся через stdin. Корректные имена git-веток сохраняются, включая префиксы с разделителями-слэшами, например fix/issue-123.

auto_name:
  command: 'claude -p'

# Принудительно использовать llm, даже если агент настроен
auto_name:
  command: 'llm'
Параметр Описание По умолчанию

command

Команда для генерации имени ветки (переопределяет профиль агента)

Профиль агента или CLI llm

model

Модель LLM для использования с CLI llm (игнорируется при задании command)

Стандартная модель llm

background

Всегда запускать в фоне при использовании --auto-name

false

system_prompt

Пользовательский системный промпт для генерации имён веток

Встроенный промпт

Рекомендуемые модели для быстрой и дешёвой генерации имён веток (с llm):

  • gemini-2.5-flash-lite (рекомендуется)

  • gpt-5-nano

Параллельные рабочие процессы и генерация нескольких worktree’ов

workmux может создавать несколько worktree’ов одной командой add, что идеально подходит для параллельных экспериментов или делегирования задач нескольким AI-агентам. Управляется четырьмя взаимоисключающими режимами:

  • (-a, --agent): создать worktree для каждого указанного агента

  • (-n, --count): создать указанное количество worktree’ов

  • (--foreach): создать worktree’ы на основе матрицы переменных

  • stdin: передать строки через pipe для создания worktree’ов с шаблонными промптами

При использовании любого из этих режимов имена веток генерируются по шаблону, а промпты шаблонизируются с переменными. Промпты для одиночного worktree передаются буквально, поэтому общий синтаксис вроде ${{ …​ }} из GitHub Actions не нужно экранировать.

Параметры нескольких worktree’ов

  • -a, --agent <name>: при многократном указании создаёт один worktree для каждого агента

  • -n, --count <number>: создаёт <number> экземпляров worktree. Можно комбинировать с одним флагом --agent для применения этого агента ко всем экземплярам

  • --foreach <matrix>: создаёт worktree’ы из строки матрицы переменных. Формат: "var1:valA,valB;var2:valX,valY". Все списки значений должны иметь одинаковую длину. Значения объединяются по индексу (zip, а не декартово произведение): первые значения каждой переменной идут вместе, вторые — вместе и т.д.

  • --branch-template <template>: шаблон в формате MiniJinja (совместимый с Jinja2) для генерации имён веток.

    • Доступные переменные: {{ base_name }}, {{ agent }}, {{ num }}, {{ index }}, {{ input }} (stdin) и любые переменные из --foreach

    • По умолчанию: {{ base_name }}{% if agent %}-{{ agent | slugify }}{% endif %}{% for key, value in foreach_vars %}-{{ value | slugify }}{% endfor %}{% if num %}-{{ num }}{% endif %}

  • --max-concurrent <number>: ограничивает количество одновременно работающих worktree’ов. При задании workmux создаёт до <number> worktree’ов, затем ждёт закрытия любого окна перед запуском следующего. Требует, чтобы агенты закрывали окна по завершении (например, через инструкцию в промпте запустить workmux remove --keep-branch).

Шаблонизация промптов

При создании нескольких worktree’ов любой промпт, переданный через -p, -P или -e, рассматривается как шаблон MiniJinja. Можно использовать переменные из режима генерации для создания уникальных промптов для каждого агента или экземпляра. Для обычных одиночных команд add текст промпта не шаблонизируется.

Матрицы переменных в файлах промптов

Вместо передачи --foreach в командной строке можно указать матрицу переменных прямо в файле промпта с помощью YAML-фронтматтера. Это удобнее для сложных матриц и позволяет держать переменные рядом с использующим их промптом.

Формат:

Создайте файл промпта с YAML-фронтматтером в начале, отделённым ---:

Пример 1: mobile-task.md

---
foreach:
  platform: [iOS, Android]
  lang: [swift, kotlin]
---

Build a {{ platform }} app using {{ lang }}. Implement user authentication and
data persistence.
workmux add mobile-app --prompt-file mobile-task.md
# Генерирует worktree'ы: mobile-app-ios-swift, mobile-app-android-kotlin

Пример 2: agent-task.md (использование agent как переменной foreach)

---
foreach:
  agent: [claude, gemini]
---

Implement the dashboard refactor using your preferred approach.
workmux add refactor --prompt-file agent-task.md
# Генерирует worktree'ы: refactor-claude, refactor-gemini

Поведение:

  • Переменные из фронтматтера доступны как в шаблоне промпта, так и в шаблоне имени ветки

  • Все списки значений должны иметь одинаковую длину, а значения объединяются по индексу (то же поведение zip, что и при -)

Похожее

© 2026 meganuke