Setup, troubleshooting
and reference

The core idea

Modular Chunks is an AI-powered project planning and build orchestration platform. Instead of feeding an AI a vague prompt and hoping for a complete app, Modular Chunks breaks your product into small, self-contained "chunks" — each one a precisely scoped unit of work with its own spec, contracts, and validation rules.

Each chunk is small enough for any AI coding tool to implement correctly in a single session, but defined precisely enough that the output can be validated automatically.

The pipeline, end to end

You move through the stages in the left-hand nav, starting from the Command Hub:

1. New project → Describe your idea — from the Command Hub, tell the platform what you want to build in your own words. It turns that into a plan and the first step.
2. Pre-flight (00) — a few questions about your experience, preferred tools, and project type, which calibrate how detailed and technical the outputs are.
3. Venture Intake (01) — structured capture of type, pitch, audience, tech direction, and industry, which drives matched personas, playbooks, and design guidelines.
4. Project Brief (02) — problem statement, target users, core features, and success metrics.
5. Architecture (03) & Product Requirements (03b) — stack and service design, plus a requirements document, enforced by your chosen Engineering Guideline.
6. Design Intake (04, hard gate) — pick a UI kit and capture density, motion, and accessibility. Nothing generates until this is locked.
7. Blueprint (05) & Chunk Studio (05b) — per-chunk specs with data models, API endpoints, state transitions, validation contracts, and design instructions. Generation runs server-side with a live progress bar; a quality gate rejects stubs, duplicates, and wrong-tech output.
8. Logic Explainer (06) — understand each chunk and propose changes before you build.
9. Node Assembly (07) — approved chunks are sequenced into agent-ready prompts, with three execution paths: the CLI, the Chrome extension (Ask Chunky side panel), or copy-paste.
10. CLI Execution (08) & Build Dashboard (09) — the chunky CLI (or your agent over MCP) builds one chunk at a time, validates each against its contract, and the dashboard tracks results.
11. Ask Chunky — a project-aware assistant you can consult at any point, with full context, from the terminal, the browser, or the Chrome side panel.

Who is it for?

• AI Prototypers — builders using Bolt, Lovable, or v0 who want structured, plain-English feature prompts to paste and build from. No schemas, no setup, no terminal.
• AI Pro Builders — builders using Cursor or Windsurf who want architecture-first specs with full data models and API contracts, written accessibly.
• Self-taught builders who want an AI co-pilot that respects their stack and explains key decisions without the jargon.
• Developers who want precise technical specs, data models, and contracts without doing the planning themselves.
• Senior engineers who want maximum depth, full contracts, and autonomous build loops via CLI autopilot.
• Teams who want consistent, documented, reviewable AI-assisted builds with role-based access.

How access works

Modular Chunks is in closed beta. You request access and tell us what you want to build, then we review the request and onboard you personally — usually within a day or two.

1. Go to Request access and fill in the short form (name, email, and where you build).
2. We review your request and get in touch to onboard you.
3. We set up your workspace with you, and you're in.

Already have an account?

Sign in with Google or your email and password. Your CLI uses the same account — run chunky login to connect it.

Two categories of tools

Web-based tools (no setup required)

These run entirely in your browser. You paste a chunk prompt and get generated code. Perfect if you're just getting started or want to prototype quickly.

• Bolt.new — paste your spec, get a full running app in seconds. Best for MVPs and rapid prototypes.
• Lovable — optimised for React + Supabase consumer apps. Great for builders without a deep technical background.
• v0 by Vercel — best for polished UI components with shadcn/Tailwind.

IDE-integrated tools (install on your machine)

These work alongside your code editor, understand your whole codebase, and can make multi-file changes. Better for complex, production-grade projects.

• Cursor — best all-rounder for full-stack TypeScript/Python. AI-native VS Code fork.
• Windsurf — strong context awareness across large codebases. Great for Next.js.
• GitHub Copilot — already in your VS Code or JetBrains IDE. Familiar extension model.
• Claude Code — terminal-based, maximum control. Best for senior engineers and complex multi-file tasks.
• Aider — terminal pair programmer, excellent for Python backends.

Which tool matches how you build?

