Skip to content

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.

swarmed project add writes a commented template, and swarmed project config <project> prints where it is.

Terminal window
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.

Each hook runs with sh -c in the task’s worktree, and an empty one is skipped.

  1. 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.
  2. When setup succeeds, start is started and kept running, with its output in a log. Starting one stack more than max_stacks is refused.
  3. Stopping a stack runs stop, then ends whatever start started, including what it started in process groups of their own.
  4. 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.

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.