AI-powered project scaffolding with your team's conventions baked in.
ProjectForge is a CLI that collects project details, picks the best AI backend, assembles a structured prompt with your team's conventions, and routes generation through installed AI coding CLIs. You get a production-ready project directory in minutes instead of hours.
ProjectForge helps you:
- Collect project requirements interactively,
- Inject team and workspace conventions,
- Route generation through installed AI coding CLIs like Claude Code, Gemini CLI, or Codex,
- Inspect assembled prompts via dry runs,
- Audit project structures with convention drift detection,
- Maintain local preferences and logs under
~/.forge, - Scaffold demo apps without requiring real credentials or secrets.
- First-run setup wizard -- detects installed AI CLIs, backend readiness, editors, git, and Docker
- Multi-backend routing -- picks the best AI backend per phase with quality-based learning
- Interactive scaffold flow -- review-and-edit screen with smart defaults that learn your patterns
- Cinematic scaffold experience -- phase timeline, activity feed, file tree, and post-scaffold dashboard
- Convention injection -- compiles shared standards from the bundled
conventions/tree, with local overrides still supported - Convention auditing --
forge checkaudits any project against your standards with--fixand--export - Conventions admin --
forge admin conventionsvalidates, previews, and browses the bundled conventions system - Project augmentation --
forge evolveadds capabilities (auth, Stripe, WebSockets, etc.) to existing projects - Scaffold analytics --
forge statsshows your scaffold history and backend performance - Scaffold replay --
forge replay --diffreproduces past scaffolds and detects drift - Secret scanning -- checks user input for leaked credentials before passing to AI
- Post-scaffold automation -- manifest, git init, verification, hooks, Forge card, editor launch
- Design templates -- selectable visual style guides for frontend-capable scaffolds
- Shell completion -- tab completion for all flags and options
| Stack | Identifier | Aliases |
|---|---|---|
| Next.js + React | nextjs |
next, react |
| FastAPI | fastapi |
api |
| FastAPI + AI/LLM | fastapi-ai |
ai, llm |
| Next.js + FastAPI Monorepo | both |
fullstack, monorepo |
| Python CLI Tool | python-cli |
cli, typer |
| TypeScript npm Package | ts-package |
npm-package, library |
| Python Worker | python-worker |
worker, service |
See docs/guides/stacks.md for detailed structure, libraries, and dev commands.
brew tap <tap-owner>/<tap>
brew install projectforgegit clone <repository-url>
cd projectforge
uv sync --devMaintainer note: keep <tap-owner>/<tap> and <repository-url> placeholders until the
final public GitHub repository and Homebrew tap owner/name are chosen. Finalize those
release URLs after the repository transfer or rename.
Verify the installation:
forge --versionforgeForge walks you through the scaffold interactively, then shows a review screen before anything is generated.
Once confirmed, Forge routes each phase to the best available backend and runs them with a live progress display.
forge --name pulse --stack fastapi --description "health check API" --docker
forge --name storefront --stack nextjs --description "e-commerce site" --no-docker
forge --name platform --stack both --description "fullstack SaaS app"Preview the assembled prompt without executing:
forge --dry-runforge --use claude
forge --use gemini --model flashOn first run, Forge launches a setup wizard that checks backend readiness, editor preference, git setup, Docker availability, and project-directory defaults, then saves your preferences to ~/.forge/config.json.
After setup, Forge gives you a clean handoff -- create a project now, review setup again, or exit and come back later.
All user config lives under ~/.forge/:
| File | Purpose |
|---|---|
config.json |
Editor, backends, model preferences, Docker, sound, and project directory settings |
conventions.md |
Legacy user-level override file for prompt conventions (still supported) |
hooks/post-scaffold.sh |
Custom script run after every scaffold |
scaffold.log |
Append-only JSON-lines scaffold history |
quality.jsonl |
Quality signals per scaffold (powers smart routing) |
preferences.json |
Answer frequency data (powers smart defaults) |
Re-run setup at any time:
forge --setupSee docs/guides/configuration.md for the full reference.
Beyond the default scaffold flow, Forge includes purpose-built commands:
forge # Interactive scaffold (default)
forge stats # Scaffold analytics dashboard
forge evolve [capability] # Add capabilities to existing projects
forge check # Convention drift detection
forge replay # Reproduce past scaffolds
forge admin conventions # Validate, preview, and browse bundled conventionsCommon admin conventions flows:
forge admin conventions --validate
forge admin conventions --preview-stack fastapi
forge admin conventions --history global
forge admin conventions --open global/python-standards.md
forge admin conventionsForge ships with a portable skill at skills/forge-scaffold/ that teaches AI agents (Claude Code, Codex, Gemini CLI, or any agent that can read files and run shell commands) how to use Forge professionally.
What it gives an agent:
- How to detect and verify a Forge installation
- Complete command examples for every stack and option combination
- When to use
--dry-runvs live scaffold vsforge evolve - How to interpret the post-scaffold dashboard and fix verification failures
- How to audit projects with
forge checkand augment them withforge evolve - Stack selection guidance, backend routing rules, and option support constraints
How to use it:
Point your agent at the skill file:
skills/forge-scaffold/SKILL.md
Or if using Claude Code with a CLAUDE.md, reference it:
For project scaffolding, read skills/forge-scaffold/SKILL.mdThe agent gets full context on all commands, all stacks, smart defaults, quality routing, and the complete scaffold lifecycle -- so it can turn a rough product brief into a high-quality Forge run without guessing.
| Flag | Description |
|---|---|
--name, -n |
Project name |
--stack, -s |
Stack identifier or alias |
--description, -d |
Project description |
--use |
Override AI backend (claude, gemini, codex) |
--model, -m |
Model to pass to the AI CLI |
--docker / --no-docker |
Include Docker setup |
--auth-provider |
Auth provider (clerk, supabase-auth, authjs, better-auth) |
--ci / --no-ci |
Include GitHub Actions CI workflow |
--design-template |
Brand/design guide for frontend stacks |
--media |
Media collection to import into the project |
--demo / --no-demo |
Demo mode (runs without real API keys) |
--dry-run |
Print assembled prompt without executing |
--export |
Export prompt to a file |
--verbose |
Show full subprocess output and timing |
--open / --no-open |
Open project in editor after scaffolding |
--verify / --no-verify |
Run post-scaffold verification checks |
--setup |
Re-run the setup wizard |
--version, -v |
Show version |
| Command | Flag | Description |
|---|---|---|
forge stats |
Show scaffold analytics | |
forge check |
--fix |
Auto-generate missing convention files |
forge check |
--export FILE |
Export audit report to markdown |
forge evolve |
CAPABILITY |
Capability to add (e.g., auth, stripe) |
forge evolve |
--dry-run |
Preview the evolve prompt |
forge replay |
--diff |
Compare replay against current project |
forge replay |
--dry-run |
Preview reconstructed prompt |
When Forge runs, you see the full journey:
- Phase timeline -- a persistent progress bar showing completed, active, and pending phases with per-backend color coding.
- Activity feed -- a scrolling log of what the AI is doing right now. Completed steps get checkmarks; the current step pulses.
- File tree -- after each phase, a color-coded tree of everything created so far with file and line counts.
- Dashboard -- when it's done, a project report card with health check results (lint, typecheck, tests, build, /health), scaffold stats (files, lines, phases, deps), and contextual next steps.
Every scaffolded project also gets a .forge/card.svg project card and a badge auto-injected into the README.
Forge learns from every scaffold you run:
- Quality memory -- after each scaffold, Forge records whether lint, tests, typecheck, and health checks passed. Over time, it uses exponential moving average scoring to shift backend routing toward whichever AI CLI performs best for each stack and phase.
- Smart defaults -- Forge tracks your answer patterns. After 3+ scaffolds with consistent choices, it offers "Your usual setup: Auth: clerk, Docker: yes" with a single confirm prompt. Decline to see the full question flow; accept to skip straight to the review screen.
- Scaffold analytics --
forge statsrenders a terminal dashboard: total scaffolds, success rate, stack distribution bar chart, per-backend performance rates, and your most recent projects.
Run forge check in any project to audit it against team conventions:
forge check # pass/warn/fail scorecard
forge check --fix # auto-generate missing CLAUDE.md, .env.example, agent_docs/
forge check --export report.md # save for PR reviewsChecks cover structure (required files and directories), tooling (Ruff config, MyPy strict, CI, pre-commit), and runtime (health endpoints, Docker non-root user, HEALTHCHECK). Stack is detected from .forge/scaffold.json or pyproject.toml/package.json.
Instead of scaffolding from scratch, add capabilities to an existing Forge project:
cd my-project
forge evolve # interactive menu
forge evolve auth # add authentication directly
forge evolve stripe # add Stripe billingAvailable capabilities depend on the stack:
| Stack | Capabilities |
|---|---|
| FastAPI | auth, websockets, s3-uploads, stripe, worker, monitoring |
| Next.js | auth, analytics, i18n |
| Both | all of the above |
Evolve reads the project's .forge/scaffold.json for context, assembles a targeted prompt with the current file tree and key source files, and routes through the same backend system as scaffolding.
Reproduce a past scaffold using the project's original inputs:
cd my-project
forge replay # re-scaffold into a temp directory
forge replay --diff # compare the replay against your current project
forge replay --dry-run # preview the reconstructed promptReplay uses .forge/scaffold.json and .forge/conventions-snapshot.md (saved at scaffold time) for exact reproduction. The --diff flag recursively compares files and saves a report to .forge/replay-diff-<date>.md.
- Setup -- First-run wizard detects backends, checks readiness, saves defaults.
- Collect -- Interactive flow or CLI flags gather project details. Smart defaults pre-fill repeat choices.
- Review -- Edit selections before generation starts.
- Assemble -- Loads conventions, templates, and scans for secrets.
- Route -- Picks the best ready backend for each scaffold phase, informed by quality history.
- Execute -- Launches AI CLIs with phase timeline, activity feed, and file tree visualization.
- Finalize -- Writes manifest + conventions snapshot, generates Forge card, inits git, runs verification, plays completion sound, opens editor.
| Guide | Description |
|---|---|
| Docs Home | Map of user, maintainer, and reference docs |
| Getting Started | Installation, first run, first scaffold |
| Configuration | Config files, conventions, hooks, media assets |
| Stacks | Detailed reference for every supported stack |
| Admin Playbook | Maintaining conventions, adding stacks, shipping releases |
| Troubleshooting | Common issues and fixes |
| Homebrew Release | Formula generation and release flow |
The distribution package is named projectforge and the installed command is forge. The
Python import namespace remains ubundiforge for compatibility with existing releases; keep
that namespace in code, tests, and build configuration until a deliberate migration is planned.
uv sync --dev # Install in dev mode
uv run pytest # Run tests
uv run ruff check src/ubundiforge tests # Lint
uv run ruff format src/ubundiforge # FormatMIT -- see LICENSE.