A structured interface between AI coding agents and a running multi-repo system.
Pre-1.0. API may change. Pin a commit if you need stability.
Consider a single feature that touches five repos: the shared schemas, two microservices that depend on those schemas, the api that sits in front of the microservices, and the api-client consumed by a web app. An agent (or team of them) working on this feature has to hold all five in its head simultaneously — make the schema change, propagate it to both microservices, update the api to match, regenerate the client, and verify the whole thing works end-to-end. Then open five PRs that need to land in the right order.
Today, that coordination is almost entirely in the agent's head, and agents are bad at it. They commit to main in the wrong repo because they forgot git checkout. They edit the api in the main checkout while their feature branch for the api lives in a worktree they never cd'd into. They lose track of what changed in schemas while working in the microservice. They open the api-client PR before the schemas PR and reviewers can't evaluate either in isolation. They declare done on unit tests in one repo while the contract break with another repo goes unnoticed until integration.
And even when the coordination works, the observation fails. The agent has five services in five worktrees. Which log file belongs to the microservice it just changed? Which port is the api on in this task's worktree, not the main checkout? Did the schemas migration run before the microservice tried to read the new column? Without structured answers, the agent falls back to a grab bag of shell commands and guesswork — and when it guesses wrong, the failure mode is silent: tests pass in each repo, the feature "works" locally, and the bug surfaces in staging after five PRs have already merged.
mship is built for this shape of problem: a feature that spans multiple repos, an agent that needs to coordinate changes across them and observe the running system as a single thing. It also works for simpler cases — a single repo, a monorepo, or two or three loosely-coupled services — but metarepo-scale coordination is the problem it was designed to solve.
uv tool install git+https://github.com/atomikpanda/mothership.git
cd my-project
mship init --name my-project --detect
mship item new "hello world" --kind chore # every task needs a work item...
mship spawn "add hello world" --work-item <id> # ...pass its id (or --hotfix to skip the gate)
cd $(mship status | jq -r '.resolved_task.worktrees | to_entries[0].value')
echo 'print("hello")' > hello.py
git add hello.py && git commit -m "feat: hello world"
mship finish --body-file - <<'EOF'
## Summary
First mship task.
## Test plan
- [x] Runs locally.
EOFRequires Python 3.14+ and uv. Optional: go-task for task execution, gh for mship finish.
The quickstart above is deliberately minimal — one repo, one file — to show the task lifecycle in isolation. For the multi-repo case mship was built for, see docs/configuration.md for mothership.yaml examples with dependency graphs, healthchecks, and env_runner delegation, and docs/cli.md for the full command surface including mship spawn --repos, mship switch, and cross-repo mship finish.
# Workflow
mship spawn "description" --work-item <id> # start a task in isolated worktrees (needs a work item; --hotfix to skip)
mship switch <repo> # context switch across repos
mship phase plan|dev|review|run # transition through phases
mship test # run tests in dependency order
mship finish --body-file - <<'EOF'... # open PR(s)
mship close # clean up task state and worktrees
# Work items & specs
mship item new "title" --kind feature|bug|chore|question # durable unit of intent behind a task
mship spec new --title "title" # design a spec; approve before feature dev/finish
mship spec dispatch <id> # bind an approved spec to a task + emit a handoff
# Task dependencies (#104)
mship spawn "downstream" --work-item <id> --depends-on a,b # declare at spawn (--work-item required)
mship depends add/remove/list # manage task-to-task dependency edges
mship finish --bypass-deps # ship a downstream even if upstream isn't ready
# Inspection
mship status # active task, phase, branch, drift
mship journal # task log with context
mship context # JSON snapshot of workspace state
mship graph # dependency graph across all tasks
mship export [--redacted] # bundle task artifacts to share (opt-in secret redaction)
# Messaging (phone <-> agent)
mship serve [--relay] # JSON API + mailbox backing the Ground Control app
mship inbox wait # block until the next human message arrives
mship reply <thread> "text" # answer a mailbox threadFor details, see mship spawn --help, docs/cli.md, and the working-with-mothership skill.
Cross-repo coordination as a first-class concept. A task in mship is a single unit of work that can span many repos. mship spawn "propagate user schema v2" --work-item <id> --repos schemas,svc-users,svc-billing,api,api-client creates one worktree per repo on a shared feature branch. mship test runs them in dependency order. mship finish opens five PRs in dependency order with coordination blocks in each body linking the others. Audits catch drift per repo. The agent operates on "the task" — mship tracks which files across which repos belong to it.
Isolation that makes coordination safe. Every worktree is on its own feature branch, separate from main. A pre-commit hook refuses commits from outside the active task's worktrees. mship also installs a Claude Code PreToolUse guard (mship _guard-edit, added by mship init --install-hooks) that refuses an Edit/Write to a repo's main checkout while that repo has an active task — closing the gap that the git pre-commit hook can't see, since edit tools bypass git. Override a one-off with MSHIP_ALLOW_MAIN_EDIT=1. Parallel tasks on different features get their own worktree sets and don't collide.
A running system to observe, not guess at. mship run brings up the task's services in dependency order, waits on per-service healthchecks (tcp, http, sleep, or a custom task), and keeps background services alive so the agent can interact with them. Ports and URLs are task-scoped — two tasks running in parallel don't fight over localhost:3000. This matters most for the metarepo case, where "the running system" means five services that have to talk to each other.
Structured state instead of shell archaeology. mship status, mship context, and mship journal emit JSON when stdout isn't a TTY. The agent asks for the active repo, the worktree paths, the branches, the last test result per repo, the open blockers — it gets structured answers, not text to parse. Combined with the runtime, this means an agent can know which log file belongs to which service, which URL to hit, and which test command to run in each repo, without a single find or ps or lsof.
A phase lifecycle that keeps the whole feature honest. plan → dev → review → run with soft gates on each transition — warns on moving to dev without a spec, to review with failing tests in any affected repo, to run with uncommitted changes anywhere in the task. The lifecycle is task-scoped, not repo-scoped, so a feature across five repos has one phase, not five.
A dispatch primitive for session handoff. mship dispatch --task <slug> -i "<instruction>" prints a self-contained subagent prompt — cd directive, branch state, recent journal entries, and a closing contract — so a fresh agent session can pick up a multi-repo task without parent-held context. By default it emits implementer framing: scope to the single task, report back, don't open a PR (the orchestrator finishes). Pass --mode standalone for the older "finish and open the PR yourself" contract.
Tasks live in git worktrees managed by mship and tracked in .mothership/state.yaml. The runtime layer (mship run) reads a topology from mothership.yaml — services, dependencies, healthchecks, env_runner for secret delegation, start_mode: background for long-running services — and brings the stack up in dependency-ordered tiers. The interface layer (mship status, context, journal, dispatch) exposes that state to agents as structured output. The coordination layer (phases, audits, the pre-commit hook, mship finish) keeps state consistent across sessions and across repos.
Agents plug into this through any MCP server or shell tool they already have. mship doesn't replace bash, playwright-mcp, or postgres-mcp; it tells those tools where to point and what's real.
To edit mothership.yaml or a per-repo Taskfile, edit it directly in the main checkout, run mship doctor, then commit. mship exempts config-only edits (drift confined to mothership.yaml and/or a Taskfile) from the dirty_worktree audit gate, so mship finish is not blocked on them — the moment any non-config tracked file is also modified, the gate re-applies (fail-closed). mship doctor loads config with path validation relaxed (require_paths=False), so a not-yet-present or in-flux Taskfile.yml surfaces as a doctor check rather than hard-failing config load before your change lands. mship status and mship doctor also report the resolved mothership.yaml path and how it resolved (env / marker / walk-up), so you always know which config is live.
.worktrees/ (full checkouts, including node_modules) and .mothership/ live at the repo root. Any bundler that does not honor .gitignore — AWS CDK Code.fromAsset, the Docker build context, npm pack, sam build, serverless — must exclude them explicitly, or it will ship worktree checkouts into your build output. The .worktrees entry mship spawn adds to .gitignore protects git but not those bundlers; mship doctor emits a best-effort warning when it spots a bundling config at the workspace root that doesn't exclude .worktrees/.mothership.
- Does: isolate worktrees per task, coordinate cross-repo work, sequence PRs, run dependency-ordered multi-service stacks with healthchecks, expose task-scoped state to agents as structured JSON, emit handoff prompts for subagents.
- Does not: run the agent, generate code, manage secrets (delegates to
env_runner), replace CI. - Works for: multiple repos in one workspace (the primary case), a monorepo (via
git_root), or a single repo.
docs/concepts.md— how the pieces fit: WorkItem, Spec, Plan, Task, worktrees, agents/subagents (with diagrams).docs/cli.md— full command surface.docs/configuration.md—mothership.yaml, healthchecks, service start modes, monorepo rules, task aliasing, drift policy.docs/cloud-agent-auth.md— GitHub auth for cloud/unattended agent sessions (token broker setup, GitHub App,mship gh preflight).docs/relay-hosting.md— self-hosting themship serve --relaytunnel relay.mship skill install— installs the agent-side skill bundle (includingworking-with-mothership), which is the canonical guide for agents operating inside an mship workspace.
MIT