Skip to content

Getting started

By the end of this page you'll have a working mship workspace, one finished task, and one merged PR — the full loop you'll repeat for everything else.

Install

uv tool install git+https://github.com/atomikpanda/mothership.git

Requires Python 3.14+ and uv. Optional but recommended: go-task (task execution) and gh (mship finish uses it to open PRs).

The install also provides mshipd, the always-on host daemon — managed via mship daemon ... (docs/daemon.md), never invoked directly.

Create a workspace

From the directory that contains your repo(s) — one repo, several, or a monorepo:

cd my-project
mship init --name my-project --detect

--detect scans the current directory for git repos and registers them. This writes two things:

  • mothership.yaml — the workspace config: your repos, their dependency order, test/run targets. Committed, shared with the team. Full reference: Configuration.
  • .mothership/ — local state (active tasks, journals). Gitignored.

Create a work item

mship item new "hello world" --kind chore
# wi-20260725. . . created

Every task belongs to a work item — the durable record of why the work exists. It's the first of mship's three gates: chore and bug items go straight to work; feature items ask for a design first (see Ship a feature).

Spawn the task

mship spawn "add hello world" --work-item <the-wi-id>
# task 'add-hello-world' spawned
#   my-project: .worktrees/add-hello-world/my-project  (branch feat/add-hello-world)

A task is the execution unit: mship creates a git worktree per affected repo, all on a shared feature branch, isolated from main. Move into it:

cd $(mship status | jq -r '.resolved_task.worktrees | to_entries[0].value')

Do the work

Edit files normally inside the worktree, then commit:

echo 'print("hello")' > hello.py
git add hello.py && git commit -m "feat: hello world"

While a task is active, mship's guards refuse commits and (for Claude Code sessions) edits to the repo's main checkout — parallel tasks can't collide, and nothing lands on main by accident.

Test

mship test
# my-project: pass (12 passed)  — diff vs previous run: no regressions

With several repos, mship test runs them in dependency order — schemas before the services that consume them — and reports per-repo results.

Finish

mship finish --body-file - <<'EOF'
## Summary
First mship task.
## Test plan
- [x] Runs locally.
EOF
# my-project: PR opened https://github.com/you/my-project/pull/1

finish pushes the branch and opens the PR (PRs, plural, in dependency order for multi-repo tasks). It also runs the gates: the work item must exist, and for feature items an approved spec and plan (details: Concepts).

Merge, then close

Merge the PR however you normally do (web UI or gh pr merge). Then:

mship close
# Closed: completed (1 prs merged): add-hello-world

close verifies the PR state, tears down the worktrees, and clears the task from .mothership/state.yaml. The loop is complete.

Where next