Shipfast

ShipFast

Autonomous context-engineered development system with SQLite brain.

5 agents. 20 commands. Per-task fresh context. 70-90% fewer tokens as the brain learns your codebase.

[](https://www.npmjs.com/package/@shipfast-ai/shipfast) [](https://www.npmjs.com/package/@shipfast-ai/shipfast) [](LICENSE) [](https://github.com/shipfast-ai/shipfast/actions/workflows/test.yml)

Claude Code, OpenCode, Gemini CLI, Kilo, Codex, Copilot, Cursor, Windsurf, Antigravity, Augment, Trae, Qwen Code, CodeBuddy, Cline

npm i -g @shipfast-ai/shipfast

Works on Mac, Windows, and Linux.

---

Why ShipFast?

Context rot kills AI coding quality. As the context window fills up, output degrades — Task 5 is worse than Task 1.

ShipFast fixes this with a SQLite knowledge graph that gives each agent fresh context and gets smarter every session.

• SQLite brain — queryable knowledge graph replaces markdown state files
• Fresh context per task — each Builder agent starts clean, quality stays consistent
• 3K-40K tokens per feature — 70% fewer on first use, 90% on repeat tasks as learnings accumulate
• Self-improving — records patterns and decisions, gets cheaper over time
• Smart model selection — dynamically picks haiku/sonnet/opus based on task + feedback loop
• Domain-aware questioning — 6 domains, 20+ question templates, zero LLM cost
• Wave-based execution — independent tasks run in parallel, dependent tasks run sequentially
• Cross-repo support — link repos, search across brains, cross-repo blast radius
• 22 languages indexed in # Link another repo for cross-repo search

shipfast unlink [path] # Unlink a repo (or all) shipfast doctor # Check brain.db health + diagnose issues shipfast permissions # Show configured permission allowlist shipfast status # Show installed runtimes + brain + links shipfast update # Update + re-detect runtimes shipfast uninstall # Remove from all AI tools

### Permissions (Zero Prompts)

`shipfast init` auto-configures safe permission rules in `.claude/settings.json`. ShipFast operations (Read, Edit, Write, git, build, test, grep) run without permission prompts. Destructive commands (rm, curl, ssh, sudo) still require approval.

No `--dangerously-skip-permissions` needed. Run `shipfast permissions` to view the allowlist.

If auto-configured permissions don't work for your setup, you can fall back to:
```bash
claude --dangerously-skip-permissions

This skips ALL permission checks — use only in trusted environments.

---

How It Works

0. Discover (for new projects)

/sf-project Build a SaaS billing system

Before any planning, the LLM acts as a senior technical discovery lead — asking project-specific questions until it understands the full picture.

10-category coverage framework (the LLM must understand all before proceeding):

| Category | What it captures | |----------|-----------------| | Problem | What pain point does this solve? For whom? | | Users | Who uses it? Distinct roles/needs? | | Core Flow | Primary user journey, step by step | | Data | What's created, stored, queried? Relationships? | | Boundaries | What's v1? What's explicitly NOT v1? | | Tech | Stack decisions (or detected from existing code) | | Auth | Who can do what? Access control model? | | Integrations | External services, APIs, third-party deps? | | Constraints | Timeline, team, budget, compliance? | | Risks | What could go wrong? Hardest part? |

Questions are generated dynamically by the LLM — not static templates. A SaaS project gets billing/multi-tenant questions. A CLI tool gets input/output questions. An API gets protocol/auth questions.

Anti-loop: max 4 rounds (16 questions). 8/10 categories clear = stop. User can say "enough" anytime. Safe tech defaults assumed without asking (PostgreSQL, REST, JWT). All answers stored as locked decisions in brain.db.

1. Discuss (when needed)

/sf-discuss Add authentication

Domain-aware ambiguity detection — zero LLM tokens:

| Domain | Example Questions | |--------|-------------------| | UI | Layout density? Interaction pattern? Empty state? Responsive approach? | | API | Response format? Error handling? Auth mechanism? Versioning? | | Database | ORM? Migration strategy? Data access pattern? | | Auth | JWT/session/OAuth? Token storage? Role model? | | Content | Markdown/rich text? Tone? i18n? | | Infra | Deploy target? CI/CD pipeline? |

Auto-detects domain from task keywords. Answers stored as locked decisions — never asked again, even across sessions.

Flags: --batch (group questions), --chain (auto-run discuss → plan → check → execute), --assume (auto-resolve from brain.db patterns)

2. Plan

/sf-plan Add Stripe billing with webhooks

Spawns two agents in fresh contexts:

Scout — Researches the codebase. Finds relevant files, functions, consumers. Tags findings: [VERIFIED], [CITED], [ASSUMED].

Architect — Creates tasks using goal-backward methodology. Each task has exact file paths, consumer lists, verify commands, and done criteria. Sets dependency graph for wave grouping.

Tasks stored in brain.db.

3. Execute

/sf-do

Complexity auto-detection routes to the right workflow:

Trivial (fix a typo) — executes inline, no agents. ~3K tokens.

Medium (add a component) — one Builder agent with all tasks batched. ~15K tokens.

Complex (new feature across files) — per-task Builder agents with fresh context each:

[1/6] Building: Split LocationList into layouts...
[1/6] ✓ Split LocationList (commit: a1b2c3d)

[2/6] Building: Extract RectangleTile sub-components...
[2/6] ✓ Extract RectangleTile (commit: e4f5g6h)

...

[6/6] ✓ Extract Featured hooks (commit: m7n8o9p)

Each Builder gets fresh context — no accumulated garbage from previous tasks. Quality stays consistent from Task 1 to Task 6.

Wave-based parallel execution:

Independent tasks (no shared files) → same wave → run in parallel
Dependent tasks (shared files/imports) → separate waves → run sequentially

The Architect sets the dependency graph. groupIntoWaves() computes waves. Independent tasks in the same wave launch simultaneously — multiple Builder agents at once.

After all tasks complete:

• Critic agent (fresh context) reviews the entire git diff — checks consumer integrity, import consistency, security
• Scribe agent (fresh context) records decisions + learnings to brain.db
• Branch audit (automatic on non-default branches) — reports MIGRATED / MISSING / SAFELY REMOVED vs default branch

Dynamic model selection per agent:

| Condition | Model | |-----------|-------| | Well-known domain (2+ high-confidence learnings) | Haiku (cheapest) | | Standard task | Sonnet (default) | | Complex multi-area, no prior patterns | Opus (best reasoning) | | Budget low ( and rewrites it against a project-wide symbol index. This closes the cross-file call-graph gap for languages without named imports (Swift, Ruby, Lua, C, C++) and fills in missed cross-file edges for every other language. Ambiguous matches (2-5 candidates) emit weighted edges — filter by weight >= 0.9` for high-confidence-only traversal.

MCP Server: 30+ structured tools for IDE integration. Commands and agents use MCP tools — no raw SQL. New in v2.0:

• brain_impact(node, direction, depth) — walk edges upstream/downstream with kind filters
• brain_trace(from, to) — BFS pathfinding between two nodes
• brain_findings(branch) — per-branch cited Scout output with citation verification
• brain_sessions — every /sf:* invocation's start/finish record, including redirects and bail-outs

MCP auto-registration (v1.8.0): shipfast writes the MCP server into each AI tool's native config file — Claude Code (settings.json), OpenCode (settings.json), Kilo (kilo.jsonc), Cursor (mcp.json), Codex (config.toml), Copilot (mcp-config.json), Windsurf (mcp_config.json), Gemini CLI (settings.json), Qwen Code (settings.json), Cline (data/settings/cline_mcp_settings.json) — so brain_* tools are immediately available on every supported platform.

Claude Code hooks (v1.8.0): FileChanged auto-triggers shipfast refresh when you edit package.json / Cargo.toml / go.mod / pyproject.toml / .nvmrc / tsconfig.json etc. PreCompact auto-saves a brain checkpoint before Claude Code compacts the session. Both leverage Claude Code 2.1.83+ / 2.1.105+ hook types.

Project Signals (v1.7.0): manifest files (package.json, Cargo.toml, go.mod, pyproject.toml, requirements.txt, Gemfile, composer.json, pubspec.yaml, *.csproj, mix.exs) + config files (tsconfig.json, .nvmrc, .env.example, pnpm-workspace.yaml, etc.) are scanned on shipfast init and refreshed with shipfast refresh. Framework, runtime, package manager, test framework, ORM are auto-detected and injected into every agent's context as `` — so agents know your real stack without re-reading files each task.

---

Agents

| Agent | Role | Default Model | Key Behaviors | |---|---|---|---| | Scout | Research | Haiku | 6-direction flow tracing, confidence tagging, consumer discovery | | Architect | Planning | Sonnet (Opus for complex) | Goal-backward, dependency graph, STRIDE threats, scope guard | | Builder | Execution | Sonnet (Haiku if learned) | Impact analysis before every change, per-task build verify, 3-attempt limit | | Critic | Review | Haiku (Sonnet for security) | Auto-depth (quick/standard/deep), import graph tracing, consumer integrity | | Scribe | Documentation | Haiku | Records decisions + learnings to brain.db, generates PR descriptions |

Models are dynamically selected — not fixed. The feedback loop tracks which model succeeds for which domain and auto-adjusts.

---

Commands

Core

| Command | What it does | |---|---| | /sf-do | The one command. Auto-detects complexity, runs the right workflow. | | /sf-plan | Research (Scout) + Plan (Architect). Stores tasks in brain.db. | | /sf-discuss | Domain-aware questioning. 6 domains, 20+ templates, zero LLM cost. | | /sf-check-plan | Validate plan: scope, consumers, dependencies, STRIDE threats. | | /sf-verify | Verify: artifacts, data flow, stubs, schema drift, build, consumers. |

Projects & Worktrees

| Command | What it does | |---|---| | /sf-project | Decompose large project into phases with REQ-ID tracing. | | /sf-milestone | Complete current milestone or start next version. | | /sf-worktree create | Create isolated worktree with smart branch naming + multi-repo support. | | /sf-worktree check | Migration audit: MIGRATED / MISSING / SAFELY REMOVED / MODIFIED / ADDED. | | /sf-worktree list\|switch\|status\|complete | Manage parallel worktrees. |

Shipping & Session

| Command | What it does | |---|---| | /sf-ship | Create branch, push, PR link + post-ship hook. | | /sf-status | Brain stats, tasks, checkpoints, version. | | /sf-resume | Resume from previous session. | | /sf-undo [task-id] | Rollback a specific task. | | /sf-rollback [last\|all\|N] | Rollback last task, last N, or entire session. |

Knowledge & Analysis

| Command | What it does | |---|---| | /sf-brain | Query knowledge graph: files, decisions, learnings, seeds, hot files. | | /sf-learn | Teach a reusable pattern (persists across sessions). | | /sf-map | Codebase report: architecture layers, hot files, co-change clusters. | | /sf-cost | Token usage breakdown by agent, domain, model + success rates. | | /sf-diff | Smart diff — changes grouped by task with file stats. |

Config

| Command | What it does | |---|---| | /sf-config | View or set model tiers, token budget, post-ship hooks. | | /sf-help | Show all commands. |

---

Auto-routing + brain snapshot on every prompt

Tired of typing /sf:do every turn? Toggle auto-routing from inside Claude Code:

/sf:enable     # every plain prompt → /sf:do
/sf:disable    # plain prompts go to Claude untouched

When enabled, the persistent statusline above your prompt shows a ⚡ badge:

SF⚡ · Opus · $0.12

/sf:status also prints Auto-route: ON/OFF.

How it works: ShipFast installs a UserPromptSubmit hook that fires on every user message. /sf:enable creates a flag file at ~/.shipfast/auto-route.enabled; while the file exists, the hook injects a directive telling the model to invoke /sf:do instead of editing directly. /sf:disable removes the file. Off by default — existing workflows are untouched.

Bypass rules (hook stays silent, no routing) even when enabled:

• message starts with / → slash command
• starts with ! → explicit raw escape
• starts with or ends with ? → question
• fewer than 4 chars → short ack like "yes" / "ok"

Brain snapshot on every prompt (v2.0)

Independent of the auto-route flag, the hook also injects a compact snapshot of your brain.db into every prompt: node/edge counts, top hot files, recent decisions/learnings/findings/sessions, and the full list of brain_* MCP tools + edge kinds. The model gets situational awareness of your codebase every turn without asking. Snapshot is cached for 30 s keyed on brain.db mtime — negligible overhead after the first turn in a stable window.

No config. Works as long as brain.db exists in or above the current working directory.

---

Self-Improving Memory

ShipFast gets cheaper every session:

1. First time doing X → full pipeline (scout + architect + builder + critic). ~30K tokens.
2. Second time → skip scout + architect (brain has the patterns). ~15K tokens.
3. Third time → skip critic too (high confidence). ~8K tokens.

Learnings are confidence-weighted (0.0-1.0). Boosted on successful reuse. Auto-pruned after 30 days of non-use.

Seeds: Ideas surfaced during work are captured for future milestones — not lost, not distracting.

---

Supported Languages

22 languages indexed overall. v2.0 ships AST-based extractors for the top 6; the rest use regex with the project-wide resolver filling cross-file gaps.

| Mode | Languages | |---|---| | AST (tree-sitter) — strict parsing, method dispatch, mutates edges | JavaScript, TypeScript, JSX/TSX, PHP, Python, Java, Go | | Regex + resolver — same-file via extractor, cross-file via project-wide resolver | Rust, Kotlin, Swift, C, C++, Ruby, Dart, Elixir, Scala, Zig, Lua, R, Julia, C#, F#, Vue/Svelte/Astro | | Also indexed — not executable code but reachable via brain_search | Markdown (skills, docs, READMEs) |

50+ directories skipped. 25+ lock files skipped. resources/views/vendor/ (Laravel view overrides) is an explicit exception to the vendor/ skip rule.

Install size (v2.0)

Vendored tree-sitter grammars (~4.3 MB total: js + ts + tsx + php + python + java + go WASM) plus the web-tree-sitter runtime (~200 KB) ship in the tarball. Total install ~5 MB, up from ~153 KB in v1.9.x. Everything is loaded lazily — if you run shipfast init --regex, the WASMs are never touched at runtime.

Later releases may split grammars into a peer package to keep the base install small; see docs track in the project plan.

---

Uninstalling

shipfast uninstall
npm uninstall -g @shipfast-ai/shipfast

---

Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for architecture overview, code style, and how to help.

---

License

MIT

Inspired by Get Shit Done. Built from scratch.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: shipfast-ai
• Source: shipfast-ai/shipfast
• License: MIT
• Homepage: https://www.npmjs.com/package/@shipfast-ai/shipfast

Install and usage instructions live in the source repository linked above.