Installation

SpecShip is Claude Code only — the installer configures one agent on purpose, so the surface stays small and easy to keep correct. If you need MCP integration with another agent that speaks the protocol, point it at specship serve --mcp by hand (see MCP & Claude Code wiring).

1. Get the CLI

Two routes put the specship binary on your machine — this is the only step where a package manager is involved:

npm i -g @specship/specship        # online

Or, with no npm and no network, use the offline bundle: download the release archive, extract, and run its install.sh / install.ps1.

2. Wire Claude Code

specship install

specship install is wiring-only — it never installs or updates the binary (and never touches npm). It:

• Asks whether to wire SpecShip into just this project (the default) or all projects (global). Pass --path <repo> to target a specific repo from anywhere.
• Writes the MCP server entry so Claude Code launches specship serve --mcp.
• Adds the read-only specship_* tools to Claude Code’s auto-allow list, so you aren’t prompted on every query.
• Installs the slash commands and the specship-explorer subagent.
• Adds the auto-sync hooks (re-index after the agent edits files; catch up on session start), the per-prompt steering nudge, and a session-start cheat-sheet of SpecShip’s commands (SPECSHIP_NO_CHEATSHEET=1 to silence).
• For a project-local install, initializes the target repo’s .specship/ and builds its index.

If the specship command isn’t on your PATH yet, the installer warns (Claude Code launches it by name) and points at both acquisition routes — it never runs them for you.

A default install gives you the full surface: the retrieval layer (the agent explores the index instead of re-reading files, plus a per-prompt nudge steering it there) and the spec-driven layer — the /specship:spec and /specship:check doors plus the “author a spec first” steering. Spec-driven development is on by default as of 0.18; pass --no-sdd for a retrieval-only install (the old default). An existing install is preserved on upgrade; it’s never silently downgraded.

Project-local vs global

A no-flag specship install is project-local by default — it writes to ./.mcp.json and ./.claude/settings.json, so SpecShip’s MCP tools only load for Claude Code sessions in this project. That keeps the always-on tool-list overhead out of sessions on unrelated projects.

Pass --location global to write to ~/.claude.json and ~/.claude/settings.json instead, so a single install works in every project you open.

Non-interactive (scripting / CI)

specship install --yes                        # project-local, auto-allow on, full surface
specship install --yes --location global      # all projects
specship install --with-jira --with-designer  # also enable the optional integrations
specship install --no-sdd                     # retrieval-only (skip the spec-driven layer)
specship install --no-permissions             # skip the auto-allow list
specship install --print-config               # print the MCP snippet, no file writes

Flag	Values	Default
--location	global, local	prompt (highlights local)
--path <repo>	target repo to wire + initialize, from any cwd	current directory
--yes	(boolean) non-interactive	prompt every step → local
--no-sdd	(boolean) skip the spec-driven layer (/specship:spec + /specship:check doors + steering) — retrieval-only	spec-driven layer ON
--with-jira	(boolean) enable the optional JIRA integration (talks to your Atlassian instance; never auto-allowed — Claude prompts per call)	off (core stays 100% local)
--with-designer	(boolean) enable the optional Designer integration (experimental — drives claude.ai/design via a debug Chrome session)	off
--no-permissions	(boolean) skip the auto-allow list	permissions on
--print-config	print the MCP snippet and exit	—

Integrations are remembered: a later plain specship install preserves an earlier --with-* opt-in — it never silently disables one.

The default install also wires a tiny per-prompt nudge that steers Claude Code toward specship_explore before it reads or edits code — the pattern that saves the most time. It only speaks in projects with a SpecShip index; set SPECSHIP_NO_STEERING=1 to turn it off (see Configuration for how to set environment variables).

--yes is non-interactive and resolves to a project-local install. Pass --location global alongside it for the old global behavior.

3. Restart Claude Code

Restart Claude Code so it picks up the new MCP server entry and loads the specship_* tools.

4. Initialize more projects

A project-local install already indexed the current project. For any other project:

cd your-project
specship init

specship init builds the per-project knowledge graph index (indexing runs by default — the old -i/--index flag is accepted but no longer needed). A global install then works in every project you open.

Supported platforms

Every release ships a self-contained build (bundled Node runtime — nothing to compile) for all three desktop OSes, on both x64 and arm64:

Platform	Architectures	Install
Windows	x64, arm64	PowerShell installer or npm
macOS	x64, arm64	shell installer or npm
Linux	x64, arm64	shell installer or npm

Offline / air-gapped install

Every release is a self-contained bundle — a vendored Node runtime plus the app, with zero native addons to compile — so it installs on a machine with no npm, no compiler, and no internet. Download the bundle on a connected machine, copy it across, and run the installer baked inside it.

1. On a machine with internet, grab the archive matching the offline machine’s platform from the Releases page — specship-<target>.tar.gz (or .zip on Windows), where <target> is one of darwin-arm64, darwin-x64, linux-x64, linux-arm64, win32-x64, win32-arm64.

2. On the offline machine, extract the archive and run the bundle’s own installer. It puts specship on your PATH, then asks where to wire Claude Code — globally (every project) or a specific repo (project-local, indexing that repo) — using only the bundled runtime; nothing is compiled and nothing is fetched:

tar -xzf specship-<target>.tar.gz
cd specship-<target>
./install.sh                     # interactive: asks global vs one repo
./install.sh --global            # non-interactive: wire all projects
./install.sh --path ~/dev/myrepo # non-interactive: wire + index one repo
./install.sh --skip-claude       # PATH only; wire later with `specship install`

Without a terminal (scripted installs), the default is global — the installer never writes project wiring into the bundle directory. On Windows the same choices are -Global, -Path C:\dev\myrepo, -SkipClaude.

On Windows, unzip specship-win32-<arch>.zip and run .\install.ps1 from the extracted folder. On macOS, clear Gatekeeper quarantine on the unsigned bundle first, or the launcher is blocked: xattr -dr com.apple.quarantine specship-<target>.

The installer honors SPECSHIP_INSTALL_DIR (default ~/.specship) and SPECSHIP_BIN_DIR (default ~/.local/bin); add the bin dir to your PATH if it isn’t already there. To reverse it, run ./install.sh --uninstall. Then, in any project:

cd your-repo && specship init

From a source checkout? scripts/offline-install.sh <bundle> (and scripts/offline-install.ps1 on Windows) does the same given a downloaded bundle directory or archive. This is a bundle-install path, not a build from source — it never runs npm or a compiler on the target.

The bundle vendors its own Node, so the offline machine needs no Node installed. npm i -g is not an offline path (it resolves per-platform packages from the npm registry) — use the release archive above.

Uninstall

specship uninstall

This reverses the installer — stripping SpecShip’s MCP server entry, the auto-allow permissions, the slash commands, the auto-sync hooks, and the spec-driven-development steering from Claude Code. It defaults to the same location as install (project-local), so an --yes install/uninstall pair stays symmetric; pass --location global to remove a global install. Your project indexes (.specship/) are left untouched — remove those per-project with specship uninit.