@dreamtree-org/ai-builder

Scaffold a complete, working full-stack multi-tenant SPA in one command — Express API + Vite/React client, pre-wired to @dreamtree-org/korm-js (data) and @dreamtree-org/twreact-ui (UI), with module-driven RBAC, row-level grants, and CSS-variable theming.

ai-builder is an AI-native CLI with these jobs:

• ai-builder <app-name> — scaffold a complete app on disk, then get out of the way.
• ai-builder init --ai <provider> — install an app-building skill pack + MCP into any project.
• ai-builder update — check for a newer version and re-sync the installed skill pack + MCP to it.
• ai-builder mcp — run a zero-dependency, read-only MCP server: the build rules, data contract and module catalog, plus where your project is right now (project_state) and your installed libraries' real APIs (layer_docs).

It is not a runtime framework and does not own your app after generation. Targets apps that don't need SEO (client-rendered SPA, no SSR).

Aim: vibe coding with minimal tokens, world-class consistent output, proper SDLC — an assistant fetches the contract/catalog/rules live instead of re-reading files. Motto: One module registry, one data contract, one component library — zero hand-rolled CRUD, zero duplicated UI.

About the Company

@dreamtree-org/ai-builder is built and maintained under Dreamtree Global — a team crafting thoughtful, developer-first software for the modern web. We believe great products start with a great foundation, and that's exactly what this builder aims to be: a fast, consistent, AI-native way to ship full-stack multi-tenant apps.

🌐 Website: dreamtreeglobal.com

Author & Maintainer

Partha Preetham Krishna M L 📧 [email protected]

Have an idea, a bug, or just want to say hi? Reach out anytime — feedback from developers like you is what keeps this project growing.

💚 Sponsor & Support

@dreamtree-org/ai-builder is free and open source, built in the open and powered entirely by passion and late nights. Every app it scaffolds — every wired-up RBAC gate, module registry, KORM data contract, and MCP tool — represents hours of careful craft so that your team can ship faster and build consistently.

If this builder has saved you time, sparked an idea, or made your stack a little saner, please consider supporting its continued development. Your sponsorship keeps the updates coming, the bugs squashed, and the docs sharp — for the whole community. Even the smallest contribution is a huge encouragement. 🙏

☕ Make a one-tap donation via UPI

📷 Scan the QR with any UPI app (Google Pay, PhonePe, Paytm, BHIM, …) to pay instantly:

UPI ID: dhrugantha.llp@kotak  •  Payee: Dreamtree Global

📱 On mobile, you can also tap the button below — it opens your UPI app directly. On desktop, scan the QR above or copy the UPI ID into your payment app.

🤝 Become a Sponsor

Want to back the project long-term or as a company? You can sponsor the package directly:

• 📦 npm: @dreamtree-org/ai-builder — star, share, and sponsor the package
• ✉️ Corporate sponsorships & partnerships: [email protected]

Every star ⭐, share, and contribution helps more than you know. Thank you for being part of the journey!

Quick start

npx @dreamtree-org/ai-builder my-app

Then follow the printed next steps:

cd my-app
cp .env.example .env        # fill DB + JWT_SECRET
npm install
npm run db:sync             # create tables from schema/sync.json
npm run seed:rbac           # seed permissions from modules.config.js
npm run dev                 # Express API + Vite client

A scaffolded app already carries the app-building skill pack + the ai-builder MCP wiring (--ai <provider>, default claude; --ai none to skip). Add the two layer skills — the live data contract and component catalog:

npx @dreamtree-org/korm-js init --ai claude
npx @dreamtree-org/twreact-ui init --ai claude
# or just: npm run setup   (installs, builds, migrates, seeds, and does the above)

In a project you did not scaffold, install the skill pack yourself:

npx @dreamtree-org/ai-builder init --ai claude   # cursor | copilot | gemini | openai | all

init — install the skill pack + MCP

Run inside any project to give your AI assistant the rules and live tools to build a dreamtree app:

npx @dreamtree-org/ai-builder init --ai <provider>   # claude | cursor | copilot | gemini | openai | all