• AI Prototyper → Bolt.new, Lovable, or v0. Paste the chunk prompt and watch it build. No installation, no terminal. Chunk prompts are plain English — no schemas.
• AI Pro Builder → Cursor or Windsurf. Your chunks include full architecture specs, data models, and API contracts ready for an AI IDE to implement.
• Self-taught Builder → Cursor or Windsurf, with GitHub Copilot as backup. IDE tools understand your whole project and can make multi-file changes.
• Developer → Cursor or Claude Code. Full codebase context, multi-file editing, and the Modular CLI for validation.
• Senior Engineer → Claude Code + autopilot + the MCP server. Fully autonomous build loops with Slack escalation.

Quick comparison

• No setup needed → Bolt.new, Lovable, v0
• Best multi-file editing → Cursor, Claude Code, Windsurf
• Best for Python backends → Aider, Claude Code
• Best for TypeScript/React → Cursor, Windsurf, GitHub Copilot
• Best for autonomous builds → Claude Code (autopilot), Factory
• Best for enterprise/compliance → Claude Code, Factory

Before you start

You'll need a Modular Chunks account. Modular Chunks is in closed beta — if you don't have access yet, see "Requesting access." Once you're in, the platform guides you through each stage. You don't need to install anything to plan your project; the CLI is only needed when you start building.

• From the Command Hub, click New project and choose Describe your idea.
• Answer pre-flight and refine the idea in Venture Intake.
• Review your brief, architecture, design, and blueprints.
• Approve your chunk blueprints.
• Install the CLI and start building.

Step 1 — New project → Describe your idea

