Branches
A full copy of the backend, schema and data, where the agent can change anything.
Every project starts with one branch, main, the one your users talk to. A new branch is a full
copy of its parent: the same schema and the same rows. Nothing done on it reaches main until
you promote it, and nothing on it is held for approval.
Create one
npx shipmantis branch create try-tagsCreated try-tags from main at version 4.
Use it with --branch try-tags, or MANTIS_BRANCH=try-tags.Pass --from <branch> to copy another branch instead of main. A name is a lowercase letter
followed by up to 20 lowercase letters, digits and dashes.
Use it
Every command, every MCP tool and the client take the branch the same way:
| Where | How |
|---|---|
| The CLI | --branch try-tags, or MANTIS_BRANCH=try-tags in the environment or .env.local. |
| The MCP tools | The branch argument, or MANTIS_BRANCH. |
| The client | createClient({ ..., branch: "try-tags" }). |
Without one, everything uses main.
npx shipmantis push --branch try-tagsOn a branch every step applies at once, including the ones that would be held on main. That is
the point: the agent drops the column, runs the app against the branch, and sees what breaks.
Files are the exception: they belong to the project, every branch
reads main's files, and uploads and deletes with a branch selected are refused.
Promote it
npx shipmantis branch promote try-tagsPromoting applies the branch's schema to the branch it came from, as one migration. The data is
not copied: rows written on the branch stay there. If the parent is main and the migration has
a destructive step, it is held for a person's approval like any other push, and the command exits
with code 2.
List and delete
npx shipmantis branch list
npx shipmantis branch delete try-tagslist shows each branch and the one it came from. Deleting a branch drops its copy of the data.
main can't be deleted.