It writes the app-building skill to the provider's conventional location and merges the ai-builder MCP server into the provider's MCP config:

| provider | skill file | MCP config | | --- | --- | --- | | claude | .claude/skills/dreamtree-app-builder/SKILL.md | .mcp.json | | cursor | .cursor/rules/dreamtree-app-builder.mdc | .cursor/mcp.json | | copilot | .github/copilot-instructions.md | .vscode/mcp.json | | gemini | GEMINI.md | .gemini/settings.json | | openai | AGENTS.md | (Codex global ~/.codex/config.toml, printed) |

Flags: --no-mcp (skill only), --no-design-skill, --force, --dry-run.

init also installs the third-party ui-ux-pro-max design-intelligence skill (color palettes, font pairings, layout patterns — reference material for prompting, never a licence to hand-roll UI outside twreact-ui). It runs npx -y ui-ux-pro-max-cli init --ai <platform> in your project — a network install from a package we don't own — best-effort and time-bounded, so a failure warns and never aborts the skill/MCP install. Opt out with --no-design-skill. Scaffolding a new app does not install it.

Your own files are never overwritten. AGENTS.md, GEMINI.md and .github/copilot-instructions.md are shared conventions you write in too, so only the span between <!-- ai-builder:start --> and <!-- ai-builder:end --> belongs to us — everything else is left exactly as it was, and a file with no markers gets the block appended rather than replaced. Files that are wholly ours (.claude/skills/…, .cursor/rules/…) are preserved unless --force.

init never creates tracking/ — installing a skill pack shouldn't add documents to your repo. Scaffolded apps get it; elsewhere your assistant creates it from the plan_template tool when it first plans.

update — stay on the latest version

The skill pack init writes is a snapshot — a newer ai-builder may have shipped since. Run update (alias upgrade) inside the project to check and re-sync:

npx @dreamtree-org/ai-builder@latest update          # report version + re-sync skill/MCP to it
npx @dreamtree-org/ai-builder@latest update --check   # report only, write nothing

It reports the running-vs-latest version (a zero-dep, cached registry check), prints the command to upgrade the package itself, and re-syncs the installed, version-stamped skill pack + MCP wiring to the running version for every provider already set up here (or just --ai <provider>). It never runs npm install for you.

It also refreshes the korm-js + twreact-ui layer skills by running each package's own init --ai <provider> (best-effort — a layer failure warns and prints the manual command). Skip with --no-layers. And it reports version drift across the whole @dreamtree-org family — declared vs installed vs latest, per package, with the exact npm i <pkg>@latest to run.

| Flag | Description | | --- | --- | | --check | Report only — write nothing | | --ai <provider> | Re-sync just this provider (default: every provider already set up here) | | --no-layers | Skip the korm-js / twreact-ui skill refresh | | --no-mcp | Re-sync the skill only, leave MCP config alone | | --no-design-skill | Skip the ui-ux-pro-max design-skill refresh | | --dry-run | Print what would change (including the layer commands), write nothing |

scaffold and init also print a one-line nudge when you're behind. Set AI_BUILDER_NO_UPDATE_CHECK=1 to disable all version checks (air-gapped/CI). Your AI assistant can self-check via the check_version MCP tool and offer to run update.

mcp — the ai-builder MCP server

A zero-dependency stdio MCP server (raw JSON-RPC 2.0 — no SDK). init wires it in automatically; you can also register it manually:

{ "mcpServers": { "ai-builder": { "command": "npx", "args": ["-y", "@dreamtree-org/ai-builder", "mcp"] } } }

Eleven tools, all read-only — the server never writes to your project. Fetch facts instead of re-reading files:

