modai — your local AI development team

A CLI where a seven-person AI development team builds software for you, and you are the client. Every agent runs on your own Ollama server — no cloud, no API keys.

The team

| Agent | Role | What they do | |---|---|---| | Maya | Product Manager | Your single point of contact. Presents work, runs checkpoints. | | Elena | Product Strategist | Asks discovery questions, writes the PRD. | | Kenji | UX Designer | Turns the PRD into screens, flows, and states. | | Priya | Tech Lead | Picks the stack (TS/React/Node by default), plans every file. | | Tom | Frontend Dev | Writes the React/TypeScript code, one file at a time. | | Sofia | Backend Dev | Writes the Node code when a server is needed. | | Marcus | QA Engineer | Reviews everything against the specs; devs fix what he flags. |

The workflow (checkpoint approvals)

Discovery ▸ PRD ✋ ▸ UX spec ✋ ▸ Architecture ✋ ▸ Build ▸ QA ▸ Delivery
                                                                  │
                     ┌────────────────────────────────────────────┘
                     ▼
             Iterations: change request ▸ Change plan ✋ ▸ Build ▸ QA ▸ PM report ▸ …

✋ = the team stops and waits for your approval. Type yes to approve, or just describe what you want changed and the responsible specialist revises.

After delivery the engagement stays open. The team asks "Anything else?" — describe a new feature or a bug and the architect writes a change plan (which you approve), the devs modify or add only the affected files, and QA reviews just what changed. This repeats until you type exit. Resuming a finished project drops you straight back into this loop, so you can come back days later and keep iterating.

The team works directly in the directory you run modai from. Generated code lands at its planned paths right there (e.g. ./src/App.tsx), approved specs go in ./docs/, and progress is saved after every step in ./.modai/ — so you can quit anytime and resume later. One directory = one product: running plain modai again in the same directory automatically resumes its engagement (modai new force-starts a fresh one).

Use it in any project directory (no global install)

Build once, in this repo folder:

npm install
npm run build

Then pick whichever style you prefer — neither touches your global npm:

A. Add it to a project as a dev dependency (recommended — pinned per project, shows up in its package.json):

cd C:\path\to\my-new-product
npm i -D C:\Users\samya\Projects\modai
npx modai            # start a new engagement here
npx modai resume     # pick up where you left off
npx modai list

npm links the folder rather than copying it, so after you edit modai and rerun npm run build, every project picks up the new version automatically.

B. Run it directly with npx, zero install (works even in directories with no package.json):

cd C:\anywhere
npx C:\Users\samya\Projects\modai
npx C:\Users\samya\Projects\modai resume

Like git, each directory is its own workspace: the generated code is written straight into the directory you run it from, with specs in ./docs/ and state in ./.modai/. Run it from an empty folder (or a repo you're happy for the team to write into).

If you ever publish it (npm publish --access public), option A becomes npm i -D @modalaideas/modai and B becomes npx @modalaideas/modai — no paths needed. The plain name modai is already taken on npm, which is why the package is scoped. Installing from a git repo also works: npm i -D git+https://github.com/<you>/modai.git (git installs build themselves via the prepare script).

Use as a library

The orchestrator is importable for building your own interface (e.g. the future web UI):

import { Orchestrator, newEngagement, saveState } from "@modalaideas/modai";

Setup (prerequisite)

# make sure Ollama is running and your model is pulled:
ollama pull ornith:9b     # or whichever model you use

Run from source (development)

npm install
npm run dev                 # same as `modai`
npm run dev -- resume       # same as `modai resume`
npm test                    # offline smoke test of the whole workflow

Configuration (env vars)

| Variable | Default | Purpose | |---|---|---| | OLLAMA_HOST | http://localhost:11434 | Your Ollama server (set this if it runs on another machine). | | MODAI_MODEL | ornith:9b | Model used by every role. | | MODAI_MODEL_<ROLE> | — | Per-role override: PM, STRATEGIST, UX, ARCHITECT, FRONTEND, BACKEND, QA. e.g. MODAI_MODEL_FRONTEND=qwen2.5-coder:14b |

Notes for small local models

The prompts are deliberately tuned for ~9B models: each agent gets one job per call, an explicit output format, and small context (specs are passed in full, code is clipped for QA). The architect is instructed to keep projects to at most 15 files and minimal dependencies — that's the size a local model can build coherently. If a phase output comes back malformed (e.g. no file-plan table), the orchestrator automatically asks that agent for a structural revision before showing it to you.

Extending

• Web UI later: the orchestrator (src/orchestrator.ts) is UI-agnostic apart from the functions in src/cli.ts (speaker, checkpoint, askClient). Swap those for websocket handlers and the same state machine drives a browser client.
• New roles: add an entry in src/team/roles.ts and call it from a phase in the orchestrator.
• Different stack defaults: edit Priya's system prompt in src/team/roles.ts.