Every project begins on the Command Hub. Click New project, choose "I'll describe my idea," and tell the platform what you want to build in plain language — a sentence or a paragraph. It reads that and sets up your project with the right first step. (Uploading an existing codebase is "Coming soon" in the chooser; the CLI's chunky upload does it today.)

Step 2 — Pre-flight and intake

Pre-flight asks how you build, your preferred coding tool, your project type, and your team size. These calibrate every AI output — from the language in your brief to how dense your chunk specs are. Intake is then a conversation; describe things the way you'd explain them to a friend, and the AI asks clarifying questions.

Step 3 — Review and approve blueprints

Once the pipeline generates your chunk blueprints, review each one and approve it on the platform (or from the terminal with chunky approve). Only approved chunks are pulled down to your CLI.

Step 4 — Install the CLI and pull your chunks

bash# Install the CLI globally (Node 18+)
npm install -g modular-chunks-cli

# Sign in, then set up the project
chunky login
cd my-project
chunky init
chunky config set projectId YOUR_PROJECT_ID

# Pull your approved blueprints
chunky pull

After pulling, run chunky status to see all your chunks and their state, and chunky show 1 to see the full prompt for chunk 1.

Step 5 — Build and validate

bash# See what to build next
chunky next

# Show the full prompt for a chunk (paste into your AI tool)
chunky show 1

# After building, validate
chunky validate 1

# On pass, sync the result to the platform
chunky sync 1

What is Cursor?

Cursor is an AI-native code editor built on VS Code. It understands your full codebase, edits multiple files at once, and accepts context rules via .cursor/rules/*.mdc files. It's the most popular choice for full-stack TypeScript and Python projects.

1. Install Cursor

1. Go to cursor.com and download the installer for your OS.
2. Install and launch Cursor — it's built on VS Code, so it'll look familiar.
3. Sign in with GitHub or a Cursor account.
4. Cursor has a free tier; a Pro plan removes AI rate limits.

2. Install the Modular CLI and connect

bashnpm install -g modular-chunks-cli
chunky login
chunky init
chunky config set projectId YOUR_PROJECT_ID
chunky pull

3. Build a chunk

bash">chunky show 1     # full spec for the next chunk

Paste the output of chunky show 1 straight into Cursor's Composer (Cmd+I); Cursor implements the whole chunk in one go. Then validate:

bashchunky validate 1

If validation fails, the CLI prints a detailed report. Paste the failure summary back into Composer and ask Cursor to fix the failing checks.

What is Claude Code?

Claude Code is Anthropic's official CLI for agentic coding. It runs in your terminal, reads a CLAUDE.md context file, and makes complex multi-file changes autonomously. It pairs perfectly with the Modular CLI because both run in the terminal and share the same context files.

1. Install Claude Code

bash# Requires Node.js 18+
npm install -g @anthropic-ai/claude-code

Authenticate per Claude Code's setup — an Anthropic API key or a Claude subscription.

2. Install the Modular CLI

bashnpm install -g modular-chunks-cli
chunky login
cd your-project-directory
chunky init
chunky config set projectId YOUR_PROJECT_ID
chunky pull

3. Configure CLAUDE.md

Claude Code reads a CLAUDE.md in your project root as its persistent instruction set. Generate one from your active context, then add any project-specific rules:

bashchunky context > CLAUDE.md

4. Autopilot — fully autonomous builds

The most powerful way to use Claude Code with Modular Chunks is autopilot. Run three terminals:

bash# Terminal 1 — MCP server (gives Claude the chunk tools)
chunky serve

# Terminal 2 — Autopilot supervisor
chunky autopilot --sync

# Terminal 3 — Claude Code
claude

Autopilot prints the chunk brief, Claude Code builds it, you run chunky validate, and autopilot advances to the next chunk on PASS.

What is GitHub Copilot?

GitHub Copilot is an AI assistant built into VS Code, JetBrains, and Visual Studio. You use it via the chat sidebar or inline completions, and it accepts project-level instructions via .github/copilot-instructions.md.

1. Subscribe and install

1. Visit github.com/features/copilot and sign up — there's a free tier for individuals.
2. Enable Copilot in your GitHub account settings.
3. Install the "GitHub Copilot" and "GitHub Copilot Chat" extensions in VS Code.
4. Sign in to GitHub from VS Code; Copilot activates automatically.

2. Connect the Modular CLI

bashnpm install -g modular-chunks-cli
chunky login
chunky init
chunky config set projectId YOUR_PROJECT_ID
chunky pull

3. Configure Copilot instructions

bashmkdir -p .github
chunky context > .github/copilot-instructions.md

4. Build chunks with Copilot Chat

1. Run chunky show 1 to get the chunk spec.
2. Open Copilot Chat (Ctrl+Shift+I).
3. Paste the spec and ask Copilot to implement it.
4. Review the generated code and save the files.
5. Run chunky validate 1.

What is Windsurf?

Windsurf is an AI-powered IDE whose "Cascade" agent understands your whole codebase and can edit across many files from a single prompt. It's particularly strong with Next.js + Supabase projects.

1. Install Windsurf

1. Download the installer from the Windsurf site.
2. Install and sign in (free tier available).
3. Open your project folder in Windsurf.

2. Connect the Modular CLI

bashnpm install -g modular-chunks-cli
chunky login
chunky init
chunky config set projectId YOUR_PROJECT_ID
chunky pull

3. Configure Cascade rules

bashchunky context > .windsurfrules

4. Validate and advance

bashchunky validate 1
chunky sync 1
chunky next

What is Bolt.new?

Bolt.new is a browser-based full-stack generator. You describe what to build and it creates a complete, running app in your browser — no installation. Ideal for AI-first builders and rapid prototyping.

1. Get your chunk prompt

• From the platform — open a chunk on Assembly and copy its coding instructions.
• From the Chrome extension — Ask Chunky hands you a paste-ready prompt tuned for Bolt.
• From the CLI — run chunky show 1 after pulling your project.

2. Paste into Bolt.new

1. Open bolt.new.
2. Paste the chunk prompt, including data models, endpoints, and brief context.
3. Click Start — Bolt generates the implementation.
4. Review in the browser preview.
5. Download as a ZIP or sync to GitHub.

3. Validate (optional)

bash# After exporting Bolt to a local folder
cd bolt-project
npm install -g modular-chunks-cli
chunky login
chunky init
chunky config set projectId YOUR_PROJECT_ID
chunky pull
chunky validate 1

What is Lovable?

Lovable is a prompt-to-product platform optimised for React, Supabase, and Tailwind apps — designed for builders who want to ship without writing code themselves.

1. Create a project

1. Sign up at lovable.dev and create a new project.
2. Connect Supabase when prompted (Lovable creates the database).

2. Start with your brief

Give Lovable the overall context first. Copy your brief from Modular Chunks and paste it as the opening message.

3. Build chunk by chunk

For each chunk, copy its coding instructions from Assembly (or the Ask Chunky side panel) and paste them in. Be explicit: "Implement chunk 2: User Authentication. Requirements: [paste]."

Three ways to connect

• Auto-setup — chunky setup <agent> wires up context files for Cursor, Claude Code, Windsurf, Copilot, Aider, Cline, and Junie.
• MCP — run chunky serve and any MCP-compatible agent gets the chunk tools directly.
• Copy-paste — chunky show <chunk> (or the Ask Chunky side panel) hands you a paste-ready prompt for anything else, including Factory and v0.

Auto-setup

bashchunky setup aider     # also: cline, junie, cursor, claude, windsurf, copilot

This writes the agent's context/rules file from your active guideline so the agent builds with full project context.

MCP for everything else

bashchunky serve            # MCP stdio for MCP-native agents
chunky serve --http     # HTTP server for non-MCP agents

Installation

bashnpm install -g modular-chunks-cli
chunky --version

Account

bashchunky login      # sign in (browser/device flow)
chunky signup     # create an account
chunky logout
chunky whoami

Core build loop

bashchunky init                         # set up .modular/ in this project
chunky config set projectId YOUR_ID # point at your project
chunky pull                         # pull approved blueprints
chunky status                       # all chunks + validation state
chunky show 1                       # full prompt for a chunk
chunky next                         # next chunk to build
chunky validate 1                   # check output against the contract
chunky sync 1                       # push the result to the platform

Plan & context

bashchunky intake        # full upstream pipeline from the CLI
chunky brief         # review/refine the brief
chunky arch          # review/refine the architecture
chunky blueprint generate | list | approve
chunky context       # active guideline, playbook, review, brief, arch, chunks
chunky log "We use Supabase Auth, not NextAuth"   # decision injected into all prompts
chunky reset brief | architecture | blueprint | session | all

Quality & delivery

bashchunky review run    # run a review checklist
chunky audit init | push | status   # audit an existing codebase
chunky debug [chunk] [--inject]     # triage a stuck issue into one focused prompt
chunky approve [--all] [--list]     # approve chunks from the terminal
chunky launch [--tier mvp|saas|enterprise]
chunky deploy [--platform vercel|railway|render|fly|docker]

Crash recovery

bashchunky checkpoint "before auth refactor"
chunky resume [--from-platform]

Ask Chunky & surfaces

bashchunky ask "how should I structure the auth chunk?"   # answered with full project context
chunky tui         # project-aware Chunky terminal in the browser
chunky listen      # watch the clipboard for agent questions and offer to ask Chunky
chunky ui          # local dashboard — build status + debug
chunky serve       # MCP server for your agent
chunky extension   # manage the VS Code extension

What is autopilot?

Autopilot is a supervisor that runs the whole build loop without approval at each step. It prints the chunk brief, watches for validation results, advances on PASS, retries with feedback on FAIL, and escalates to Slack when retries are exhausted.

Basic usage

bash# Terminal 1 — MCP server
chunky serve

# Terminal 2 — autopilot
chunky autopilot

# Terminal 3 — your agent (Claude Code, Cursor, etc.)
claude

Options

bashchunky autopilot \
  --max-retries 5 \   # retry limit per chunk (default 3)
  --sync \            # auto-sync to the platform on each PASS
  --slack \           # Slack escalation when retries are exhausted
  --spend-limit 20 \  # refuse to start if projected cost exceeds this (USD)
  --dir ./src

How the loop works

1. Autopilot reads the cache and finds the next approved chunk.
2. It prints the full brief (project context + chunk prompt + supervisor rules).
3. Your agent implements the chunk.
4. You or the agent run chunky validate N.
5. On PASS: auto-syncs (if --sync), clears the retry counter, prints the next brief.
6. On FAIL: injects the failure report into the next prompt and retries.
7. After max retries: escalates via Slack (if --slack) or exits with code 2 for CI.

Slack escalation

When a chunk exceeds its retry limit, autopilot can send a Slack message with the failure report and wait for a decision — approve (resume with a reset counter) or request changes (inject feedback). Configure Slack in your project .env.local, then run with --slack.

bashSLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_SIGNING_SECRET=your-signing-secret
SLACK_CHANNEL_ID=C1234567890

What it does

chunky serve starts a Model Context Protocol (MCP) server. MCP-compatible agents connect to it and call structured tools instead of reading raw text. Around 19 tools are auto-registered; the ones you'll see most:

• get_current_chunk — the current chunk spec with full context
• get_session_state — what's been built and validated this session
• update_session_state — mark files complete, record pivots, log discarded approaches
• ask_cto — route an architectural question to the AI CTO and record the ruling
• log_user_decision — log a decision so it appears in all future prompts
• get_project_context — the full brief + architecture + active guideline/playbook

Setup

bash# Terminal 1 — start the MCP server
chunky serve

# Terminal 2 — start your agent (auto-discovers MCP servers)
claude

# For non-MCP agents, expose it over HTTP instead
chunky serve --http

What it does

The "Ask Chunky" Chrome extension opens a side panel beside any tab. Chunky has full project context via your CLI token, so you can ask "what should I work on next?", "explain chunk 3", or "refine the brief" and get a streaming answer without leaving your work.

Every chunk renders as a card with a Copy button. Chunky tunes the format to the active platform — imperative build briefs for Bolt / Lovable / v0 / Replit Agent / Base44, conversational asks for Claude / ChatGPT / Gemini / AI Studio / DeepSeek, focused snippets for StackBlitz / CodeSandbox.

• Paste-ready prompts for your AI coding agent
• A "Chunk 0" project-brief preamble that gives the agent venture context before the first technical chunk
• Right-click "Ask Chunky about this" on any selected text — works on any page
• 20 platforms recognised by URL (AI app builders, chat models, sandboxes, visual builders)

Install

1. Add "Modular Chunks — Ask Chunky" from the Chrome Web Store.
2. Pin the icon to your toolbar.
3. Run chunky login in your terminal, then copy your token from the account CLI page.
4. Click the extension → Settings → paste the token → Save.
5. Chunky lists your chunks; start asking, or hit Copy on any chunk.

Privacy

The extension talks only to modularchunks.com over HTTPS. It doesn't inject scripts into coding platforms, read page contents, or track browsing history. Copy/paste is explicit — nothing leaves your clipboard until you paste it. Full disclosure is in the privacy policy.

Authentication

All API requests require a Bearer token. Generate yours from the account CLI/API page (/auth/cli).

bashcurl https://modularchunks.com/api/assembly/contracts \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -G -d "projectId=YOUR_PROJECT_ID"

Key endpoints

GET /api/assembly/contracts

All chunk blueprints for a project, with approval and validation state.

POST /api/assembly/validation

Push validation results for one or more chunks.

json{
  "projectId": "YOUR_PROJECT_ID",
  "chunks": [
    { "id": "chunk-id", "validationStatus": "pass", "validationReport": { "checks": [] } }
  ]
}

POST /api/extension/sync · GET /api/extension/state

Sync local pipeline state to the platform, and fetch the latest state (used by the Chrome extension).

CI/CD integration

yamlname: Validate chunks
on: [push]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm install -g modular-chunks-cli
      - run: |
          chunky config set projectId ${{ secrets.PROJECT_ID }}
          chunky config set apiToken ${{ secrets.API_TOKEN }}
          chunky pull
          chunky validate --skip-tsc
          chunky sync

Recommended roles

• Project Owner — runs intake, reviews brief and architecture, approves blueprints.
• Technical Lead — sets the active guideline, playbook, and design system; reviews chunk specs for technical accuracy.
• Builders — each takes one or more chunks; builds, validates, syncs.
• Reviewer — runs chunky review run against completed chunks before merging.

Parallel builds

Multiple people can build different chunks at once as long as there are no dependency conflicts. The CLI enforces dependency order — chunk N+1 can't start until chunk N passes validation.

Code review

bashchunky review run 

The wizard walks the active review checklist, records pass/fail per item, and logs the result for traceability.

Decisions and pivots

bashchunky log "Supabase Row Level Security for all multi-tenant isolation"
chunky log "Auth uses Supabase Auth, not NextAuth — do not add NextAuth"

Where Modular Chunks fits

Modular Chunks sits between your idea and your first line of production code. It replaces the blank-page problem: instead of an empty repo and a vague spec, you start with a structured, validated build plan and chunk-by-chunk prompts ready for any AI coding tool.

• Before → idea, whiteboard, Figma, PRD
• In Modular Chunks → New project (Describe your idea) → Pre-flight → Venture Intake → Brief → Architecture → Product Requirements → Design Intake (hard gate) → Blueprint → Logic Explainer → Node Assembly
• After → coding tool (Cursor, Claude Code, Windsurf — auto-wired via the MCP tools), git, CI/CD, deployment

Recommended lifecycle

1. Command Hub — click New project and describe your idea to open the project.
2. Pre-flight — set your preferences once per account.
3. Intake — one conversation per project (30–60 min).
4. Brief, architecture, design review — async, ~15–30 min.
5. Blueprint approval — chunk by chunk, async.
6. CLI pull — one command.
7. Build loop — autopilot or manual per-chunk validation.
8. Sync — push results after each chunk.
9. Assembly — the full session summary when all chunks are done.

Git branching

bashgit checkout -b chunk/01-auth
# build chunk 1
chunky validate 1
git commit -am "feat: chunk 01 — authentication (chunky validated)"
git push origin chunk/01-auth
# open PR → review → merge
git checkout -b chunk/02-user-profile

How it works

Every project has one owner (the creator) and any number of invited members. Permissions are enforced by Postgres row-level security, so even a misbehaving client only sees what its membership allows.

Open the project → Settings → Members. Type a teammate's email; if they have an account they're invited immediately, otherwise they get an email invite that creates the account on first sign-in.

Roles

• Owner — full control. Edits every artefact, regenerates stages, transfers ownership, deletes the project, manages members. One owner per project.
• Member — full read-write on every artefact. Runs chunks, syncs to the CLI, comments, approves / requests changes. Can't delete the project or change roles.
• Viewer — read-only. Sees every artefact and comment but can't edit. Good for stakeholders.

What members see & removing them

Every artefact, chunk, and comment, with realtime updates on save. CLI keys aren't shared — each member generates their own at /auth/cli. Notifications respect each member's personal preferences. Owners remove members from Settings → Members; access and their project CLI keys are revoked immediately.

Three channels

Notifications go through three channels independently — mix and match per event.

• Email — transactional. Always on for delete confirmations and billing receipts; opt-in per event for everything else.
• Web Push — browser + iOS PWA + Android. Works on locked phones (PWA install required for iOS).
• Slack — personal DMs via per-user OAuth. Each user installs the app to their own workspace; the bot DMs only them.

Configuration

All three are configured at /account/notifications, with granular toggles per event:

• Chunk approval / changes requested / new comment
• Autopilot stalled / completed
• CLI validation pass / fail
• Pipeline stage ready (brief, architecture, PRD, blueprint)
• Spend cap approaching / payment failed
• API key created / new device sign-in
• Recurring task fired / failed

Slack install

Click "Connect Slack" on /account/notifications, pick a workspace, and the bot opens a DM. You can install to multiple workspaces; revoke any from the same page.

Usage & the trial

Your plan includes a monthly token allowance, with pay-as-you-go beyond it, and a 14-day free trial with no card up front. Tokens are counted across every AI-touching call — brief, architecture, PRD, per-chunk blueprint, Ask Chunky, audit, deploy assistant, drift check, skill discovery — and each call is recorded so /account/usage shows exactly where your tokens went.

Spend cap

Set a hard monthly cap at /account/billing. Once you cross it, every AI endpoint returns 402 (Payment Required) until you raise the cap or the next cycle begins — so even a runaway script can't bleed past it.

Managing your subscription

Billing runs on LemonSqueezy, which handles VAT, sales tax, and refunds globally. Click "Manage subscription" on /account/billing to change plan, update payment method, view invoices, or cancel. Refunds within 14 days are automatic; later ones are case-by-case via support.