Your first task
A project is a git repository registered with Swarmed. A task is a branch of it, checked out in a worktree of its own. A session is one agent at work in that worktree.
In the app
Section titled “In the app”Open the app, add a repository, start a task and say what the agent should do. Swarmed creates the branch and the worktree, runs the repository’s setup hook if it has one, and starts the agent there.
The app speaks in swarm words until Settings → Appearance switches it to plain ones: adding a repository is Found a colony, a new task New brood.
Permission requests, questions and plans are answered in the conversation. The task’s panel shows what changed, and from there the work is committed, pushed and opened as a pull request, each a step of its own behind a button.
From a terminal
Section titled “From a terminal”The same, with the swarmed command:
swarmed project add ~/code/shop # register a git repositoryswarmed task new shop fix-login # branch, worktree, setup hookswarmed session run shop fix-login "Fix the login form's error message"swarmed session send 12 "Add a test for it" # the id `session run` printedswarmed task commit shop fix-login -m "Fix the login form's error message"swarmed task push shop fix-loginswarmed task pr shop fix-login # through your own ghswarmed task rm shop fix-login # teardown hook, worktree removedsession run and session send print the conversation as it happens and ask on the terminal
when the agent wants permission ([y/N]). Ctrl-C stops the turn, not the session. They exit
non-zero when the turn is stopped or fails, so a script can tell.
task rm refuses while the worktree has uncommitted changes or unpushed commits; --force
removes it anyway.
Trying it without spending tokens
Section titled “Trying it without spending tokens”SWARMED_FAKE_AGENT=1 swaps in a scripted agent that spends no tokens:
SWARMED_FAKE_AGENT=1 swarmed session run shop fix-login "hello"Where the work is
Section titled “Where the work is”The worktree is at ~/swarmed/<project>/<task>. Nothing is written into your repository apart
from the task’s branch, and an empty first commit if the repository had none, since a branch
needs a commit to start from.
- Hooks, stacks and ports: have each task set itself up and run its own dev server.
- Coding agents: run a session on something other than Claude Code.
- Supervision: how much an agent may do without asking.