build-with-ai

A zero-API, local-first CLI that guides developers step-by-step through building complete software projects with any AI by generating deterministic, context-aware prompts at every engineering phase.

Overview

When building non-trivial applications with AI assistants (Claude, ChatGPT, Cursor, DeepSeek, local Ollama models), developers often encounter three problems:

1. The Blank Canvas Problem: Asking an AI to "build a whole app" produces monolithic, fragmented code.
2. Context Drift: As the chat progresses, the AI forgets foundational schema and architectural decisions made earlier.
3. Skipped Phases: Jumping directly to UI before establishing data contracts, authentication, or error handling.

build-with-ai solves this by breaking projects into disciplined, sequential phases (Discovery, Schema, Auth, Core CRUD, Testing, Deployment). It maintains a local context store (context.json) and automatically interpolates prior architectural decisions into downstream prompts ({{decisions.key}}).

Core Guarantees

• Zero API Keys & Zero Cost: Runs 100% locally in your terminal. No third-party API accounts or rate limits required.
• Universal Model Compatibility: Use with any web interface, IDE plugin, or local model.
• Non-Destructive: Operates entirely within .buildwithai/ and never touches or overwrites your application source files.

How It Works

graph LR
    subgraph Local Machine
        CLI[build-with-ai CLI]
        Store[(.buildwithai/ Memory)]
        Code[Application Code]
    end

    subgraph AI Assistant
        AI[Claude / ChatGPT / Cursor / Local LLM]
    end

    CLI -->|1. Generate Prompt & Copy| Clipboard[System Clipboard]
    Clipboard -->|2. Paste Prompt| AI
    AI -->|3. Produce Code & Design| Developer[Developer]
    Developer -->|4. Implement| Code
    Developer -->|5. Record Decisions| CLI
    CLI -->|6. Save Context| Store
    Store -->|7. Interpolate Context| CLI

Quickstart

Run directly without installation via npx:

npx build-with-ai

Or install globally:

npm install -g build-with-ai

Initialize a new project:

npx build-with-ai init

Available Templates

build-with-ai includes 11 production-ready workflow templates:

Custom & Remote Templates

Load team-specific or custom templates directly from a local path or remote URL:

# Local template
npx build-with-ai init --template ./custom-template.json

# Remote template (HTTPS raw JSON)
npx build-with-ai init --template https://raw.githubusercontent.com/org/repo/main/template.json

Custom templates are validated against the schema and automatically saved to .buildwithai/template.json, ensuring all subsequent commands (next, done, status, export) resolve the template offline without needing the original file or URL.

Or discover and initialize with community templates using the remote template registry:

# Search all templates in the community registry
npx build-with-ai search

# Search by keyword
npx build-with-ai search saas

See CONTRIBUTING.md for the template authoring specification and schema contracts.

Walkthrough

1. Initialize

npx build-with-ai init

Select a template, experience level, and project overview. The .buildwithai/ workspace is created.

2. Generate Prompt (next)

npx build-with-ai next

The CLI formats the active step, identifies recommended models and target files, and copies the prompt to your clipboard.

STEP 1/15: Problem Discovery & SaaS Value Proposition
Phase: Discovery
Recommended AI: Claude 3.5 Sonnet / GPT-4o
Target Files: [None]

PROMPT FOR YOUR AI:
------------------------------------------------------------
I am building a SaaS product called "Invoice Tracker".
The concept is: A subscription SaaS for freelancers to automate invoicing.
My experience level is Intermediate.

Act as a SaaS product strategist:
1. Define the primary customer persona.
2. Formulate a 2-sentence value proposition.
------------------------------------------------------------
Prompt copied to clipboard.

3. Record Decisions (done)

Paste the prompt into your AI assistant, review the architectural output, and record the choices:

npx build-with-ai done

Enter decisions for required keys (e.g., decisions.targetCustomer, decisions.coreValueProp). Decisions are saved to context.json, and the project advances to the next step.

4. Automatic Context Injection

On subsequent steps, previous decisions are automatically injected into the generated prompt:

STEP 3/15: Technology Stack Selection
Phase: Tech Stack

PROMPT FOR YOUR AI:
------------------------------------------------------------
My experience level is Intermediate and "Invoice Tracker" targets:
[Injected from Step 1: Freelance designers and agencies]

Recommend the optimal production tech stack...
------------------------------------------------------------

5. Inspect and Modify Decisions (context, set & config)

View stored decisions or update any value directly using dot-notation:

npx build-with-ai context
npx build-with-ai set decisions.database "PostgreSQL with Prisma"

Or edit decisions interactively — pick a key from a list and type the new value (JSON is parsed automatically):

npx build-with-ai config

6. Track Progress (status & resume)

npx build-with-ai status

PROJECT STATUS: Invoice Tracker
Template:   Modern SaaS MVP
Progress:   [============------------] 47% (7/15 steps)

WORKFLOW STEPS:
  [x] 1. Problem Discovery [Discovery]
  [x] 2. MVP Feature Scoping [Requirements]
  [x] 3. Technology Stack Selection [Tech Stack]
  [x] 4. Database Schema Design [Database]
  [x] 5. API Routes & Server Actions [API]
  [x] 6. Authentication Setup [Authentication]
  [>] 7. Stripe Subscription Integration [Payments] (Current)
  [ ] 8. Transactional Email Pipeline [Email]

7. Export Documentation and Editor Rules (export)

npx build-with-ai export

Generates standardized documentation from your build history:

• README.md — Project architecture and setup guide.
• BUILD_LOG.md — Chronological log of decisions and step history.
• .buildwithai/CONTEXT.md — Markdown projection of recorded state.

Use --out-dir <path> to export to a custom directory, --dry-run to preview output paths, or --force to overwrite an existing README.md. Without --force, interactive runs ask whether to overwrite, save as README.ai.md, or cancel; non-interactive runs preserve README.md and write the generated file to README.ai.md.

Sync Editor Rules (export --rules)

npx build-with-ai export --rules

Synchronizes recorded architectural decisions from context.json into editor instruction files across AI coding environments:

• .cursorrules (Cursor legacy)
• .cursor/rules/project-decisions.mdc (Cursor modern MDC format)
• .windsurfrules (Windsurf)
• CLAUDE.md (Claude Code / Anthropic)
• .github/copilot-instructions.md (GitHub Copilot)

Any custom instructions you have added outside the managed <!-- BUILD-WITH-AI:START --> block are preserved. Pass --dry-run to inspect target rule files without writing to disk.

8. Undo and Rollback (undo)

npx build-with-ai undo

Need to revise a prior step? undo safely rolls back the step counter to the previous step, restores the prior snapshot of context.json, and cleans up the corresponding step history file in .buildwithai/history/.

Commands Reference

Headless & CI Scripting

Use --json or --raw to integrate build-with-ai with automated pipelines or editor extensions:

# Extract prompt using jq (macOS / Linux)
npx build-with-ai next --json | jq -r '.prompt'

# Extract prompt in PowerShell (Windows)
npx build-with-ai next --json | ConvertFrom-Json | Select-Object -ExpandProperty prompt

# Disable clipboard globally in headless environments
export BUILD_WITH_AI_NO_COPY=1

MCP Server (AI-native editors)

npx build-with-ai mcp starts a native Model Context Protocol stdio
server, so editor agents (Cursor, Windsurf, Claude Code) and Claude Desktop can drive the workflow
directly. Available tools: get_workflow_status, get_active_prompt, complete_step, get_context.
Steps completed through complete_step automatically capture a pre-step snapshot so that undo can roll them back cleanly.

// Cursor: .cursor/mcp.json — Claude Desktop: claude_desktop_config.json ("mcpServers")
{
  "mcpServers": {
    "build-with-ai": {
      "command": "npx",
      "args": ["build-with-ai", "mcp"],
      "cwd": "/path/to/your/project"
    }
  }
}

BYOK Autonomous Mode (next --run)

Bring your own API key (or a local LLM) and skip the copy/paste round-trip: next --run
sends the step prompt to the model, writes the returned file blocks into your project, records
decisions into context.json, saves the raw response to history, and advances the step. Add
--review to see a colored diff of every proposed change and confirm before it is applied.

export OPENAI_API_KEY=sk-...                       # or ANTHROPIC_API_KEY / GEMINI_API_KEY / ...
npx build-with-ai next --run                        # autonomous step via OpenAI
npx build-with-ai next --run --review               # preview the diff first
npx build-with-ai next --run --provider anthropic   # pick a provider explicitly
npx build-with-ai next --run --provider ollama     # local model, no key needed

Supported providers: openai, deepseek, groq, together, ollama (local,
http://localhost:11434/v1), anthropic, gemini, jev. Keys resolve in this order:
--api-key flag → <PROVIDER>_API_KEY environment variable → .buildwithai/.env
(gitignored automatically on init). Override the model or endpoint per provider with
<PROVIDER>_MODEL / <PROVIDER>_BASE_URL (or --model / --base-url). The client is
zero-dependency (native Node fetch) and the default clipboard workflow is unchanged when
--run is not passed.

Architecture & Storage Design

All metadata and state are stored in a self-contained .buildwithai/ directory within your project root:

my-project/
├── .buildwithai/
│   ├── state.json        # Progress tracking (currentStep, completedSteps, timestamps)
│   ├── context.json      # Structured decisions store (single source of truth)
│   ├── template.json     # Persisted custom template (when initialized via --template)
│   ├── snapshots/        # Step snapshots enabling safe `undo` and rollback
│   ├── CONTEXT.md        # Formatted markdown view of context.json
│   └── history/          # Archived step responses (step-01.md, step-02.md, ...)
├── src/                  # User application code (never touched by the CLI)
├── README.md             # Generated on export
└── BUILD_LOG.md          # Generated on export

Branch-scoped storage (multi-branch workflows)

By default, all git branches share the single .buildwithai/ directory. Set BUILD_WITH_AI_BRANCH_SCOPED=1
to isolate state per branch:

export BUILD_WITH_AI_BRANCH_SCOPED=1

When enabled, the CLI detects the current git branch and stores that branch's state.json, context.json
and history/ under .buildwithai/branches/<branch-name>/ instead. Branch names are sanitized into a
single safe directory segment (e.g. feature/auth becomes feature-auth), so they can never escape the
branches/ directory. When git is unavailable, the directory is not a git repository, or HEAD is detached,
the CLI falls back to the default shared .buildwithai/ storage. reset only clears the current branch's
storage; other branches are left untouched.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for details on code style, template schema requirements, and pull request procedures.

Please also review our Code of Conduct.

Security

If you discover a security vulnerability, please review our Security Policy and report it privately to [email protected].

Maintainers

build-with-ai is maintained by PicadoLabs.

• Maintainer: Kaap10
• Organization: PicadoLabs
• Contact: [email protected]

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Copyright (c) 2026 PicadoLabs.