Herdr Worktree Dispatcher

Standalone Herdr plugin that dispatches coding tasks into temporary git worktrees and starts an agent in the new checkout. The public entrypoint remains scripts/dispatch.sh; the implementation is TypeScript compiled to dist/cli.js for npm packages.

What It Does

• Creates a Herdr-managed git worktree under the current workspace with add.
• Starts an agent in the new worktree workspace.
• Builds a persistent task prompt file and starts the agent with that file.
• Requires every dispatched task to produce a file artifact, including analysis and review reports.
• Splits independent multi-task requests across multiple workers where possible.
• Finalizes implementation tasks with merge --token, which verifies clean checkouts, integrates the branch, and removes the temporary worktree.
• Ships with an optional coding-agent skill in skills/worktree-dispatcher/, including SKILL.md and a skill-local scripts/dispatch.sh wrapper.

Requirements

• Herdr 0.7.0 or newer.
• Node.js 20 or newer.
• Herdr plus an agent CLI. The default command is opencode, which the dispatcher runs as opencode --prompt "$(cat .herdr-worktree-dispatcher/PROMPT-<label>.md)" inside the child worktree.

Install From npm

npm install -g herdr-worktree-dispatcher
herdr-worktree-dispatcher install --agent all

The npm package is built during npm pack / npm publish using prepack, so users do not need TypeScript installed globally or a local build step.

install links the Herdr plugin, creates config.env if it does not already exist, and installs the companion skill. Supported skill targets are OpenCode, Claude Code, Codex, and Pi:

herdr-worktree-dispatcher install --agent opencode
herdr-worktree-dispatcher install --agent claude
herdr-worktree-dispatcher install --agent codex
herdr-worktree-dispatcher install --agent pi
herdr-worktree-dispatcher install --agent all
herdr-worktree-dispatcher install --skill-dir ~/.custom-agent/skills

Without --agent, the installer auto-detects existing agent homes and only installs matching skills. --agent all creates all default skill directories. Pi skills install to ~/.pi/agent/skills.

Install For Local Development

npm install
npm run build
scripts/install.sh
herdr plugin action list --plugin worktree.dispatcher

The install script links this checkout as the worktree.dispatcher Herdr plugin, creates $(herdr plugin config-dir worktree.dispatcher)/config.env from examples/config.env if it does not already exist, and symlinks the companion worktree-dispatcher skill into detected local agent skill directories. Build dist/cli.js before running the plugin after TypeScript changes.

Useful install variants:

scripts/install.sh --config-only
scripts/install.sh --skip-skill
scripts/install.sh --skill-dir ~/.claude/skills --copy-skill

Run Directly

scripts/dispatch.sh add --merge -- "implement the task"

Run the dispatcher from the target git workspace. --cwd is intentionally unsupported; if the current workspace/PWD is not inside a git repository, dispatch fails.

When using the global worktree-dispatcher skill from another repository, the skill should call this plugin checkout's script if the target repo does not have its own scripts/dispatch.sh:

DISPATCH_SH="scripts/dispatch.sh"
[ -f "$DISPATCH_SH" ] || DISPATCH_SH="/Users/mac/Documents/playground/herdr-worktree-dispatcher/scripts/dispatch.sh"
bash "$DISPATCH_SH" add --merge -- "implement the task"

The repository includes examples/config.env as a template. Your real local config should live in Herdr's plugin config directory:

mkdir -p "$(herdr plugin config-dir worktree.dispatcher)"
cp examples/config.env "$(herdr plugin config-dir worktree.dispatcher)/config.env"

When Herdr runs the plugin, scripts/dispatch.sh automatically reads $HERDR_PLUGIN_CONFIG_DIR/config.env if it exists. Use --config only to override that path for one command.

Use a config profile so daily commands stay short:

scripts/dispatch.sh add --profile fast -- "fix the bug"

When running outside Herdr's plugin environment, point the dispatcher at a config file:

export HERDR_WORKTREE_DISPATCHER_CONFIG=/Users/mac/Documents/playground/herdr-worktree-dispatcher/examples/config.env
scripts/dispatch.sh add --profile fast -- "fix the bug"

Use a prompt file for larger tasks:

scripts/dispatch.sh add -P /tmp/task.md

By default, the dispatcher creates a branch like worktree/<task-slug>-<timestamp> so repeated smoke tests or repeated task prompts do not collide. Use --branch only when you need a specific branch name.

The workspace label is generated from task keywords rather than raw file paths or line numbers. If you want an exact sidebar name, pass --name:

scripts/dispatch.sh add --name "readme-install-docs" -- "update README installation instructions"

Choose the pane layout for the child agent:

