Ship production apps from a single sentence.
An AI orchestration framework that plans, designs, builds, reviews, and deploys software
using a structured multi-agent pipeline — not a chat window.
$ forge auto "a personal finance tracker with budget categories, expense logging, and monthly reports"
forge auto
sandbox on · type a message anytime to queue feedback
[0:03] Plan ready
Personal Finance Tracker · nextjs
12 stories across 4 epics
Layout & Navigation
[full] App shell with sidebar navigation
[full] Dashboard landing page
Expense Management
[full] Add expense form with categories
[full] Expense list with filters
[ui] Category management page
Budget Tracking
[full] Budget setup per category
[ui] Budget vs actual progress bars
[full] Budget alerts and notifications
Reports
[ui] Monthly expense breakdown chart
[ui] Category pie chart
[full] Export to CSV
[full] Date range selector
Build · 12 stories
[0:15] [1/12] App shell with sidebar navigation · 8 files 2.1k in / 18.4k out
[0:48] [2/12] Dashboard landing page · 4 files 1.8k in / 12.1k out
[1:22] parallel: Add expense form, Category management
[2:01] [3/12] Add expense form with categories · 6 files 2.4k in / 21.0k out
[2:01] [4/12] Category management page · 3 files 1.2k in / 9.8k out
...
[14:02] Pushed to GitHub
─────────────────────────────────
Done in 14m 23s · 12/12 stories
28.4k in / 198.2k out
Every AI coding tool today works the same way: you type into a chat, the AI writes some code, you paste it in, something breaks, you go back and forth. There is no structure, no planning, no design phase, no review. You are the project manager, the QA engineer, and the glue holding it all together.
ForgeAI replaces that entire loop.
ForgeAI runs a complete software development pipeline autonomously. One command, six phases, zero copy-pasting.
PLAN DESIGN BUILD REVIEW PUSH SHIP
──── ────── ───── ────── ──── ────
Break into Generate Implement QA check Auto-push Tag, merge,
epics & Storybook each story each story, commits & deploy
stories previews with full auto-fix tags to
CLI power minor issues GitHub
Orchestrator Worker Worker Worker Git Git
Agent (design mode) (build mode) (review mode) Manager Manager
Each phase has a clear input, a clear output, and a gate between them. Stories that don't depend on each other build in parallel. After everything completes, the project is automatically pushed to GitHub (if a remote is configured). The whole thing runs on main with per-story commits and tags for easy rollback.
# Prerequisites: Node 18+, Claude Code CLI (logged in)
# Install globally
npm install -g forgeai
# Create a new project directory
mkdir my-app && cd my-app
# Initialize (choose Next.js, React+Vite, or Django)
forge init
# Build something
forge auto "a task management app with projects, due dates, and team assignment"
# Start the dev server
forge start
# If interrupted, resume where you left off
forge resume
# Fix a bug (supports screenshots)
forge fix "the sidebar overlaps on mobile" --image screenshot.png
# Push to GitHub manually (auto-push happens after forge auto)
forge pushThat's it. Come back in 15 minutes to a working app with proper types, responsive design, SEO metadata, favicons, and a README — already pushed to your repo.
Every project goes through Plan, Design, Build, Review, Push. Each phase has specialized prompts, tool permissions, and quality gates. The AI doesn't just write code — it writes code that builds, lints, and type-checks before moving on.
Instead of one monolithic agent or a swarm of disconnected ones, ForgeAI uses two:
- Orchestrator — The tech lead. Plans the sprint, crafts detailed prompts for each story, routes your feedback, reviews output. Never touches code.
- Worker — The engineer. Same agent, four modes (
design,build,review,fix), each with different system prompts and tool permissions. Preserves context across the entire build.
Stories are grouped by dependency. Independent stories build concurrently using Promise.all, cutting total build time significantly. A 12-story app that takes 45 minutes sequentially finishes in ~15 minutes.
Type a message at any point during the build. It gets queued and processed at the next safe point between stories. The Orchestrator classifies your input and routes it:
"make the header sticky" → Worker fix mode
"redesign the settings page" → Worker design mode → build mode
"the API returns 404 on /expenses" → Worker fix mode (debug)
"add a dark mode toggle" → New story added to sprint
"what's the database schema?" → Orchestrator answers directly
Pass a screenshot to forge fix and Claude reads the image to understand the visual issue:
forge fix "the button is cut off on mobile" --image screenshot.pngAfter forge auto or forge resume completes, commits and tags are automatically pushed to your GitHub remote. No manual git push needed. If the push fails, a warning is shown and you can retry with forge push.
Each worker mode has a maximum turn limit (design: 30, build: 50, review: 20, fix: 15). If an agent gets stuck in a loop, it stops gracefully instead of burning through your usage.
After the build phase completes, ForgeAI pauses and plays a notification sound. You choose: continue to review, skip review, or abort. You're always in control.
Every project gets the things most AI tools forget:
favicon.ico,icon.svg,apple-touch-icon.png- Open Graph image (
og.png) for social sharing - Complete metadata — title, description, OG tags, Twitter cards
robots.txt,sitemap.xml,manifest.jsonnext/imagefor all images- Auto-generated
README.mdbased on what was actually built
ForgeAI isn't locked to one framework. Each adapter knows how to scaffold, build, lint, and run a project in its stack:
| Framework | Language | Design Phase | Status |
|---|---|---|---|
| Next.js | TypeScript | Storybook | Stable |
| React + Vite | TypeScript | Storybook | Stable |
| Django | Python | Skipped | Stable |
| Flutter | Dart | — | Planned |
Worker prompts automatically adapt to the framework — Next.js gets App Router instructions, Vite gets SPA routing, Django gets migration commands.
If a build gets interrupted (auth expires, network drops, you close the terminal), your progress is saved. Run forge resume to pick up exactly where you left off. Blocked stories can be retried.
Pass --deploy and ForgeAI configures next.config for static export and creates a GitHub Actions workflow for automatic deployment.
forge auto "description" # Full autonomous pipeline (auto-pushes to GitHub)
forge auto "description" --skip-design # Skip Storybook previews (faster)
forge auto "description" --deploy # Add GitHub Pages deployment
forge auto "description" --mute # No notification sounds
forge auto "description" --quiet # Spinners only, no tool detailsforge init # Initialize ForgeAI in current directory
forge plan "description" # Generate sprint plan
forge design # Generate Storybook design previews
forge build # Build stories sequentially
forge review # Run QA review on built stories
forge sprint "description" # Run full pipeline with human gatesforge start # Start the dev server (auto-detects framework)
forge push # Push commits + tags to GitHubforge status # Show current sprint progress
forge map # Visual sprint map with status + dependencies
forge diff <v1> [v2] # Show changes between two versions
forge fix "description" # Fix a bug or make a small change
forge fix "desc" --image <path> # Fix with a screenshot for visual context
forge undo # Revert the last agent action
forge resume # Resume an interrupted sprint (auto-pushes)
forge history # Show version timeline and activity log
forge checkout <version> # Jump to a specific version or checkpoint
forge export # Export sprint plan as markdown
forge clean # Reset sprint state (keeps config)
forge doctor # Diagnose setup issuessrc/
├── cli/
│ ├── index.ts # CLI entry point (commander)
│ └── commands/
│ ├── auto.ts # forge auto — autonomous mode
│ ├── resume.ts # forge resume — resume interrupted sprint
│ ├── start.ts # forge start — start dev server
│ ├── push.ts # forge push — push to GitHub
│ ├── init.ts # forge init
│ ├── plan.ts # forge plan
│ ├── design.ts # forge design
│ ├── build.ts # forge build
│ ├── review.ts # forge review
│ ├── sprint.ts # forge sprint
│ ├── status.ts # forge status
│ ├── map.ts # forge map — visual sprint map
│ ├── fix.ts # forge fix (supports --image)
│ ├── undo.ts # forge undo
│ └── history.ts # forge history + forge checkout
│
├── core/
│ ├── orchestrator/
│ │ ├── index.ts # Orchestrator agent — plans, routes, reviews
│ │ └── prompts.ts # Orchestrator system prompt
│ │
│ ├── worker/
│ │ ├── index.ts # Worker agent — executes in 4 modes
│ │ └── prompts/
│ │ └── index.ts # Framework-aware mode-specific prompts
│ │
│ ├── pipeline/
│ │ ├── index.ts # Step-by-step pipeline
│ │ └── auto.ts # Autonomous pipeline (parallel, timer, gates, resume, auto-push)
│ │
│ ├── adapters/
│ │ ├── base.ts # FrameworkAdapter interface
│ │ ├── nextjs.ts # Next.js adapter
│ │ ├── react-vite.ts # React + Vite adapter
│ │ ├── django.ts # Django adapter
│ │ └── index.ts # Adapter registry + factory
│ │
│ ├── git/
│ │ └── index.ts # Git operations (branch, commit, tag, push)
│ │
│ ├── github/
│ │ └── index.ts # GitHub Issues sync (via gh CLI)
│ │
│ └── utils/
│ ├── config.ts # Config validation
│ └── sound.ts # Notification sounds (macOS/Linux/fallback)
│
├── state/
│ └── index.ts # State manager (.forge/ directory, cached)
│
└── types/
└── plan.ts # TypeScript types for the entire system
ForgeAI tracks everything in a .forge/ directory inside your repo:
.forge/
├── plan.json # Epics, stories, status, dependencies
├── state.json # Current phase, queue, history
├── config.json # Framework, model, preferences
├── snapshots/ # Pre-action snapshots for undo
└── designs/ # Design approval metadata
Every story gets a commit. Every milestone gets a tag:
main ────●────●────●────●────●────●──── HEAD → pushed to origin
│ │ │ │ │ │
│ │ │ │ │ └── forge/v0.6-export-csv
│ │ │ │ └── forge/v0.5-budget-alerts
│ │ │ └── forge/v0.4-budget-setup
│ │ └── forge/v0.3-expense-list
│ └── forge/v0.2-add-expense
└── forge/v0.1-designs
Roll back to any point with git checkout forge/v0.3-expense-list.
| Requirement | Details |
|---|---|
| Node.js | v18 or higher |
| Claude Code | Installed and logged in (npm i -g @anthropic-ai/claude-code && claude login) |
| Git | Any recent version |
| Subscription | Claude Max, Team, or Enterprise |
ForgeAI uses the Claude Agent SDK which authenticates through your Claude Code session. No separate API key needed.
After forge init, your forge.config.json controls:
{
"framework": "nextjs",
"model": "sonnet",
"designPreview": "storybook",
"autoCommit": true,
"storybook": {
"port": 6006
}
}| ChatGPT / Claude Chat | GitHub Copilot | Cursor | ForgeAI | |
|---|---|---|---|---|
| Planning | Manual | None | None | Automated sprint planning |
| Design preview | None | None | None | Storybook generation |
| Build | Copy-paste | Autocomplete | Inline edit | Full autonomous build |
| Review | Manual | None | None | Automated QA + auto-fix |
| Git strategy | Manual | Manual | Manual | Auto commits + tags + push |
| Parallelism | N/A | N/A | N/A | Dependency-grouped parallel |
| Human oversight | Full control | None | Approve/reject | Stage gates + live feedback |
| Bug fix with screenshots | N/A | N/A | N/A | forge fix --image |
| SEO & assets | You remember | You remember | You remember | Built-in defaults |
| Multi-framework | N/A | Any | Any | Next.js, React, Django |
| Resume on failure | Start over | N/A | N/A | Auto-save + resume |
v0.1 — Core pipeline, two-agent architecture, Next.js support
v0.2 — Autonomous mode, parallel execution, undo/history, GitHub sync
v0.3 — React + Vite and Django adapters, forge map, forge resume
v1.0 — Current
- 21 CLI commands covering the full development lifecycle
- 3 framework adapters (Next.js, React + Vite, Django)
- Framework-aware prompts via pluggable adapter system
forge start— auto-detect and launch dev serverforge push— push commits + tags to GitHubforge fix --image— screenshot-based bug fixing- Auto-push to GitHub after
forge autoandforge resume - Graceful shutdown with automatic progress save
- Config validation with actionable error messages
- Token expiry handling with auto-retry
v1.1 — Next Up
- Flutter adapter — Dart support with widget-based design previews
- Vue.js / Nuxt adapter — Vue 3 + Composition API + Nuxt 3 SSR support
- Svelte / SvelteKit adapter — Svelte 5 with runes and SvelteKit routing
- Test generation phase — auto-generate unit and integration tests after build (Vitest, pytest, Flutter test)
- Custom adapter plugin API — drop a JS file in
.forge/adapters/to add your own framework
v1.2 — Planned
- Multi-provider support — swap Claude for OpenAI, Gemini, or local models (Ollama) per agent
- Web dashboard — browser-based sprint monitoring with real-time build progress, token usage charts, and story diffs
- CI/CD integration — GitHub Actions / GitLab CI pipeline generation, auto-run tests on PR, deploy previews
- Cost estimation — token budget planning before sprint starts, per-story cost breakdown, spending alerts
v2.0 — Future
- Team collaboration — multiple users can queue feedback on the same sprint, role-based permissions (lead reviews, dev builds)
- Monorepo support — run separate pipelines for
packages/*with shared dependency tracking - Visual regression testing — screenshot comparison between versions, flag UI drift automatically
- Database schema generation — auto-generate migrations, seed data, and ERD diagrams from plan descriptions
- Accessibility audit phase — automated WCAG checks after build, auto-fix common a11y issues
- i18n / localization — generate translation keys and locale files from built UI, support RTL layouts
- Plugin system — community-built pipeline phases (e.g., performance audit, API docs, Docker setup)
- Template library — starter templates for common app types (SaaS dashboard, e-commerce, blog, landing page)
git clone https://github.com/joeljohn159/forgeai.git
cd forgeai
npm install
npm run build
npm link # Makes 'forge' available globallyMake changes in src/, then npm run build to test.
MIT
Built by Joel John