build-with-ai

---

Why build-with-ai?

Prompting an AI model to “build an entire app” typically breaks down in three ways:

1. The Blank Canvas Problem: Monolithic prompts produce hallucinated schemas and unmaintainable code dumps.
2. Context Drift: In long conversations, AI forgets early database designs, auth models, and naming standards.
3. Skipped Foundations: Models jump to frontend polish before data models, contracts, and error handling exist.

build-with-ai solves this by breaking application development into structured, sequential engineering phases. It records decisions in a local context.json file and automatically injects them into downstream prompts ({{decisions.key}}).

Key Principles

• Zero API Keys & Zero Cost: Runs 100% locally in your terminal. Works out of the box with web UIs (ChatGPT, Claude), IDEs (Cursor, Windsurf), or local LLMs (Ollama).
• Universal Compatibility: Generates tailored prompts for any AI model without vendor lock-in.
• Non-Destructive: State is maintained exclusively inside .buildwithai/ and never alters your application code unexpectedly.
• AI Editor Ready: Ships with a native Model Context Protocol (MCP) server and automatic editor rules synchronization (.cursorrules, CLAUDE.md, etc.).

---

Quickstart

Run directly without prior installation:

npx build-with-ai

Or install globally:

npm install -g build-with-ai

Initialize your workspace:

npx build-with-ai init

---

The 4-Step Workflow

graph LR
    A["1. init"] --> B["2. next"]
    B --> C["3. AI Implementation"]
    C --> D["4. done"]
    D --> B
    D --> E["5. export"]

1. Initialize (init)

Select a technology template, your experience level, and a project summary:

npx build-with-ai init

2. Generate Prompt (next)

Formats the active phase requirements, identifies target files, and copies the context-injected prompt to your clipboard:

npx build-with-ai next

3. Record Decisions (done)

Paste the prompt into your AI tool, review the generated code, and record architectural decisions:

npx build-with-ai done

You can also parse decisions directly from the clipboard:

npx build-with-ai done --from-clipboard

4. Export & Sync Rules (export)

Export clean Markdown documentation and sync your project decisions across editor rule files:

npx build-with-ai export
npx build-with-ai export --rules

---

Available Templates

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

Custom and Remote Templates

Load team-specific or custom templates from a local file or HTTPS URL:

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

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

# Discover community templates
npx build-with-ai search saas

Custom templates are persisted to .buildwithai/template.json and work fully offline for all subsequent commands.

---

CLI Reference

Core Workflow

Context & Configuration

Documentation & Editor Rules

---

Advanced Capabilities

BYOK Autonomous Mode

Bring Your Own Key or use local Ollama to bypass copy-pasting. The CLI executes the step prompt, writes returned code files into your workspace, updates context.json, and advances the phase:

export OPENAI_API_KEY=sk-...
npx build-with-ai next --run

# Preview git-style diffs before files are written
npx build-with-ai next --run --review

# Use a local model with Ollama (no API key required)
npx build-with-ai next --run --provider ollama

Supported providers: openai, anthropic, gemini, deepseek, groq, together, ollama.

Model Context Protocol (MCP)

Start a native stdio MCP server to let AI coding tools drive the workflow:

npx build-with-ai mcp

Add to your editor configuration (.cursor/mcp.json or claude_desktop_config.json):

{
  "mcpServers": {
    "build-with-ai": {
      "command": "npx",
      "args": ["build-with-ai", "mcp"],
      "cwd": "/path/to/your/project"
    }
  }
}

Exposed tools: get_workflow_status, get_active_prompt, complete_step, and get_context. Steps completed via MCP automatically create safe rollback snapshots.

Editor Rules Synchronization

Keep your AI coding assistant anchored to the project’s architectural decisions:

npx build-with-ai export --rules

Updates:

• .cursorrules and .cursor/rules/project-decisions.mdc
• .windsurfrules
• CLAUDE.md
• .github/copilot-instructions.md

All user instructions outside the managed `` block are preserved.

Optionally, configure exported decisions in .buildwithai/rules.config.json:

{
  "includeKeys": ["decisions.database", "decisions.auth"],
  "excludeKeys": ["decisions.scratchNotes"]
}

Both keys are optional; includeKeys selects decisions, excludeKeys removes them, and exclusions take precedence. Without this file, all decisions are exported.

Branch-Scoped Storage

To isolate state across git branches, enable branch scoping:

export BUILD_WITH_AI_BRANCH_SCOPED=1

State is isolated under .buildwithai/branches//, ensuring feature branches do not collide.

---

Storage Architecture

All state is self-contained inside your project’s .buildwithai/ directory:

my-project/
├── .buildwithai/
│   ├── state.json        # Progress tracking and current step pointer
│   ├── context.json      # Structured architectural decisions (single source of truth)
│   ├── template.json     # Persisted template (for offline execution)
│   ├── snapshots/        # Step snapshots for non-destructive undo/rollback
│   ├── CONTEXT.md        # Formatted markdown view of decisions
│   └── history/          # Historical step responses (step-01.md, step-02.md, ...)
├── src/                  # User application code (never touched by CLI)
├── README.md             # Generated on export
└── BUILD_LOG.md          # Generated on export

---

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for details on development setup, template specifications, and pull request guidelines.

Please review our Code of Conduct.

---

Security

To report security vulnerabilities, consult our Security Policy or contact [email protected].

---

Maintainer

• Maintainer: Vardhman Gupta
• Organization: PicadoLabs
• Contact: [email protected]

---

License

Licensed under the Apache License 2.0.

Copyright © 2026 PicadoLabs.