npm: build-with-ai626 downloadsApache 2.0 Open Source

Build full-stack software with any AI.
Disciplined, deterministic, zero context drift.

A local-first CLI orchestrator that generates context-aware prompts, preserves architectural memory, and eliminates AI drift with zero API keys.

View on GitHubStar npm Package

626+

NPM Package Downloads

Zero API

100% Local and Free

7 Blueprints

Production Workflows

100% CI

Ubuntu, macOS and Windows

Interactive Simulation

Test Drive the CLI in Your Browser

Experience how build-with-ai guides your project step by step without requiring API keys or cloud dependencies.

build-with-ai · bash · 80x24

  ██████╗ ██╗   ██╗██╗██╗     ██████╗ 
  ██╔══██╗██║   ██║██║██║     ██╔══██╗
  ██████╔╝██║   ██║██║██║     ██║  ██║
  ██╔══██╗██║   ██║██║██║     ██║  ██║
  ██████╔╝╚██████╔╝██║███████╗██████╔╝
  ╚═════╝  ╚═════╝ ╚═╝╚══════╝╚═════╝ 
  build-with-ai v1.4.0 · Zero API Software Architect CLI
  Type 'help' to see commands, or 'next' to generate prompt.

Active Blueprint: Modern SaaS MVP (15 Steps) Progress: [████████░░░░░░░░] Step 5/15 (33% Complete) Phase: Phase 02 · Auth & Subscription Billing

Try:

System Architecture

The 5-Stage Closed Engineering Loop

How build-with-ai preserves state across multiple chat sessions and prevents the AI from forgetting earlier architectural decisions.

Select Blueprint & Initialize Project

Developer picks a battle-tested blueprint. The CLI initializes local-first storage inside `.buildwithai/context.json` without cloud telemetry.

CLI Injects Memory & Generates Prompt

The prompt engine pulls architectural decisions from earlier steps and constructs a complete, context-aware prompt with zero context drift.

AI Model Generates Disciplined Code

The AI produces targeted, single-responsibility code, schema migrations, or configurations that strictly adhere to earlier project constraints.

Code Saved & Decisions Recorded

Developer verifies code on disk and confirms the step in the CLI with `done`. Any new architectural choices are captured.

Local Memory Updated For Next Step

Choices persist in `.buildwithai/context.json`. Downstream steps (e.g. Step 5: Auth Middleware) automatically inherit these values.

Stage 1: CLI Initializer

Active Stage

Developer picks a battle-tested blueprint. The CLI initializes local-first storage inside `.buildwithai/context.json` without cloud telemetry.

Payload / Contract Data:

$ npx build-with-ai init
? Select Blueprint: Modern SaaS MVP (15 Steps)
? Project Name: my-saas-platform
[OK] Created .buildwithai/context.json
[OK] Initialized Phase 01: Architecture & Foundation

Production Templates

7 Built-in Architectural Blueprints

Battle-tested phased workflows for full-stack apps, SaaS MVPs, REST APIs, mobile apps, extensions, and AI pipelines.

Full-Stack Web Application

23 Phased Steps

End-to-end modern web monolith or hybrid architecture with robust auth, relational schema, automated tests, and CI/CD.

Next.js / ViteTailwind CSSPrisma / DrizzlePostgreSQLNextAuthStripeJest / PlaywrightVercel

Phase 01Steps 1 to 6

Discovery & Schema Architecture

System requirements & user journeys
Relational database schema modeling
API route contracts & status codes

Phase 02Steps 7 to 12

Scaffolding & Authentication

Project initialization & linting
Database migration & ORM client setup
Session auth & role-based middleware

Phase 03Steps 13 to 18

Core Features & State Engine

Server actions & data fetching hooks
Interactive UI components & forms
Stripe payment webhooks & billing

Phase 04Steps 19 to 23

Testing, Hardening & CI/CD

Unit tests for services & edge cases
End-to-end Playwright user flows
Production Docker & Vercel deployment

Prompt Intelligence

Dynamic Context Interpolation Engine

See how build-with-ai substitutes template placeholders with concrete architectural decisions stored in context.json.

Raw Prompt Template (blueprint.json)Template Tokens

Target: Generate Data Access & API Routes

Database Provider: {{decisions.database}}
ORM / Query Engine: {{decisions.orm}}
Authentication Layer: {{decisions.auth}}
Frontend Framework: {{decisions.framework}}

Generate CRUD handlers with error schemas and validate session permissions using {{decisions.auth}}.

