create-oma-app 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 open-multi-agent contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,42 @@
+# create-oma-app
+
+Scaffold a runnable multi-agent demo on [`@open-multi-agent/core`](https://www.npmjs.com/package/@open-multi-agent/core) — one command from zero to a live agent DAG.
+
+```bash
+npm create oma-app@latest
+```
+
+Answer one prompt (the project name) and you get a small project that, on its first run, shows a **coordinator breaking a single goal into a multi-agent DAG** — agents running in parallel and in dependency order — then opens a dashboard of the run in your browser.
+
+## What you get
+
+```
+my-demo/
+├── src/index.ts     # the demo: one goal → multi-agent DAG → dashboard
+├── .env.example     # OpenAI, or any OpenAI-compatible provider
+├── package.json     # one runtime dependency: @open-multi-agent/core
+├── tsconfig.json
+└── README.md
+```
+
+- **One runtime dependency** — `@open-multi-agent/core`; `tsx` is the only dev dependency.
+- **Provider-neutral** — OpenAI out of the box, or any OpenAI-compatible endpoint (DeepSeek, Groq, Ollama, …) via `OPENAI_BASE_URL` + `OMA_MODEL`.
+- **No tools, no filesystem writes** — the default demo is pure reasoning, so the first run is fast and robust across providers.
+
+## Run it
+
+```bash
+npm create oma-app@latest my-demo
+cd my-demo
+npm install
+cp .env.example .env   # add your key
+npm run dev
+```
+
+## Next steps
+
+Open `src/index.ts` and change the goal, add an agent, or give an agent tools. See the [examples](https://github.com/open-multi-agent/open-multi-agent/tree/main/packages/core/examples) for tool use, MCP, structured output, and providers.
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/**
+ * create-oma-app — scaffold a runnable multi-agent demo on @open-multi-agent/core.
+ *
+ * Usage:
+ *   npm create oma-app@latest [project-name]
+ *
+ * One command from zero to a live coordinator-driven agent DAG. The copy logic
+ * lives in scaffold.ts; this file is the interactive CLI. Zero runtime
+ * dependencies — Node.js built-ins only, so `npm create oma-app` stays a fast,
+ * clean one-shot whose own deps never reach the generated project or core.
+ */
+import { basename, resolve } from 'node:path';
+import { createInterface } from 'node:readline';
+import { isNonEmptyDir, scaffold } from './scaffold.js';
+// Minimal ANSI styling — no dependency.
+const ESC = {
+    reset: '\x1b[0m',
+    bold: '\x1b[1m',
+    dim: '\x1b[2m',
+    cyan: '\x1b[36m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    red: '\x1b[31m',
+};
+const bold = (s) => `${ESC.bold}${s}${ESC.reset}`;
+const dim = (s) => `${ESC.dim}${s}${ESC.reset}`;
+const cyan = (s) => `${ESC.cyan}${s}${ESC.reset}`;
+const green = (s) => `${ESC.green}${s}${ESC.reset}`;
+function prompt(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((res) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            res(answer.trim());
+        });
+    });
+}
+async function main() {
+    console.log();
+    console.log(`  ${bold('create-oma-app')}${dim(' — scaffold a multi-agent demo')}`);
+    console.log();
+    // 1. Resolve the project directory name (argv, else one prompt).
+    let projectName = process.argv[2];
+    if (!projectName)
+        projectName = await prompt(`  Project name: ${dim('(oma-demo)')} `);
+    projectName = (projectName || 'oma-demo').trim();
+    const dirName = basename(projectName);
+    const targetDir = resolve(process.cwd(), projectName);
+    // 2. Refuse to overwrite a non-empty directory without confirmation.
+    if (isNonEmptyDir(targetDir)) {
+        console.log();
+        console.log(`  ${ESC.yellow}!${ESC.reset} ${bold(dirName)} already exists and is not empty.`);
+        const answer = (await prompt(`  Write into it anyway? ${dim('(y/N)')} `)).toLowerCase();
+        if (answer !== 'y' && answer !== 'yes') {
+            console.log(`  ${ESC.red}✗${ESC.reset} Aborted.`);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    // 3. Scaffold. Use the basename for the package name so a path-y project
+    //    name (e.g. ./apps/my-demo) still yields a clean npm name.
+    scaffold({ targetDir, projectName: dirName });
+    // 4. Next steps.
+    console.log();
+    console.log(`  ${green('✓')} Created ${bold(dirName)}`);
+    console.log();
+    console.log('  Next steps:');
+    console.log();
+    console.log(`    ${cyan(`cd ${projectName}`)}`);
+    console.log(`    ${cyan('npm install')}`);
+    console.log(`    ${cyan('cp .env.example .env')}   ${dim('# then add your API key')}`);
+    console.log(`    ${cyan('npm run dev')}`);
+    console.log();
+    console.log(dim('  One goal becomes a multi-agent DAG, then a dashboard of the run'));
+    console.log(dim('  opens in your browser. OpenAI or any OpenAI-compatible endpoint'));
+    console.log(dim('  (DeepSeek, Groq, Ollama, …) — see .env.example.'));
+    console.log();
+}
+main().catch((err) => {
+    console.error(err);
+    process.exitCode = 1;
+});

package/dist/scaffold.js

@@ -0,0 +1,41 @@
+/**
+ * create-oma-app scaffold core — copy the bundled template into a target directory,
+ * restore the shipped dotfiles, and stamp the project name. No console output,
+ * no prompts: the CLI in index.ts handles interaction so this stays testable.
+ */
+import { cpSync, existsSync, readdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** template/ ships alongside dist/ (and src/) one level under the package root. */
+export const TEMPLATE_DIR = fileURLToPath(new URL('../template', import.meta.url));
+/** Turn an arbitrary project name into a valid npm package name. */
+export function toPackageName(input) {
+    return (input
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9-~]+/g, '-')
+        .replace(/^-+|-+$/g, '') || 'oma-demo');
+}
+/** True when `dir` exists and contains at least one entry. */
+export function isNonEmptyDir(dir) {
+    return existsSync(dir) && readdirSync(dir).length > 0;
+}
+/** Copy the template into `targetDir`, restore dotfiles, stamp the name. */
+export function scaffold({ targetDir, projectName, templateDir = TEMPLATE_DIR }) {
+    cpSync(templateDir, targetDir, { recursive: true });
+    restoreDotfile(targetDir, '_gitignore', '.gitignore');
+    restoreDotfile(targetDir, '_env.example', '.env.example');
+    const pkgPath = join(targetDir, 'package.json');
+    const stamped = readFileSync(pkgPath, 'utf8').replace(/__PROJECT_NAME__/g, toPackageName(projectName));
+    writeFileSync(pkgPath, stamped);
+}
+/**
+ * Restore a shipped dotfile. npm strips/renames real dotfiles (notably
+ * `.gitignore`) on publish, so the template ships them as `_gitignore` /
+ * `_env.example` and we rename them on scaffold.
+ */
+function restoreDotfile(dir, from, to) {
+    const fromPath = join(dir, from);
+    if (existsSync(fromPath))
+        renameSync(fromPath, join(dir, to));
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "create-oma-app",
+  "version": "0.1.0",
+  "description": "Scaffold a runnable multi-agent demo on @open-multi-agent/core — one command from zero to a live agent DAG.",
+  "type": "module",
+  "bin": {
+    "create-oma-app": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "template",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "lint": "tsc --noEmit",
+    "typecheck:template": "tsc -p template/tsconfig.json",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "open-multi-agent",
+    "multi-agent",
+    "scaffold",
+    "create",
+    "starter",
+    "ai",
+    "agent"
+  ],
+  "author": {
+    "name": "open-multi-agent",
+    "url": "https://github.com/open-multi-agent"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/open-multi-agent/open-multi-agent.git",
+    "directory": "packages/create-oma-app"
+  },
+  "homepage": "https://github.com/open-multi-agent/open-multi-agent/tree/main/packages/create-oma-app#readme",
+  "bugs": {
+    "url": "https://github.com/open-multi-agent/open-multi-agent/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}

package/template/README.md

@@ -0,0 +1,27 @@
+# Multi-agent demo
+
+Built on [`@open-multi-agent/core`](https://www.npmjs.com/package/@open-multi-agent/core), scaffolded with `npm create oma-app`.
+
+## Run
+
+```bash
+npm install
+cp .env.example .env   # add your API key
+npm run dev
+```
+
+You'll see a **coordinator** break one goal into a task DAG, several agents run in parallel and in dependency order, and a **dashboard** of the run open in your browser (`dashboard.html`).
+
+Works with OpenAI out of the box, or any OpenAI-compatible provider — set `OPENAI_BASE_URL` + `OMA_MODEL` in `.env` (DeepSeek, Groq, Ollama, …). See `.env.example`.
+
+## What's next
+
+Everything lives in [`src/index.ts`](src/index.ts):
+
+- **Change the goal** — swap the goal string for your own multi-step task.
+- **Add an agent** — add an `AgentConfig` to the team roster; the coordinator routes work to it.
+- **Give agents tools** — add e.g. `tools: ['file_read', 'file_write', 'bash']` to an agent so it can read/write files, run commands, or call MCP servers.
+
+More patterns (tool use, MCP, structured output, providers) are in the [examples](https://github.com/open-multi-agent/open-multi-agent/tree/main/packages/core/examples).
+
+> Tip: for full editor type-checking, `npm i -D @types/node`. Not needed to run.

package/template/_env.example

@@ -0,0 +1,22 @@
+# Set ONE provider. The demo uses an OpenAI-compatible client.
+
+# --- OpenAI (default) -------------------------------------------------------
+OPENAI_API_KEY=sk-...
+
+# --- Or any OpenAI-compatible endpoint --------------------------------------
+# Set OPENAI_BASE_URL at the provider and OMA_MODEL to one of its models.
+#
+# DeepSeek:
+#   OPENAI_API_KEY=sk-...
+#   OPENAI_BASE_URL=https://api.deepseek.com
+#   OMA_MODEL=deepseek-chat
+#
+# Groq:
+#   OPENAI_API_KEY=gsk_...
+#   OPENAI_BASE_URL=https://api.groq.com/openai/v1
+#   OMA_MODEL=llama-3.3-70b-versatile
+#
+# Ollama (local, no cloud key — any non-empty value works):
+#   OPENAI_API_KEY=ollama
+#   OPENAI_BASE_URL=http://localhost:11434/v1
+#   OMA_MODEL=llama3.2

package/template/_gitignore

@@ -0,0 +1,4 @@
+node_modules/
+.env
+dashboard.html
+.agent-workspace/

package/template/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "@open-multi-agent/core": "1.7.0"
+  },
+  "devDependencies": {
+    "tsx": "^4.21.0"
+  }
+}

package/template/src/index.ts

@@ -0,0 +1,178 @@
+/**
+ * Multi-agent demo — one goal, automatically decomposed into a task DAG.
+ *
+ * The OpenMultiAgent coordinator reads the goal below, breaks it into tasks,
+ * assigns them to the right agents, and runs them in parallel and in dependency
+ * order. When the run finishes, a dashboard of the DAG opens in your browser.
+ *
+ * These agents use NO tools — pure reasoning — so the first run is fast and
+ * works on any OpenAI-compatible model. To watch agents use tools (read/write
+ * files, run commands, call MCP servers), give an agent a `tools` array; see
+ * the examples linked in the README.
+ *
+ * Run:  npm run dev
+ */
+import { spawn } from 'node:child_process'
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { OpenMultiAgent, renderTeamRunDashboard } from '@open-multi-agent/core'
+import type { AgentConfig, OrchestratorEvent } from '@open-multi-agent/core'
+
+// --- Minimal .env loader ----------------------------------------------------
+// Reads .env into process.env so `npm run dev` works right after
+// `cp .env.example .env`. Inlined to keep the project at ONE runtime
+// dependency (no dotenv). Existing env vars win.
+function loadEnv(path = '.env'): void {
+  if (!existsSync(path)) return
+  for (const raw of readFileSync(path, 'utf8').split('\n')) {
+    const line = raw.trim()
+    if (!line || line.startsWith('#')) continue
+    const eq = line.indexOf('=')
+    if (eq === -1) continue
+    const key = line.slice(0, eq).trim()
+    const val = line.slice(eq + 1).trim().replace(/^["']|["']$/g, '')
+    if (key && !(key in process.env)) process.env[key] = val
+  }
+}
+loadEnv()
+
+// --- Provider (OpenAI-compatible, env-driven) -------------------------------
+// OPENAI_API_KEY is read automatically by the OpenAI client. For another
+// provider, set OPENAI_BASE_URL + OMA_MODEL in .env (DeepSeek, Groq, Ollama…).
+const model = process.env.OMA_MODEL ?? 'gpt-5.4'
+
+if (!process.env.OPENAI_API_KEY) {
+  console.error(
+    '\n  Missing OPENAI_API_KEY.\n\n' +
+      '  1. cp .env.example .env\n' +
+      '  2. add a key — OpenAI, or any OpenAI-compatible provider\n' +
+      '     (DeepSeek, Groq, Ollama, …; see .env.example)\n',
+  )
+  process.exit(1)
+}
+
+// --- The team: four specialists, no tools, pure reasoning -------------------
+const strategist: AgentConfig = {
+  name: 'strategist',
+  model,
+  systemPrompt: `You define sharp, outcome-focused goals.
+Given a brief, name the few outcomes that matter most. Concrete bullet points, no filler.`,
+  maxTurns: 1,
+  temperature: 0.3,
+}
+
+const planner: AgentConfig = {
+  name: 'planner',
+  model,
+  systemPrompt: `You turn outcomes into a concrete, time-boxed plan.
+Produce clear weekly milestones — each a short, checkable line. No filler.`,
+  maxTurns: 1,
+  temperature: 0.2,
+}
+
+const riskAnalyst: AgentConfig = {
+  name: 'risk-analyst',
+  model,
+  systemPrompt: `You stress-test plans.
+Name the few highest-impact risks and give one concrete, specific mitigation for each.`,
+  maxTurns: 1,
+  temperature: 0.4,
+}
+
+const synthesizer: AgentConfig = {
+  name: 'synthesizer',
+  model,
+  systemPrompt: `You assemble the team's work into one clean deliverable.
+Merge the outcomes, weekly plan, and risk mitigations into a single concise document
+a manager could hand over directly. Use short markdown headings.`,
+  maxTurns: 1,
+  temperature: 0.2,
+}
+
+// --- Live progress: watch the DAG run ---------------------------------------
+function onProgress(event: OrchestratorEvent): void {
+  switch (event.type) {
+    case 'task_start':
+      if (event.agent) console.log(`  ▶ ${event.agent} working…`)
+      break
+    case 'task_complete':
+      if (event.agent) console.log(`  ✓ ${event.agent} done`)
+      break
+    case 'error':
+      console.error(`  ✗ ${event.agent ?? 'run'} failed`)
+      break
+  }
+}
+
+/** Best-effort open in the default browser; prints the path if it can't. */
+function openInBrowser(file: string): void {
+  // pathToFileURL handles drive letters, slashes, and spaces on every OS —
+  // a hand-built `file://` string breaks on Windows paths.
+  const url = pathToFileURL(resolve(file)).href
+  const fallback = (): void => console.log(`  Open it manually: ${url}`)
+  try {
+    // On Windows the opener is cmd's `start`, whose first quoted arg is the
+    // window title — pass an empty title ("") so the URL isn't swallowed.
+    const child =
+      process.platform === 'win32'
+        ? spawn('cmd', ['/c', 'start', '', url], { stdio: 'ignore', detached: true })
+        : spawn(process.platform === 'darwin' ? 'open' : 'xdg-open', [url], { stdio: 'ignore', detached: true })
+    child.on('error', fallback)
+    child.unref()
+  } catch {
+    fallback()
+  }
+}
+
+const orchestrator = new OpenMultiAgent({
+  defaultProvider: 'openai',
+  defaultModel: model,
+  defaultBaseURL: process.env.OPENAI_BASE_URL, // unset = OpenAI
+  onProgress,
+})
+
+const team = orchestrator.createTeam('demo-team', {
+  name: 'demo-team',
+  agents: [strategist, planner, riskAnalyst, synthesizer],
+  sharedMemory: true,
+})
+
+// --- The goal: multi-step, so the coordinator MUST decompose it -------------
+// Kept well over 200 characters so it never hits the single-agent
+// short-circuit — that is what guarantees you see a multi-agent DAG, not one
+// agent. (create-oma-app's tests assert this length.)
+const goal = `Design a 30-day onboarding plan for a software engineer joining a fast-moving startup.
+Step 1: identify the 4 outcomes the new hire should reach by day 30.
+Step 2: turn those outcomes into concrete weekly milestones for weeks 1 through 4.
+Step 3: list the 3 risks most likely to derail onboarding, each with a specific mitigation.
+Step 4: synthesize everything into one concise plan a manager could hand over on day one.`
+
+console.log(`\n  Goal: ${goal.split('\n')[0]}\n`)
+console.log('  The coordinator is decomposing the goal into a task DAG:\n')
+
+const result = await orchestrator.runTeam(team, goal)
+
+// --- Summary: the DAG the coordinator built from one goal -------------------
+const line = '─'.repeat(52)
+console.log(`\n  ${line}`)
+console.log(`  Run complete — success: ${result.success}`)
+console.log(`  Tokens: ${result.totalTokenUsage.input_tokens} in / ${result.totalTokenUsage.output_tokens} out`)
+console.log('\n  Task DAG (auto-decomposed — you wrote none of this wiring):')
+for (const task of result.tasks ?? []) {
+  console.log(`    • ${task.title}  [${task.assignee ?? '—'}] ${task.status}`)
+}
+
+// --- Final plan: the synthesizer merged the team's work into one document ---
+const plan = result.agentResults.get('synthesizer')
+if (plan?.success && plan.output.trim()) {
+  console.log(`\n  Final plan (by synthesizer):\n  ${line}`)
+  console.log(plan.output)
+}
+
+// --- Dashboard: render the DAG and open it ----------------------------------
+const dashboardPath = 'dashboard.html'
+writeFileSync(dashboardPath, renderTeamRunDashboard(result))
+console.log(`\n  ${line}`)
+console.log(`  DAG dashboard → ${dashboardPath} (opening in your browser…)`)
+openInBrowser(dashboardPath)

package/template/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src"]
+}