@shipfast-ai/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.

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 <1 second — architecture layers auto-derived from import graph
• Works with 14 AI coding tools — auto-detects and installs for all

Getting Started

npm i -g @shipfast-ai/shipfast
cd your-project
shipfast init

Auto-detects your AI tools and installs for all of them. Verify: run /sf-help in your AI tool.

Terminal Commands

shipfast init           # Index repo + auto-configure permissions (no --dangerously-skip-permissions needed)
shipfast init --fresh   # Full reindex (clears existing brain)
shipfast refresh        # Re-scan project signals (deps, framework, scripts) — fast
shipfast link <path>    # 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:

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 (<40%)	All Haiku (degradation)
--cheap flag	All Haiku
--quality flag	Sonnet/Opus

Models auto-adjust via feedback loop — tracks success/failure rates per model+domain, upgrades haiku→sonnet when failing, downgrades when consistently succeeding.

All execution flags: --tdd (test-first), --research (force Scout), --verify (force verification), --no-plan (skip planning), --discuss (force discussion), --cheap (all haiku), --quality (sonnet/opus)

4. Verify

/sf-verify

Fresh context verification:

• 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
• Schema drift detection: warns when ORM models change without migrations (Prisma, Drizzle, TypeORM, Django, Rails, Knex)
• TDD sequence check: verifies test(...) commits before feat(...) commits
• Build verification: runs build command, reports pass/fail
• Branch audit: compares changes vs default branch, flags missing migrations

Scores: PASS / PASS_WITH_WARNINGS / FAIL with specific details.

5. Ship

/sf-ship

Creates branch, generates PR description from brain.db (decisions, tasks, changes), pushes, outputs PR link. Runs configurable post-ship hook if set.

6. 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-do → /sf-verify → /sf-ship

Brain (SQLite Knowledge Graph)

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

Table	What it stores
nodes	Functions, types, classes (pluggable language extractors, 22 languages)
edges	Import/call/dependency relationships + git co-change patterns
decisions	Locked Q&A pairs with domain tags (~40 tokens each)
learnings	Error→fix patterns with confidence scoring (0.0-1.0)
tasks	Execution history with commit SHAs, tokens used, duration
seeds	Forward ideas captured during work for future milestones
model_performance	Success/failure tracking per model+domain (feedback loop)
checkpoints	Git stash refs for rollback
requirements	REQ-IDs mapped to phases for tracing
architecture	Auto-computed layers from import graph (zero hardcoding)
folders	Directory roles: entry, shared, consumer, leaf, foundation
hot_files	Most frequently changed files from git history
config	Token budget, model tiers, post-ship hooks, default branch

Incremental indexing: ~300ms for changed files. Deleted files auto-cleaned. Stale learnings auto-pruned.

MCP Server: 26 structured tools for IDE integration. Commands and agents use MCP tools — no raw SQL.

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 <project_stack> — 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 <task>	The one command. Auto-detects complexity, runs the right workflow.
/sf-plan <task>	Research (Scout) + Plan (Architect). Stores tasks in brain.db.
/sf-discuss <task>	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 <desc>	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>	Query knowledge graph: files, decisions, learnings, seeds, hot files.
/sf-learn <pattern>	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 (opt-in)

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 statusline shows a ⚡ badge: SF⚡ [==== ] 40%. /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 <your text> 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"

Self-Improving Memory

ShipFast gets cheaper every session:

• First time doing X → full pipeline (scout + architect + builder + critic). ~30K tokens.
• Second time → skip scout + architect (brain has the patterns). ~15K tokens.
• 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: 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. 25+ lock files skipped.

Uninstalling

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

Contributing

See CONTRIBUTING.md for architecture overview, code style, and how to help.

License

MIT

Inspired by Get Shit Done. Built from scratch.