Ship – Orquestrador de Workflows para Agentes
itsHabib/ship
Orquestração de workflows com persistência e controle para agentes Cursor
Ver no GitHubMCP server que gerencia execução de tarefas em workflows de agentes Cursor, persistindo estado em SQLite e fornecendo operações de inspeção e cancelamento. Integra execução local e em nuvem, permitindo que agentes retomem runs interrompidas e mantenham histórico estruturado de execuções.
Instalação
npx convez-ai itsHabib/ship1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Gerenciar tarefas de desenvolvimento delegadas a agentes IA
- Persistir e recuperar estado de execuções de workflow interrompidas
- Inspecionar progresso e cancelar runs em execução via MCP
Veredito

Ship é uma solução madura (V1 feature-complete) para equipes que rodam agentes Cursor em workflows complexos e precisam de persistência, rastreabilidade e controle granular. Exige conforto com TypeScript, MCP e arquitetura de microserviços; não é para usuários casuais.
README
A tradução para o português deste README ainda está na fila.
Ship
Repo-native dev-workflow MCP toolkit. Ship hands a task doc to a Cursor agent (local worktree or cloud), persists workflow state in SQLite, and exposes inspect/cancel verbs over MCP. Cloud-run resume happens at process startup inside @ship/core, not as an MCP tool. The repo dogfoods itself — feature work lands via mcp__ship__ship against task docs in worktrees.
Status
V1 feature-complete on main (Phases 0–9). V2 phases shipped: 01 (async ship kickoff), 03 (subagent passthrough), 04 (Cursor cloud runner), 08 (Agent.resume for orphaned cloud runs). The PR-opening MCP verb was removed in PR #81; PR creation is operator-side (gh pr create). Cause-chain failure diagnostics and boolean-coerce fixes landed in PR #82.
See docs/features/ship-v1/plan.md for V1 history and docs/features/ship-v2/spec.md for V2 design and phase docs under docs/features/ship-v2/phases/.
Quick start
pnpm install
make check # typecheck + lint + format-check + test (604+ L1/L2 tests, no API keys)
Dogfood pattern (how this repo ships itself):
- Write a task doc under
docs/features/<feature>/phases/<NN>-<slug>.md. - Spin up a worktree (
/worktree-add <branch>) or use Cursor cloud runtime. - Kick off:
mcp__ship__ship { workdir, docPath, repo, branch }— returns{ workflowRunId, status: "running" }immediately (V2 async). - Poll terminal:
mcp__ship__get_workflow_run { workflowRunId }or readship://runs/{id}. - Commit, push, open PR with
gh pr create.
CLI equivalent (blocking): cd packages/cli && npx tsx src/bin.ts ship <docPath> --repo <name> (--repo is required; --workdir / --branch are optional).
Architecture
Eight pnpm workspace packages, dependency direction inward toward @ship/core:
| Package | Role |
|---|---|
cli | Terminal verbs over ShipService |
core | Orchestration — ShipService, artifacts, default wiring |
cursor-runner | Sole @cursor/sdk boundary — local + cloud runners |
mcp | Zod wire schemas for MCP tool I/O |
mcp-server | MCP stdio server — tool registration + ship://runs resource |
store | SQLite persistence behind the Store interface |
test-harness | In-memory fixtures + scenario helpers for tests |
workflow | Domain schemas, transitions, ID factories |
Ship owns workflow state and the MCP surface. @cursor/sdk owns agent execution. Tower (external) owns repo/worktree/PR snapshots when integrated — Ship calls it, doesn't reimplement it.
Develop
pnpm install
make check # CI-equivalent full gate
pnpm run test:watch # Vitest watch mode
make lint-fix && make format # auto-fix lint + format
Per-package tests: pnpm --filter @ship/<package> test.
On-demand mutation testing across shipping packages:
gh workflow run mutation.yml # requires GitHub CLI auth
MCP server (fake runner, no API key):
cd packages/mcp-server && SHIP_TEST_FAKE_CURSOR=1 npx tsx src/bin.ts
Integration (L3) and live e2e (L4, opt-in keys): make integration, make e2e. See AGENTS.md for the command matrix.
Docs map
Feature work lives under docs/features/<feature>/:
spec.md— design spec (what and why)plan.md— execution plan with phase checkboxesphases/<NN>-<slug>.md— per-phase task docs (input toship.ship)
Cached external references sit at docs/<topic>.md. Test-layer taxonomy (L1–L4): docs/features/qe-sdet/spec.md.
Workbench
Ship sits in a portfolio dev-workbench alongside dossier (project memory), huddle (multi-seat coordination), and /worktree-* skills. The Dev workbench section in CLAUDE.md documents when to call each verb — use it as the operator reference for MCP tools and skills beyond Ship itself.
License
Licensed under MIT.