Resolved Prompt (Sent to AI)Auto-Injected

Target: Generate Data Access & API Routes

Database Provider: Supabase PostgreSQL
ORM / Query Engine: Prisma v5 (CUID Keys)
Authentication Layer: Supabase SSR Auth
Frontend Framework: Next.js 14 App Router

Generate CRUD handlers with error schemas and validate session permissions using Supabase SSR Auth.

Core Engineering

Engineered for Developers Who Value Quality

Built from the ground up with local-first reliability, complete data sovereignty, and deterministic output.

Zero API & 100% Local Privacy

Requires no API keys, cloud accounts, or telemetry. All templates, progress, and architectural decisions live locally inside your project folder.

Dynamic Context Interpolation

Uses regex template resolvers to dynamically interpolate decisions across prompts. Downstream steps always remember choices made in upstream phases.

Cross-Platform Clipboard Sync

Gracefully synchronizes generated prompts with macOS pbcopy, Linux xclip/wl-copy, and Windows clip.exe, with headless CI fallbacks.

Deterministic Doc Generator

Automatically compiles production-ready README.md, full BUILD_LOG.md, and CONTEXT.md documentation files as you advance through project milestones.

Non-Destructive Safety Guarantee

Never deletes, overwrites, or executes destructive modifications against your source code. You remain in 100% control of file writes.

Extensible Blueprint Engine

Supports custom organizational blueprints loaded via local JSON files or HTTPS URLs, enabling engineering teams to standardize custom software workflows.

CLI Reference

Command-Line Interface

A clean, intuitive command set designed to fit into any modern developer terminal.

Standard CLI Command Set

Run from any project root

$npx build-with-ai

Setup

Launches interactive setup wizard to select blueprints, models, and configure project parameters

$build-with-ai next

Workflow

Generates and copies the next sequential phase prompt to clipboard with interpolated context

$build-with-ai status

Inspection

Displays ASCII progress bar, active phase, and completed steps checklist across the project

$build-with-ai done

Workflow

Marks current step complete, prompts for key technical choices, and updates context.json

$build-with-ai context

State Store

Prints the live JSON architectural decision store and active parameters in the terminal

$build-with-ai list

Blueprints

Lists all 7 built-in production templates with step counts, descriptions, and prerequisites

$build-with-ai export

Artifacts

Generates README.md, BUILD_LOG.md, and CONTEXT.md documentation from session history

Open Source Roadmap

Active Issues & Contributions

Help shape the future of build-with-ai. Pick a good first issue, propose new templates, or contribute core features.

#42

Add ESLint and automated code formatting check to CI pipeline

Set up a lightweight ESLint configuration and npm run lint command to enforce code quality, catch syntax issues, and verify consistent formatting in GitHub Actions CI.

cidx

#41

Add project progress metrics and timestamps to the status command

Enrich the status dashboard with elapsed project time calculation, last updated relative timestamps, recorded decisions count, and export readiness indicator.

enhancementgood first issue

#40

Add history inspect command to view previous step logs

Add CLI command build-with-ai history to inspect recorded AI summaries and step history files directly from terminal without opening history folder.

enhancementgood first issue

#39

Add search and json options to the list command

Improve blueprint discovery by adding keyword search filtering and machine-readable JSON array output for external automation.

enhancementgood first issue

#38

Add unit test coverage for contextBuilder dot-notation edge cases

Dedicated unit test suite in test-flow.js to rigorously verify getByPath, setByPath, and flattenObject against complex deeply nested structures.

good first issuetests

#37

Add Python FastAPI & Microservices workflow template

Create fastapi-backend template guiding developers through building scalable, production-grade Python backend services with FastAPI, Pydantic v2, and async SQLAlchemy.

good first issuetemplates

#36

Implement atomic file writing for state and context persistence

Prevent state file corruption if a terminal session is abruptly killed midway through a save by writing to a temporary file and performing an atomic rename.

enhancementreliability

#35

Add custom out-dir option to the export command

Allow export command to write generated project documentation (README.md, BUILD_LOG.md, and CONTEXT.md) to a custom output directory.

enhancementgood first issue

#34

Add an Electron Desktop App workflow template

Create electron-app template covering the end-to-end SDLC for desktop applications built with Electron, React, TypeScript, and local SQLite.

good first issuetemplates

#33

Add no-copy flag and environment variable support to next command

Allow developers running in headless, CI/CD, or SSH environments to suppress automatic clipboard copy operations via no-copy flag or environment variable.

enhancementgood first issue

#29