| Tool | Returns | | --- | --- | | project_state | Call this first. The app on disk (modules, models, tables), installed layer versions, the state of tracking/plan.md incl. its Resume block, git — and a computed nextAction | | plan_template | the plan / big-picture / backlog skeleton + the rules that keep a plan resumable | | layer_docs | korm-js / twreact-ui docs read from your node_modules — a component's real props at the version you installed | | build_rules | the binding hard rules + RBAC model + add-a-feature path | | data_contract | the KORM processRequest contract + schema column format | | list_modules / describe_module | the starter module catalog; one module in full | | get_schema / get_registry | the generated schema/sync.json / modules.config.js | | scaffold_plan | the exact files a scaffold would emit (dry run) | | check_version | version drift across the whole @dreamtree-org family + the commands to fix it |

Why an agent stops guessing

Two problems this closes:

"Where was I?" A session can end mid-task; everything the agent worked out dies with it. Scaffolded apps ship a tracking/ trio — plan.md (active work, with a Resume here block rewritten at every task transition, not at the end), big-picture.md (architecture, seeded from your real registry and schema) and backlog.md. A fresh session calls project_state once and gets the next concrete action back. No re-reading ten files, no re-deciding what was decided.

"What props does <Button> take?" korm-js and twreact-ui each ship AI docs inside the package — ai-skills/*.md, and twreact-ui's dist/ai-schema.json with the per-component prop contract. layer_docs reads them out of your own node_modules, so answers are true for the version you actually installed. ai-builder deliberately keeps no snapshot of another package's API: a snapshot is stale the moment they publish.

A generated app is two npm projects — the API at the root and the SPA under client/ — and twreact-ui is declared and installed only in client/. Layer resolution accounts for that: from the app root it looks in the root node_modules, then in the nested app project, then upward, and tells you which one answered (workspace: "client", hoisted: false). Asking from the app root always works.

Usage

npx @dreamtree-org/ai-builder <app-name> [options]

| Option | Description | | --- | --- | | --db <mysql\|pg\|sqlite> | Database client (default: sqlite for local dev) | | --modules <a,b,c> | Starter module keys (default: core) | | --ai <provider\|none> | Install the skill pack + MCP wiring into the new app (default: claude) | | --yes, -y | Accept defaults, skip prompts | | --dry-run | Show the file plan, write nothing | | --force | Overwrite a non-empty target directory | | --help, -h | Show help |

Starter modules

core is always generated (RBAC, settings, per-tenant API tokens). The rest are opt-in examples you can keep, replace, or delete:

| Key | Models | Demonstrates | | --- | --- | --- | | core | User, Role, Permission, ApiToken, Setting | RBAC engine + external API tokens | | billing | Bill, Passbook | row-level grants (default-deny per-Passbook access) | | inventory | Product, Category | plain CRUD with a foreign key | | crm | Lead, Customer | CRUD + export action |

npx @dreamtree-org/ai-builder my-app --db pg --modules billing,inventory

How it works

A zero-runtime-dependency CLI generates the app from a module registry.

argv ─▶ src/index.js ─┬─▶ src/prompts.js       (appName, db, modules, brand)
                      ├─▶ src/moduleCatalog.js
                      │     buildRegistry(modules) ─▶ modules.config.js
                      │     buildSchema(modules)   ─▶ schema/sync.json (KORM format)
                      ├─▶ src/generate.js
                      │     walk templates/app/** ─▶ src/substitute.js ─▶ target dir
                      └─▶ src/init.js          (--ai <provider>, in-process)
                            skill pack + MCP wiring ─▶ the new app

Token substitution is the only "templating engine" — no Handlebars/EJS. The templates under templates/app/** are real, lint-clean files; dynamic pieces (modules.config.js, schema/sync.json, the DB driver dependency, the .env.example DB block) are computed from the chosen modules and injected as __TOKEN__ substitutions (src/substitute.js, shared by the generator, init and the MCP server).

The last step runs init in-process against the new app, so a fresh scaffold already has the skill pack + MCP wired for --ai <provider> (default claude, none to skip). The provider value is validated before any file is written, and nothing on this path touches the network.

Generated app architecture

        Express API ──processRequest──▶ korm-js ──▶ DB (mysql/pg/sqlite)
            ▲
        /api/crud/:Model
            │
        Vite/React SPA ── composes ──▶ twreact-ui

The single source of truth in a generated app is modules.config.js — it derives permissions, navigation, routes, and the model→module map. RBAC is enforced uniformly as (module, action, scope), with BaseTenantModel adding branch scoping and instance-grant WHERE … IN injection for row-level access. Multi-tenant by default: a platform DB (tenants, modules, superadmin) and a per-tenant DB resolved per request by middleware/tenantResolver.js.

Repository layout

| Area | Path | | --- | --- | | CLI entry | bin/cli.js | | Orchestrator / subcommand dispatch | src/index.js | | Interactive prompts | src/prompts.js | | Module catalog → registry + schema | src/moduleCatalog.js | | Generator (copy + token substitution) | src/generate.js | | __TOKEN__ substitution (shared by generate / init / mcp) | src/substitute.js | | init --ai (skill pack + MCP wiring, managed blocks) | src/init.js | | update (version check + family drift + re-sync) | src/update.js | | Version policy + semver (checkForUpdate, familyStatus) | src/version.js | | npm registry lookups (https → npm view → floor, cached) | src/registry.js | | Read-only introspection of a generated app on disk | src/project.js | | project_state assembly + the computed nextAction | src/projectState.js | | Version-accurate layer docs from node_modules | src/layerDocs.js | | MCP server (zero-dep stdio JSON-RPC, read-only) | src/mcp/server.js | | Compact build knowledge (MCP + skill) | src/knowledge.js | | Terminal UI helpers | src/ui.js | | Generated-app templates | templates/app/** | | Generated-app agent memory (plan / architecture / backlog) | templates/app/tracking/** | | App-building skill body (installed by init) | templates/skills/app-builder.md | | Design SSOT (decisions + rationale) | SOP-ai-app-builder.md | | Architecture SSOT (HLD/LLD) | tracking/big-picture.md | | Bug / quality / vision backlog | tracking/backlog.md |

Development

The scaffolder uses Node built-ins only (no runtime dependencies); requires Node >= 18.

git clone [email protected]:DreamtreeTech/ai-builder.git
cd ai-builder
npm run test:smoke   # scaffolds + syntax-checks an app, parses schema/registry (no network)

Run the CLI locally without publishing:

node bin/cli.js my-app --dry-run

Two CI workflows guard the repo. ci.yml runs the smoke test on every PR and push to main — fast, no network. e2e.yml does the real thing: scaffold → npm install → db:sync → seed:rbac → vite build → boot → /health, /api/meta/modules and an unauthenticated-CRUD-401 check, plus layer_docs against the app's actual node_modules. It runs nightly, on push to main, and as a gate on every release.

Releasing

Publishing is automated and tag-driven — never run npm publish by hand.

1. Land the work on main with CI green.

2. Add the release's entry to CHANGELOG.md under a new ## [x.y.z] heading, refresh any docs the change invalidated, and commit.

3. Bump + tag + push in one step:

   npm run release:patch   # or release:minor / release:major

   That runs npm version, which rewrites package.json, commits chore(release): vX.Y.Z, creates the annotated vX.Y.Z tag, and pushes both.

4. The tag push fires .github/workflows/release.yml: the e2e gate, then the smoke test, then npm publish, then a GitHub release whose notes are the matching CHANGELOG.md section.

Nothing between step 3 and the published tarball is manual. If a pre-publish gate fails, fix it and re-run the workflow — no version is burned, because nothing was published.

Contributing rules (must-read)

CLAUDE.md is the single source of truth for any contributor (human or AI). The non-negotiables:

1. The SOP is binding — changing a locked decision means updating SOP-ai-app-builder.md in the same change.
2. Compose twreact-ui; never duplicate UI. A gap is a GitHub issue against the twreact-ui repo, not an inline copy.
3. All data access goes through KORM — no raw SQL, no scattered axios.
4. One module registry drives permissions, nav, routes, and the model→module map.
5. Schema is generated, not hand-authored.
6. The scaffolder stays zero-runtime-dependency.

License

MIT © Dreamtree Global

Support

• 📦 npm package
• 🐛 Issue tracker
• 🌐 Dreamtree Global
• 📧 [email protected]