Hooks, stacks and ports
A task has a stack: what the project’s hooks set up and keep running in its worktree. With hooks and ports configured, two tasks can run the same app at once without stepping on each other.
A project’s configuration
Section titled “A project’s configuration”swarmed project add writes a commented template, and swarmed project config <project> prints
where it is.
port_step = 100
[ports]web = 3000
[hooks]setup = "cp {{repo}}/.env .env && npm ci"start = "npm run dev -- --port {{port.web}}"
[env]WEB_PORT = "{{port.web}}"Every key is listed under Project configuration.
Hooks and the stack
Section titled “Hooks and the stack”Each hook runs with sh -c in the task’s worktree, and an empty one is skipped.
- A new task gets its branch and worktree, then its environment’s snapshot, then
setup. A task whose setup failed is kept, and setup can be run again. - When
setupsucceeds,startis started and kept running, with its output in a log. Starting one stack more thanmax_stacksis refused. - Stopping a stack runs
stop, then ends whateverstartstarted, including what it started in process groups of their own. - Removing a task stops its agents and its stack, runs
teardown, and removes the worktree. It is refused while the worktree has uncommitted changes or unpushed commits, unless forced. The branch stays unless you ask for it to go.
Quitting the app ends its stacks’ processes without running stop. From the command line,
swarmed task new and swarmed task setup end the stack again when they exit, and
swarmed task start keeps one running in the foreground.
Each task has a slot: the lowest number from 1 that no other task of the project holds. A task’s
port is base + slot × port_step, so with web = 3000 the first task’s is 3100 and the second’s
3200. Slot 0, port 3000, is left to the main checkout.
Variables
Section titled “Variables”Hooks, env values and open_url may use these. An unknown name is an error.
| Variable | Is |
|---|---|
{{project}} |
the project’s name |
{{task}} |
the task’s name |
{{user}} |
your user name on this machine ($USER) |
{{branch}} |
the task’s branch |
{{slot}} |
the task’s slot |
{{worktree}} |
the task’s worktree |
{{repo}} |
the main checkout |
{{port.<name>}} |
the task’s port of that name |
In a hook, a value is always one word, whatever is in it: a path with a space needs no quotes,
and a branch’s name is never read as a command. The same values are exported to hooks as
SWARMED_PROJECT, SWARMED_TASK, SWARMED_USER, SWARMED_BRANCH, SWARMED_SLOT,
SWARMED_WORKTREE, SWARMED_REPO and SWARMED_PORT_<NAME>.
The task’s agents get env too, but not the SWARMED_* variables, and Claude Code gets no
variable whose name starts with ANTHROPIC_ or CLAUDE.