Install reference

macOS / Linux (Homebrew)

brew install saman-mb/tap/shipmates

Anywhere (Cargo)

cargo install shipmates

Binary Installer

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/saman-mb/shipmates/releases/download/vX.Y.Z/shipmates-installer.sh | sh

shipmates install --harness claude-code
shipmates install --harness opencode --local
shipmates install --harness all --dir /path/to/project

Installs into your global home directory by default. Use --local for the current directory, or --dir /path/to/project for a specific root. The crew and the thirteen commands land in the exact tree your harness reads, in its own native format — nothing is downloaded; the CLI compiles the payload from sources built into the binary. Full per-harness paths are in the table below.

One thing to know up front: five harnesses take the full crew (claude-code, opencode, antigravity, codex, github-copilot). The two skill-only harnesses (cursor, windsurf) have no native subagent directory, so only the thirteen commands land — the workflows still run, just without the named specialists.

shipmates install --harness claude-code              # crew + commands + all tools
shipmates install --harness claude-code --with-tools termgif,scrub
shipmates install --harness opencode --with-tools all   # same as omitting the flag
shipmates install --harness codex --with-tools none     # explicit crew-only

A tool is the third kind of shipmates resource, alongside the crew and the commands. Unlike a command, a tool is never invoked with a slash — the crew reach for it on their own when the intent of your prompt calls for it. shipmates-termgif, the first tool, renders a polished animated terminal demo GIF of a workflow run from a small JSON spec — see its tool page. Former short names (termgif, scrub) still select the namespaced tool at install.

Omitting --with-tools installs every bundled tool. Pass none for a minimal crew-only install, all explicitly (same as the default), or a comma-separated list for a subset. Each tool maps to the harness's own native tool surface: a native code tool on opencode (.opencode/tools/<name>.ts), and an agent-invoked Agent Skill in the shared .agents/skills/ tree everywhere else — on Claude Code pinned agent-only with user-invocable: false, so it never shows up as a slash command.

shipmates install --harness claude-code --global   # global home directory (default)
shipmates install --harness claude-code --local       # current directory
shipmates install --harness claude-code --dir /path/to/project

--global selects the global home directory explicitly. --local selects the current directory. --dir PATH selects an explicit root; it cannot be combined with either mode flag. The harness's own tree is created if it doesn't exist.

• Compiles the payload from its built-in canonical sources (commands/ + crew/), rendering each command and persona into the harness's own dialect — where its agents live, what its session metadata is called, which project-instructions file it reads.
• Writes into the tree each harness reads. Four harnesses (codex, antigravity, cursor, github-copilot) share one .agents/skills/ tree — rendered once, byte-identical, so a multi-harness install has a single copy, not four. Crew stay harness-native (.codex/agents/, .github/agents/, .agents/agents/). The rest keep their own root: .claude/, .windsurf/, and opencode's .opencode/commands/.
• Emits the thirteen skills whole — whatever a skill bundles comes along with its SKILL.md — and, on the five crew-bearing harnesses, the twelve crew personas: agents/*.md on claude-code, opencode and antigravity, agents/*.toml on codex, and agents/*.agent.md on github-copilot. The two skill-only harnesses (cursor, windsurf) get the skills and nothing else.
• Writes an install receipt at <target>/.shipmates/receipts/<harness>.json. The receipt records Shipmates version, harness, resolved layout, and each file Shipmates owns with its SHA-256 hash.
• Reinstalling is idempotent: unchanged receipt-owned files are skipped; changed receipt-owned files get a sibling .bak-… backup before replacement. New files are added. Symlinked target paths are rejected.
• A file already at a payload path is classified by its own frontmatter. One that names the artifact installed there is adopted — backed up, rewritten from the payload, and claimed in the receipt. One that does not is yours: install stops before writing anything and names shipmates install --force, which backs each up and replaces it.
• The payload is the one compiled into the binary. cargo run -- install inside a Shipmates checkout uses that checkout; any other source tree must be asked for with --from-cwd or SHIPMATES_SRC=/path/to/checkout.
• Warns about files recorded by the previous receipt but absent from the new payload instead of silently deleting them.

opencode takes the thirteen as flat commands/<name>.md files rather than skill directories. That is a safety decision, not a formatting one — opencode's skills are model-invoked and its SKILL.md has no disable-model-invocation equivalent, so commands/ is what keeps the thirteen user-invoked only. The reasoning is on the harness matrix.

One shared skills tree. codex, antigravity, cursor and github-copilot all read Agent Skills from the open .agents/skills/ location, so shipmates renders the thirteen skills once, in a neutral dialect, and writes them there — one source of truth, byte-identical across all four. Install several into one repo and you get a single .agents/skills/, not four divergent copies (which is what a per-harness rendering would collide into). The crew, whose formats differ, stay harness-native: .codex/agents/<name>.toml, .github/agents/<name>.agent.md, and .agents/agents/<name>.md for antigravity (the agy CLI, successor to the retired Gemini CLI). windsurf is deliberately left out of the shared tree — its docs make .windsurf/skills/ the canonical location and .agents/skills/ only a secondary scan — and claude-code keeps its own .claude/skills/.

ls .claude/agents
ls .claude/skills

You should see twelve .md files in agents/ and thirteen directories in skills/ each holding a SKILL.md — then run /ship-issue <issue#>.

For an opencode install, check the two directories it uses instead:

ls .opencode/agents
ls .opencode/commands

Twelve .md files in each. Note that no harness other than Claude Code has been verified at runtime — the payload formats were checked against each harness's parsing source and first-party docs, but no live run has confirmed that agents resolve or that /ship-issue completes. See the harness matrix.

shipmates doctor
shipmates doctor --local
shipmates doctor --dir /path/to/project
shipmates doctor --fix
shipmates doctor --fix --no-migrate

doctor uses the global home directory and the claude-code harness by default; pass --harness to check another harness, --local for the current directory, or --dir for an explicit root. It does not discover harnesses from receipts. It reports whether the harness tree is present, whether expected files are missing, whether installed files are modified or unreadable. It is read-only unless you pass --fix.

--no-migrate requires --fix. shipmates doctor --fix --no-migrate restores receipt-owned missing or modified files but leaves superseded legacy command files in place. Install migrates receipt-owned legacy files; a receipt-less tree preserves existing legacy files unless --force is explicit. A missing receipt reports ownership unknown and preserves existing files; an invalid receipt is a problem and --fix refuses ownership-based repair.

The receipt lives below the target at .shipmates/receipts/<harness>.json. It records harness, layout, version, and SHA-256 hashes for files Shipmates owns. shipmates uninstall defaults to the global home directory and discovers the harness only when exactly one valid receipt exists. With multiple valid receipts, pass --harness; an explicit missing or invalid receipt fails closed. It removes only unchanged, receipt-owned files and leaves modified, unreadable, or unmanaged files untouched.

shipmates uninstall
shipmates uninstall --local
shipmates uninstall --dir /path/to/project

Do not remove the whole harness directory: it may contain files the user owns. Uninstall is receipt-scoped, validates all sibling receipts first, and fails safe when ownership is uncertain. A shared-only block preserves the shared file while removing the selected receipt.

shipmates uninstall

Uninstall defaults to the global home directory; use --local or --dir for another root. It uses the receipt at <target>/.shipmates/receipts/<harness>.json. With one valid receipt, --harness is optional; with multiple valid receipts, specify it. Missing or invalid receipts fail closed, while no receipt directory is a no-op. It removes only files recorded there whose contents still match the hashes. Modified, unreadable, and unmanaged files are warned about and left untouched. The command never guesses by deleting a whole harness tree.