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.

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}}).

• 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.

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

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

build-with-ai includes 11 production-ready workflow 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

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

npx build-with-ai init

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

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.

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.

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...
------------------------------------------------------------

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"

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]

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 or --dry-run to preview output paths.

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

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)
│   ├── 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

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.

If you discover a security vulnerability, please review our Security Policy and report it privately to picadolabs@gmail.com.

build-with-ai is maintained by PicadoLabs.

• Maintainer: Kaap10
• Organization: PicadoLabs
• Contact: picadolabs@gmail.com

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

Copyright (c) 2026 PicadoLabs.