Skip to content

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.

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.

The same, with the swarmed command:

Terminal window
swarmed project add ~/code/shop # register a git repository
swarmed task new shop fix-login # branch, worktree, setup hook
swarmed 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` printed
swarmed task commit shop fix-login -m "Fix the login form's error message"
swarmed task push shop fix-login
swarmed task pr shop fix-login # through your own gh
swarmed task rm shop fix-login # teardown hook, worktree removed

session 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.

SWARMED_FAKE_AGENT=1 swaps in a scripted agent that spends no tokens:

Terminal window
SWARMED_FAKE_AGENT=1 swarmed session run shop fix-login "hello"

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.