🚢 Ship

Turn Claude Code into a repeatable path from idea to production.

Ship researches, specifies, builds, tests, and prepares your project for release — while stopping for your approval before important decisions or external actions. Instead of relying on one long chat, it keeps plans, acceptance criteria, QA findings, and release evidence in versioned files inside your repository.

Free and open source · MIT · v0.10.5 · Beta · Not affiliated with Anthropic

Ship itself is free and has no subscription. Claude Code and model/API usage are still billed according to your own Anthropic setup.

_{Actual output, not a mockup. Skillbinka was built during Ship's second end-to-end dogfooding run.}

What the experience looks like

This is a condensed trace from that run. It is shortened for readability, not presented as a verbatim transcript or benchmark:

> /ship

What are you building?
> A free English-language catalog of Claude Code skills,
> organized by profession, with install and usage instructions

Set up ✓
Research and positioning complete ✓

Approve the profession-first scope? [y/N]
> y

Initial "modern marketplace" direction rejected
Choose a visual concept:
> Index-Card Catalog

Specification frozen ✓
Astro catalog built ✓
Browser journeys checked on desktop and mobile ✓
Independent QA verified 3 critical, 13 major, and 8 minor findings
Fix pass completed; critical findings re-verified ✓

Waiting for you:
Choose production host, domain, and analytics

You provide the idea and make the decisions. Ship manages the process and leaves an auditable trail in the project.

Quick start

Install Ship:

/plugin marketplace add vadimsv1/ship-plugin
/plugin install ship@ship-marketplace

Then open Claude Desktop or Cowork and start with:

/ship

Add your idea on the same line if you want: /ship Build a small portfolio site. Ship asks only for missing information and whether this is a quick experiment or a real project. That is the only workflow you need to learn.

Claude Code namespaces plugin skills in its slash-command menu; there the same orchestrator can appear as /ship:ship. You can also simply ask Claude to “use Ship” for the project.

For a low-commitment first try, use a small repository and choose Quick experiment. Ship will use the shorter Lite flow instead of the full production pipeline.

Requirements

Ship runs entirely on your machine and needs a few standard developer tools on your PATH:

Tool	Needed for	Notes
Git	evidence-bound gates, phase commits	any recent version
Python 3 + PyYAML	the executable state machine, gate checks, and context packs	pip install pyyaml. Run the scripts with whatever Python you have — python on python.org Windows, python3 on stock macOS/Linux.
A browser for UI QA (only for UI projects)	Layer-A.5 browser journeys (search → result → 200, Copy actually copies, mobile)	Provided by a browser-driving tool: the Claude in Chrome extension (CLI needs the extension + a compatible plan, enabled via --chrome / /chrome), Claude Desktop's in-app browser, Playwright, or an MCP equivalent. If no browser is available, the UI checks are reported UNREVIEWED/BLOCKED — never assumed passed.
Bash (optional)	running scripts/ship-doctor.sh, the plugin's own test suite	not needed to use Ship
pre-commit + gitleaks (optional)	the scaffolded git-native secret scan	Ship writes the config; you run pre-commit install

Cowork compatibility. Ship is designed to work in Cowork: it is a local workflow with no MCP server, no external network calls of its own, and no accounts, and its owner gates map to Cowork approvals. It only needs the session to run git and Python (same as any local use). Nothing in Ship phones home.

Examples

Three ways to start Ship in Claude Desktop or Cowork:

1. A new content site (full pipeline):

   /ship — "Build a searchable catalog of open-source CLI tools: ~20 real tools, browse by category, each page shows a working install command and a link to the real repo."

   Ship runs research → spec (with an owner-approved design direction) → build → expert QA → fix.

2. A quick experiment (Lite flow):

   /ship — "Quick experiment: a single-page cron-expression explainer. Keep it minimal."

   Ship uses the short Idea → Build → Deploy path and skips the heavy panel.

3. An adversarial QA pass on an existing repo:

   /ship — "Review this project before launch: code correctness, security on untrusted input, UI/UX on desktop + mobile, and SEO."

   Ship runs the risk-sized panel + an independent verifier and triages verified findings.

Ship selects and runs the relevant phases and reviewers underneath that one entry point.

Why not just ask Claude Code to build it?

Claude Code is already capable of writing the code. Ship adds the process around it that long, high-stakes sessions usually lose.

A single unstructured session	With Ship
Decisions live mainly in chat history	Decisions and constraints live in versioned project files
The same agent often reviews its own work	Independent reviewers inspect different risk areas
Findings may be accepted from plausibility	A verifier requires a concrete reproduction
Important release steps depend on memory	Executable gates check evidence before advancing
Deployment preparation is improvised	Staging, rollback, secret hygiene, and smoke checks are planned
Context keeps growing throughout the session	Linear phases run with compact, isolated context packs
It is hard to tell what remains	.ship/state.yml records the current phase and open gates

What Ship gives you

• Persistent project memory. Positioning, hard rules, acceptance criteria, progress, and release evidence survive chat compaction and future sessions.
• Independent QA. Risk-appropriate reviewers cover code, security, UI/UX, SEO, and operations; a separate verifier filters ungrounded findings.
• Real owner control. Ship pauses for decisions that belong to you, including scope, visual direction, infrastructure, and production release.
• Production guardrails. Secret scanning, build-once promotion, staging, rollback preparation, browser journeys, and deployment smoke checks are part of the workflow.
• Bounded context and spend. Phase-specific context packs and Lean/Standard/Deep modes reduce unnecessary fan-out without removing required quality checks.
• A recoverable process. If a session ends, the next one can resume from committed state, handoffs, and artifacts instead of reconstructing the project from memory.

Who it is for

Ship is designed for solo developers and small teams using Claude Code on work that is too important for a single improvised session:

• content and SEO products;
• SaaS applications;
• developer tools and headless services;
• existing projects that need a structured release or adversarial QA pass.

Ship is intentionally overkill for a two-line script or a tiny one-off edit. Use Lite mode for experiments, or use Claude Code directly when no pipeline is needed.

Safety and control

Ship is a guided workflow, not an unsupervised deployment service.

• Owner gates cannot be self-approved by an agent.
• External actions, account creation, purchases, provisioning, and production release remain subject to your approval and available credentials.
• Secrets stay out of committed files; Ship scaffolds git-native and CI secret scanning.
• Failed tests become explicit findings rather than disappearing inside a long transcript.
• The state machine and gate checks are executable, but Claude still performs the project work and you remain responsible for reviewing consequential changes.

Data access & privacy

Ship runs locally and collects nothing.

• No network calls of its own, no telemetry, no accounts, no MCP server. Web searches and page fetches during Research are performed by Claude Code's own tools (subject to your setup), not by any Ship service.
• What it touches: files inside the project you point it at, plus git. It creates the .ship/ state, handoffs, and context packs described in What Ship creates.
• Secret scanning is the scaffolded gitleaks pre-commit hook + CI job (templates/pre-commit-config.yaml, templates/ci-workflow.yml) — run locally at commit time and server-side in CI. The plugin bundles no Claude-side secret hook.
• Secrets live in .env (git-ignored) with a committed .env.example; Ship never prints live secrets.
• Full policy: PRIVACY.md.
• Report a security issue privately: see SECURITY.md.

The pipeline

Real projects use the full path:

flowchart LR
    A["💡 Idea"] --> B["🔎 Research"] --> C["📐 Spec"] --> D["🔨 Build"] --> E["🧪 QA"]
    E -->|findings| F["🔧 Fix"]
    F -->|re-check| E
    E -->|clean| G["📦 Prod-prep"]
    F -->|clean| G
    G --> H["🖥️ Provision"] --> I["🚀 Deploy"] --> J["📈 Monitor"]
    J -.->|next iteration| B

Loading

Experiments use the shorter path:

flowchart LR
    A["💡 Idea"] --> B["🔨 Build"] --> C["🚀 Deploy"]

Loading

Every phase follows the same shape:

flowchart LR
    IN[Input] --> WORK["Do the work"] --> ART["Write evidence"] --> GATE{"Gate"}
    GATE -->|"checks + owner approval"| NEXT["Next phase"]
    GATE -->|"not ready"| WORK

Loading

The important difference is that a phase does not advance merely because an agent says it is done. The gate checks project evidence, and owner decisions remain owner decisions.

Independent expert QA

For projects that need it, Ship runs a risk-sized review panel:

flowchart TB
    BUILD["Built project + real browser evidence"] --> PANEL{"Relevant reviewers"}
    PANEL --> CODE["Code"]
    PANEL --> SEC["Security"]
    PANEL --> UI["UI/UX"]
    PANEL --> SEO["SEO"]
    PANEL --> OPS["Operations"]
    CODE --> VERIFY["Independent verifier"]
    SEC --> VERIFY
    UI --> VERIFY
    SEO --> VERIFY
    OPS --> VERIFY
    VERIFY --> TRIAGE["Verified critical · major · minor"]
    TRIAGE -->|critical or major| FIX["Fix → re-QA"]
    TRIAGE -->|clean| RELEASE["Continue toward release"]

Loading

Ship does not run every reviewer by reflex. The selected panel depends on the project, its risk surface, and the configured spend mode. UI projects still require rendered desktop and mobile evidence; security review remains required when untrusted input or sensitive operations are present.

Token-aware by design

A real pre-optimization run processed roughly 65 million cache-read tokens because the growing project history was repeatedly replayed. Ship now limits that pattern by giving linear phase agents a compact context pack containing the current objective, protected rules, relevant files, a small repository map, and required checks.

The phase returns a short receipt and a structured handoff instead of its full transcript.

flowchart LR
    O["Thin orchestrator"] -->|"bounded phase pack"| A["Fresh phase agent"]
    A -->|"receipt + handoff"| O
    O -->|"next phase pack"| B["Next fresh agent"]

Loading

Important limitation: research and QA are fan-out phases and are still coordinated by the main session because their subagents cannot launch their own panels. The orchestrator's context therefore does not become magically free. Actual savings must be measured by a matched A/B run; a green self-test proves the machinery, not the token reduction.

Spend modes

Mode	Research	Web-search guidance	QA panel	Best for
lean	Up to 2 directions	About 12 searches	Risk-only, often 1–2	Small changes and experiments
standard	Up to 3 directions	About 20 searches	2–3 by real risk	Most projects
deep	Full investigation	Explicitly expanded	Full relevant panel	High-risk work or owner request

No mode removes the quality floor: deterministic checks, browser QA for user interfaces, security checks for untrusted input, and owner gates remain required.

What Ship creates

Ship stores its working memory alongside the project:

POSITIONING.md        Product, audience, and differentiation
CONSTITUTION.md       Non-negotiable project rules
PROJECT.md            Technical and product specification
DESIGN.md             Approved visual direction for UI projects
ACCEPTANCE.md         Machine-checkable success criteria
ROADMAP.md            Done, next, and deferred work
progress.md           Dated project history
research/             Evidence and synthesized decisions
production_runbook.md Release, rollback, and operations checklist

.ship/state.yml                    Current phase and gate evidence
.ship/handoffs/<n>-<name>.yml      Durable phase-to-phase records
.ship/context/<run>/<n>-<name>.yml Regenerable bounded context packs
.ship/context-policy.yml           Optional context budget and exclusions

It also scaffolds .env.example, .gitignore, pre-commit secret scanning, and a CI workflow.

Project types

Ship chooses a suitable type from your answer, or you can set it explicitly:

Type	Intended use	Flow emphasis
lite	Throwaway experiment	Idea → Build → Deploy
content	Content and SEO products	Research, search journeys, SEO, and rendered UI
saas	Full applications	Auth, billing, security, staging, and full release checks
engine	Headless services and tools	Correctness, security, evaluation, and operations

Everyday use

You only need one entry point:

Entry	Purpose
/ship	Start a project, resume its current phase, or request a focused review

The scaffolder, phase skills, gates, context packs, reviewers, and handoffs run underneath it. Their namespaced commands are an internal/advanced Claude Code surface and may not appear as user-entered commands in Claude Desktop or Cowork.

Real-world proof

Dogfooding run #2: Skillbinka

The starting brief was a free catalog of Claude Code skills, organized by profession, with a useful page for every skill. Ship took it through research, owner-approved positioning and design, a frozen specification, an Astro build, browser QA, independent expert review, verification, and a fix pass.

Responsive catalog	Install-ready skill page

The run produced 21 curated skill entries across four profession hubs, a distinctive owner-selected Index-Card Catalog interface, Pagefind search, an ingestion review queue, and SEO/build artifacts. The latest recorded gate was green: 9/9 ingestion tests, clean lint and typecheck, a successful build, and zero broken internal links.

The useful part was not that the first build looked finished. It was that QA demonstrated where it was not:

• the launch-minimum rule existed in the specification but was not enforced in navigation;
• 9 of the first 13 skill pages copied a literal <repo> placeholder instead of an installable command;
• the mobile skill layout pushed the core Copy control off-screen.

All three critical findings were fixed and re-verified. The first fix pass also closed 11 of 13 major findings; follow-up work added unit tests, ESLint, sitemap lastmod, CI checks, security headers, and accessibility fixes. The recorded QA judge score was 96/100, and the pipeline state marked the result quality_clean.

This is still a dogfooding result, not a customer success claim. The run stopped at phase 6 (production preparation): hosting, deployment, and monitoring were not completed. Its model, token, elapsed-time, and cost telemetry was not recorded in the project, so Ship does not claim measured token savings from this run. A matched A/B benchmark is still needed.

Quality and self-test

From the plugin repository:

bash scripts/ship-doctor.sh

The doctor validates manifests, frontmatter, YAML/JSON, cross-references, state transitions, strong gate behavior, context-pack and handoff invariants, the phase-0 CONSTITUTION guardrails, and the gitleaks/CI version pins (including that no Claude-side secret hook creeps back). CI runs the same suite on every push.

This verifies the plugin's internal contracts. It does not replace testing the product that Ship builds, and it does not prove token savings without a real A/B run.

Status and honest limits

Ship is beta software under active dogfooding.

• It provides structure and executable checks, not perfect autonomy.
• Claude can still make incorrect implementation or design decisions.
• Prompt-level observation limits are not the same as a hard runtime sandbox.
• External services, credentials, infrastructure, and production environments vary by project.
• Full workflows use multiple model calls and may cost more than an ordinary short coding session; use Lite or Lean mode when the full process is unnecessary.

If you want a magic one-shot app generator, Ship is probably not the right tool. If you want Claude Code to work through a visible, resumable, reviewable release process, that is exactly what Ship is for.

Troubleshooting

Symptom	Cause / fix
A gate or context command errors with pyyaml missing	pip install pyyaml — Ship's scripts need Python 3 + PyYAML.
python3: command not found (often python.org Windows)	This is about the manual scripts (gate/context/migrate) — run them with python instead.
Ship reports Phase-Isolated pipeline: OFF	A phase ran without a context pack. Ask Ship to rebuild and validate the current phase pack. This means the token economy isn't engaged — worth fixing before trusting a run's token numbers.
A Ship gate reports BLOCKED	It's doing its job — missing checks, an unverified QA, a leftover {{placeholder}}, or a null commit SHA. Fix what it lists; don't hand-set gate_passed.
A gate blocks on a missing prior handoff (project upgraded from older Ship)	Run python <plugin>/scripts/context_builder.py migrate . (use python3 if that's your Python) to write a synthetic predecessor handoff (review it), or set last_completed_phase in .ship/state.yml.
Installed version looks stale after an update	Refresh the marketplace clone, not just the plugin: /plugin marketplace update ship-marketplace → /plugin install ship@ship-marketplace → restart.
pre-commit not found	Optional. Install pre-commit and run pre-commit install, or rely on the CI gitleaks job.

Report bugs in the issue tracker; security issues privately via SECURITY.md.

Installation details

• Marketplace: use the two install commands in Quick start, then enter /ship in Claude Desktop or Cowork.
• Local development: claude --plugin-dir /path/to/ship-plugin.
• Loose installation: copy skills/, agents/, and commands/ into ~/.claude/ and keep the plugin directory available so they can resolve templates and scripts.
• Secret scanning: the scaffolded gitleaks pre-commit hook + CI job — commit-time locally and server-side in CI (make it required via branch protection).

Feedback and license

Ship is released under the MIT License. Issues, dogfooding reports, and reproducible bug reports are welcome in the GitHub issue tracker.