npm i -g @shipfast-ai/shipfast

Why ShipFast?

Context rot kills AI coding quality. As the context window fills up, output degrades.

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

• 17 commands, 5 composable agents — simple to learn, covers the full workflow
• SQLite brain — queryable knowledge graph, no per-task state files
• 3K-40K tokens per feature — 70-90% less than typical AI dev workflows
• Fresh context per task — no accumulated garbage between tasks
• Cross-session learning — records decisions and patterns, gets cheaper over time
• Codebase indexing in <1 second — 973 files indexed in 636ms
• Graph-derived architecture — auto-detects layers from import graph
• Cross-repo linking — search across multiple repos with shipfast link
• 17 MCP tools — structured brain access, no SQL improvisation
• Works with 14 AI coding tools — auto-detects and installs for all

Getting Started

npm i -g @shipfast-ai/shipfast

Auto-detects your AI tools and installs for all of them. Then index your repo:

cd your-project
shipfast init

Verify: run /sf-help in your AI tool.

Staying Updated

shipfast update

Updates the package and re-detects runtimes (catches newly installed AI tools).

Terminal Commands

shipfast init           # Index current repo into .shipfast/brain.db
shipfast init --fresh   # Full reindex (clears existing brain)
shipfast link <path>    # Link another repo for cross-repo search
shipfast unlink [path]  # Unlink a repo (or all)
shipfast status         # Show installed runtimes + brain + links
shipfast update         # Update + re-detect runtimes
shipfast uninstall      # Remove from all AI tools
shipfast help           # Show all commands

How It Works

Already have code? shipfast init indexes your codebase in under 1 second — functions, types, imports, git history. All stored in a SQLite database.

1. Plan Phase

/sf-plan Add Stripe billing with webhooks

Spawns two agents in fresh contexts:

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

Architect — Creates a precise task list using goal-backward methodology. Starts from "what does done look like" and works backward to tasks. Each task has exact file paths, consumer lists, verify commands, and measurable done criteria.

Tasks are stored in brain.db. No PLAN.md files.

2. Execute

/sf-do

Reads tasks from brain.db and executes them.

Trivial tasks (fix a typo, add an import) — executes inline. No agents, no planning. ~3K tokens.

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

Complex tasks (new feature across multiple files) — per-task Builder agents with fresh context each. No accumulated garbage between tasks. Each Builder:

1. Reads files + greps for consumers of anything it'll change
2. Implements following existing patterns
3. Runs build/typecheck — fixes errors before committing
4. Commits with conventional format
5. Updates task status in brain.db

After all tasks: Critic reviews the diff. Scribe records decisions and learnings to brain.db.

3. Verify

/sf-verify

Separate verification in fresh context:

• 3-level artifact validation: exists → substantive (not stubs) → wired (imported and used)
• Data flow tracing: components receive real data, not hardcoded empty arrays
• Consumer integrity: removed exports have zero remaining consumers
• Stub detection: TODO, FIXME, placeholder, empty handlers, console.log, debugger
• Build verification: runs build command, reports pass/fail

Scores: PASS / PASS_WITH_WARNINGS / FAIL with specific failure details.

4. Discuss (when needed)

/sf-discuss Add authentication

Detects ambiguity before planning (zero LLM tokens — rule-based):

• WHERE: No file paths mentioned
• WHAT: No behavior described
• HOW: Multiple approaches possible
• RISK: Touches auth/payment/data
• SCOPE: Broad request with conjunctions

Asks 2-5 targeted questions. Stores answers as locked decisions in brain.db. Never asks the same question twice (even across sessions).

5. Ship

/sf-ship

Creates branch, generates PR description from brain.db (decisions, tasks, changes), pushes, outputs PR link.

6. Repeat → Complete → Next Milestone

/sf-discuss Phase 2
/sf-plan Phase 2: Payment webhooks
/sf-do
/sf-verify
/sf-ship
...
/sf-milestone complete
/sf-milestone new v2.0

Or for simple tasks, just run directly:

/sf-do fix the login bug

ShipFast auto-detects complexity and runs the right workflow.

Why Fresh Context Matters

Context rot is the #1 quality killer. As the context window fills with file reads, error messages, and previous task artifacts, Claude's output quality degrades.

ShipFast solves this:

Each agent starts clean. No accumulated garbage. Quality stays consistent from first task to last.

Brain (SQLite Knowledge Graph)

All state lives in .shipfast/brain.db. Zero markdown files.

Incremental indexing: only re-indexes changed files (~300ms). Deleted files auto-cleaned.

MCP Server: brain.db is exposed as 17 structured MCP tools. LLMs call these instead of improvising SQL.

Architecture Intelligence

ShipFast auto-derives architecture layers from the import graph — zero hardcoded folder patterns. Works with any project structure, any language.

How it works:

1. BFS from entry points (files nothing imports) assigns layer depth
2. Fuzzy import resolution handles @/, ~/, and alias paths
3. Folder roles detected from aggregate import/export ratios
4. Recomputed on every shipfast init (instant)

What it produces:

• Layer 0 (entry): files nothing imports — pages, routes, App.tsx
• Layer 1-N (deeper): each layer imported by the layer above
• Leaf layer: files that import nothing — types, constants
• Folder roles: entry (imports many), shared (imported by many), consumer, leaf, foundation

Why it matters: Scout knows which layer a file lives in. Builder knows to check upstream consumers before modifying a shared layer. Critic can detect skip-layer violations. Verifier traces data flow from entry to data source.

All exposed as MCP tools: brain_arch_layers, brain_arch_folders, brain_arch_file, brain_arch_data_flow, brain_arch_most_connected.

Agents

5 composable agents with compressed behavioral rules.

Builder's Rule Zero

Before deleting, removing, or modifying ANY function, type, or export:

grep -r "functionName" --include="*.ts" --include="*.tsx" .

If other files use it → update them or keep it. NEVER remove without checking consumers. This single rule prevents 80% of refactoring bugs.

Commands

Core Workflow

Projects

Shipping

Session

Knowledge

Config

Workflows

Simple:     /sf-do fix the typo in header
Standard:   /sf-plan add dark mode → /sf-check-plan → /sf-do → /sf-verify
Complex:    /sf-project Build billing → /sf-discuss → /sf-plan → /sf-check-plan → /sf-do → /sf-verify → /sf-ship

Self-Improving Memory

ShipFast gets cheaper and smarter every session:

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

Learnings are confidence-weighted (0.0-1.0). Boost on successful reuse. Auto-prune after 30 days of non-use. Users teach directly with /sf-learn.

Configuration

Model tiers per agent (configurable with /sf-config):

Scout:     haiku    (reading is cheap)
Architect: sonnet   (planning needs reasoning)
Builder:   sonnet   (coding needs quality)
Critic:    haiku    (diff review is pattern matching)
Scribe:    haiku    (writing commit msgs is simple)

Supported Languages

22 languages indexed: JavaScript, TypeScript, Rust, Python, Go, Java, Kotlin, Swift, C, C++, Ruby, PHP, Dart, Elixir, Scala, Zig, Lua, R, Julia, C#, F#, Vue/Svelte/Astro.

50+ directories skipped (node_modules, dist, target, pycache, .venv, Pods, etc.) sourced from GitHub's official gitignore templates.

25+ lock files skipped (package-lock.json, Cargo.lock, poetry.lock, go.sum, etc.).

Uninstalling

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

Auto-detects and removes from all runtimes. Cleans settings.json hooks.

License

MIT

Inspired by Get Shit Done. Built from scratch.