scripts/dispatch.sh add --layout right -- "fix the bug"
scripts/dispatch.sh add --layout down -- "fix the bug"

The dispatcher creates the worktree through Herdr and starts the child agent in a split inside that worktree workspace. right opens the agent to the right. down opens the agent below. The child agent starts without taking focus, so you can keep working from the pane that launched the task.

Smoke-test the dispatcher without asking the child agent to edit code:

scripts/dispatch.sh add --merge --smoke-test -- "test task"

Smoke tests run in a worktree. With --merge, the child agent only executes the merge command if it actually creates a commit; no-change smoke tests leave the agent/worktree open for inspection.

Use --merge for normal dispatches so changed worktrees can come back automatically:

scripts/dispatch.sh add --merge -- "fix the bug and verify it"

--merge does not block the add phase. It writes a lifecycle token and gives the child agent an exact scripts/dispatch.sh merge --token PATH command. The prompt tells the child agent to run that command only after it has verified and committed its own changes. If it made no changes or no commit, it must not run merge/cleanup and should leave the worktree open.

Run a merge token manually if the child agent reports it instead of executing it:

scripts/dispatch.sh merge --token /tmp/herdr-worktree-dispatcher-cleanup/task-20260628120000-12345.json

Send a follow-up message to a dispatched worker using the same lifecycle token:

scripts/dispatch.sh message --token /tmp/herdr-worktree-dispatcher-cleanup/task-20260628120000-12345.json -- "please also check the docs"

You can also target any Herdr agent directly:

scripts/dispatch.sh message --agent wt-fix-the-bug -- "please pause before merging"

Dispatch an analysis task:

scripts/dispatch.sh add --merge -- "analyze the implementation and write findings to docs/implementation-review.md"

Analysis, review, research, and planning tasks still produce files, typically Markdown reports. The child agent should only skip merge/cleanup when the user explicitly asks for chat-only output or no file changes.

For multiple tasks, split them by dependency. Numbered or bulleted issue lists are parallel by default: dispatch each independent item as its own worker unless there is a concrete dependency or likely edit conflict. Dependent tasks should wait for their prerequisites to merge or publish their artifact path.

Use another interactive agent command:

scripts/dispatch.sh add --agent "opencode" -- "fix the failing test"

For the default opencode command, the dispatcher writes the prompt to .herdr-worktree-dispatcher/PROMPT-<label>.md inside the child worktree, adds that directory to git exclude, and starts opencode --prompt "$(cat .herdr-worktree-dispatcher/PROMPT-<label>.md)". Custom agent commands are treated as interactive pane commands; for those, the dispatcher resolves the started pane and submits the prompt with herdr pane send-text and herdr pane send-keys Enter.

Pass arguments to the agent command:

scripts/dispatch.sh add --agent "opencode" --agent-arg "--model=gpt-5.1" -- "fix the bug"
scripts/dispatch.sh add --agent "opencode" --agent-arg "--debug" --agent-arg "--model=gpt-5.1" -- "fix the bug"

Agent Skill

Copy or symlink the whole skills/worktree-dispatcher directory into your coding agent's skills directory if you want a worktree-dispatcher skill instruction. Include both SKILL.md and scripts/dispatch.sh; the skill-local script is the stable entrypoint agents call when the target repo does not have its own dispatcher script.

The skill is intentionally narrow: it tells the current agent not to inspect the repo before dispatching and to call add --merge. The child prompt makes merge/cleanup conditional on an actual commit.

Broad requests such as "分析当前实现" or "分析代码实现" are intentionally treated as sufficient context for repository-wide analysis, so the dispatcher skill should not ask a follow-up question for a file or feature name.

Short prompts that should trigger the skill in OpenCode:

派发：修复登录刷新问题
分发这个任务：review 当前实现并写到 docs/review.md
开 worker 做：给 README 补安装说明
用 dispatcher 跑：分析 cleanup 流程并产出报告
send to worker: fix the failing test

Config File

The config file is named config.env to match common Herdr plugin setup docs, but its content is INI-like. [default] applies first, then [profile.NAME] overrides it. Repeated agent_arg keys append arguments.

[default]
agent = opencode
layout = right

[profile.merge]
agent_arg = --model=gpt-5.1
merge = true

Supported keys are agent, repeated agent_arg, layout, merge, and merge_mode. merge_mode defaults to rebase and can be set to merge. CLI flags such as --layout and --merge-mode override config values.

Notes

This plugin does not reimplement Workmux. It delegates worktree creation and removal to Herdr, then composes Herdr's public agent-start surface to run the child agent.

New changes should be made in src/ and compiled with npm run build for local testing. dist/ is ignored by git and generated automatically for npm packages by npm run build via prepack.