Tasks

A task is a prompt that gets its own git worktree, branch and wrapped agent, so several agents can work in the same repository without stepping on each other.

cd ~/src/api
pilothouse task new "make the auth test deterministic"

This:

1. creates a branch pilothouse/<slug> from your current branch,
2. creates a worktree for it under ~/.pilothouse/worktrees/<repo>/<slug>,
3. starts the agent there in wrap mode, detached, with your prompt as its first message,
4. shows the task in the inbox, on your phone, and in pilothouse task ls.

Your rules and approvals apply exactly as they do anywhere else.

Options

pilothouse task new [--agent claude|codex] [--base <ref>] [--name <slug>] [-a|--attach] "<prompt>"

Flag	Meaning
--agent	Which agent to run (default claude)
--base	Branch or commit to start from (default: the current branch)
--name	Slug for the branch and worktree (default: derived from the prompt)
-a, --attach	Attach to the agent right away instead of starting detached

Follow along

pilothouse task ls          # status comes from the task's session
pilothouse attach <id>      # watch or talk to the agent
pilothouse task diff <id>   # git diff <base>...<branch>

Finish

pilothouse task done <id>         # remove the worktree, keep the branch
pilothouse task done <id> --pr    # push the branch and open a PR (gh pr create --fill)
pilothouse task done <id> --keep  # keep the worktree too
pilothouse task abandon <id>      # throw it away

--pr uses the GitHub CLI (gh), so it needs to be installed and logged in.

Tips

• Tasks are plain git branches and worktrees. You can cd into the worktree, run the tests yourself, or commit on top.
• Combine tasks with a rule like ask-before-push-main so parallel agents can push their own branches but never main.
• Queues, concurrency limits and headless runs are not in v0.1.