@eventmodelers/cli 1.0.74 → 1.0.76

package/README.md

@@ -78,7 +78,8 @@ your-project/
 │   └── config.json                ← your token + org/board (gitignored) — shared by every kit in this project
 ├── .build-kit/                    ← agent runner (name is .agent-modeling-kit/ for the modeling-kit stack)
 │   ├── ralph-claude.js            ← realtime agent + task loop
-│   ├── ralph-ollama.js            ← same, via local Ollama
+│   ├── ralph-local-ai.js          ← same, via a local/self-hosted model
+│   ├── ralph-exec.js              ← same, via an external agent command (Codex CLI, OpenCode, …)
 │   ├── ralph.sh                   ← bash-only loop (no realtime)
 │   ├── lib/                       ← stack-specific agent prompts + helpers
 │   └── .slices/                   ← board slices, written by `fetch`/`listen` (or pre-seeded by `init --demo`)
@@ -92,7 +93,7 @@ The six backend stacks (`node`, `supabase`, `axon`, `opencqrs`, `umadb`, `kurren
 
 `react` and `supabase-react` are two more registered stacks (installable the same way). `supabase-react` is real, filled-in content — a Vite + React 19 + TypeScript scaffold that authenticates and issues command POSTs via a Supabase session (`src/lib/api.ts`/`src/lib/supabase.ts`), plus `init-style-guide`/`learn-styleguide` skills so generated UI stays on-brand. It's UI-only: `.build-kit/CLAUDE.md` only routes `STATE_CHANGE`/`STATE_VIEW` slices to `build-state-change`/`build-state-view` — an `AUTOMATION` slice has no UI counterpart and gets flagged via `request-feedback` instead, since it belongs to whichever backend stack is installed alongside this one. It needs no overrides at all and uses `shared/build-kit`'s realtime agent as-is.
 
-`react` (the plain-REST/board-polling variant, no Supabase) is still in the same state as a fresh `init --build-kit` scaffold — CLAUDE.md, the `build-*` skills, and `templates/root/` are all TODO-marked placeholders, not real content, pending an equivalent reference implementation. It overrides `lib/ralph.js` (+ `ralph-claude.js`/`ralph-ollama.js`/`package.json`/`README.md`) for board-polling sync. Fill in the TODOs (and add a real `templates/root/` scaffold) against an actual project before relying on it.
+`react` (the plain-REST/board-polling variant, no Supabase) is still in the same state as a fresh `init --build-kit` scaffold — CLAUDE.md, the `build-*` skills, and `templates/root/` are all TODO-marked placeholders, not real content, pending an equivalent reference implementation. It overrides `lib/ralph.js` (+ `ralph-claude.js`/`ralph-local-ai.js`/`package.json`/`README.md`) for board-polling sync. Fill in the TODOs (and add a real `templates/root/` scaffold) against an actual project before relying on it.
 
 ## Skills
 
@@ -124,7 +125,8 @@ npx @eventmodelers/cli init --stack <name>          # scaffold a stack + install
 npx @eventmodelers/cli init --stack <name> --demo   # same, plus a ready-made demo model in the kit's .slices/ to build against
 npx @eventmodelers/cli re-init                      # refresh an already-installed kit's scripts/skills only — never touches the root scaffold
 npx @eventmodelers/cli run                          # start the agent loop (ralph-claude.js) from the installed kit dir
-npx @eventmodelers/cli run --ollama                 # same, via local Ollama (ralph-ollama.js)
+npx @eventmodelers/cli run --local-ai [target]      # same, via a local/self-hosted model (ralph-local-ai.js)
+npx @eventmodelers/cli run --exec "<command>"        # same, via an external agent harness (ralph-exec.js)
 npx @eventmodelers/cli run --bash                   # bash-only loop, no realtime (ralph.sh)
 npx @eventmodelers/cli run --local                  # skip platform config/credential lookup entirely — local-only, no board sync
 npx @eventmodelers/cli run --modeling               # modeling-kit: warm Claude process driven by the board's prompt queue
@@ -335,7 +337,7 @@ npx @eventmodelers/cli bridge
 
 `init --bridge` installs a `.bridge-kit/` (mirrors `.build-kit/`'s realtime + task-queue loop) plus only the skills for the chosen `--target` (`shared/bridge/<target>/`) — a `spec-kitty` bridge never installs Kiro's skills, and vice versa. `bridge` starts the loop: on every board slice change (not just "Planned", unlike build-kit), it regenerates that framework's spec artifacts from the current board state. It doesn't build code and doesn't claim slices.
 
-For `spec-kitty`, that sync is deterministic and stops well short of writing Spec Kitty's own artifacts — `lib/adapters/spec-kitty-adapter.js` fetches full slice detail and restates it as a plain markdown mission brief (one section per slice, its scenarios verbatim, nothing invented), then calls `spec-kitty intake --force` to install it at `.kittify/mission-brief.md`. It deliberately doesn't create the mission, write `spec.md`, or author work packages — Spec Kitty's own `/spec-kitty.specify` → `/spec-kitty.plan` → `/spec-kitty.tasks` pipeline does that, because those steps need real judgment (work package boundaries, which files a WP owns, which agent profile fits) that only makes sense with actual codebase context, which this adapter doesn't have. What it replaces is Spec Kitty's *interactive discovery interview*: `/spec-kitty.specify`'s own "Brief Context Detection" step reads `.kittify/mission-brief.md` when present and extracts requirements from it instead of asking the user, so the event model — not a live Q&A — becomes the input. No LLM call happens in this adapter's own path, and `bridge` picks it automatically whenever a target has one (`--claude` forces the Claude runner instead). Targets without a static adapter yet fall back to Claude re-running `bridge-<target>-specify`; pass `--ollama` for the local-Ollama runner instead (same caveat as build-kit's `--ollama`: `lib/ollama-agent.js` is shared as-is).
+For `spec-kitty`, that sync is deterministic and stops well short of writing Spec Kitty's own artifacts — `lib/adapters/spec-kitty-adapter.js` fetches full slice detail and restates it as a plain markdown mission brief (one section per slice, its scenarios verbatim, nothing invented), then calls `spec-kitty intake --force` to install it at `.kittify/mission-brief.md`. It deliberately doesn't create the mission, write `spec.md`, or author work packages — Spec Kitty's own `/spec-kitty.specify` → `/spec-kitty.plan` → `/spec-kitty.tasks` pipeline does that, because those steps need real judgment (work package boundaries, which files a WP owns, which agent profile fits) that only makes sense with actual codebase context, which this adapter doesn't have. What it replaces is Spec Kitty's *interactive discovery interview*: `/spec-kitty.specify`'s own "Brief Context Detection" step reads `.kittify/mission-brief.md` when present and extracts requirements from it instead of asking the user, so the event model — not a live Q&A — becomes the input. No LLM call happens in this adapter's own path, and `bridge` picks it automatically whenever a target has one (`--claude` forces the Claude runner instead). Targets without a static adapter yet fall back to Claude re-running `bridge-<target>-specify`; pass `--local-ai` for the local-model runner instead (same caveat as build-kit's `--local-ai`: `lib/local-ai-agent.js` is shared as-is).
 
 Don't want the standing loop at all? `fetch` can call the same adapter for a single one-shot sync, no `.bridge-kit/` install required:
 
@@ -354,7 +356,7 @@ npx @eventmodelers/cli init --bridge --target spec-kitty --hook "git add .slices
 npx @eventmodelers/cli bridge
 ```
 
-`init --bridge --hook` persists the command to `.bridge-kit/bridge.json` — a plain, **committed** file (unlike `.eventmodelers/config.json`, which is gitignored for credentials) since the hook is project policy meant to be shared by every teammate and CI runner, not per-machine state. `bridge --hook "<command>"` overrides it for a single run without touching that file. Only one executor runs per invocation — `--ollama`, `--hook`, and `--claude` are mutually exclusive.
+`init --bridge --hook` persists the command to `.bridge-kit/bridge.json` — a plain, **committed** file (unlike `.eventmodelers/config.json`, which is gitignored for credentials) since the hook is project policy meant to be shared by every teammate and CI runner, not per-machine state. `bridge --hook "<command>"` overrides it for a single run without touching that file. Only one executor runs per invocation — `--local-ai`, `--hook`, and `--claude` are mutually exclusive.
 
 The hook command runs with `BRIDGE_TASK_COUNT`, `BRIDGE_SLICE_ID`/`_TITLE`/`_STATUS` (the most recent change in the batch), and `BRIDGE_BATCH_FILE` (path to the full batch as JSON) in its environment. It's invoked once per batch, not once per slice — any change that arrives while the hook is still running is left queued for the next batch rather than dropped.
 

package/cli.js

@@ -31,8 +31,8 @@ const __dirname = dirname(__filename);
 
 // Each stack is a template set under stacks/<key>/templates/{.claude,root,<kitSubdir>}.
 // Stacks with useShared:true also get shared/build-kit/* copied into their kit dir
-// first (ralph.js, ralph-claude.js, ralph-ollama.js, ralph.sh, realtime-agent.js,
-// code-export.mjs, lib/agent.sh, lib/ollama-agent.js, package.json, README.md) —
+// first (ralph.js, ralph-claude.js, ralph-local-ai.js, ralph-exec.js, ralph.sh, realtime-agent.js,
+// code-export.mjs, lib/agent.sh, lib/local-ai-agent.js, package.json, README.md) —
 // those files have no per-stack content, so they live once instead of being
 // copy-pasted into every stack (that copy-pasting is exactly how they drifted out
 // of sync before: a bugfix or default landing in one stack's copy but not another's).
@@ -41,6 +41,29 @@ const __dirname = dirname(__filename);
 // modeling-kit (below) is the one kit that opts out of all of this (useShared:false)
 // — it has no cold-spawn/tasks.json runtime at all, so none of shared/build-kit/*
 // applies to it; see its own templates/kit for its (much smaller) self-contained set.
+// --- Local-AI runner selection ------------------------------------------------
+// One runner drives every local/self-hosted backend. What differs between Ollama,
+// vLLM, LM Studio and llama.cpp is the wire dialect (native /api/chat vs the
+// OpenAI-compatible /v1/chat/completions) plus a default URL — both handled inside
+// lib/local-ai-agent.js. Splitting this per vendor would multiply the one file that
+// is currently shared across every stack, so these are presets, not runners.
+// Claude (ralph-claude.js) stays the default executor; this is opt-in.
+const LOCAL_AI_TARGETS = ['ollama', 'vllm', 'lmstudio', 'llamacpp'];
+
+// null = not requested. true = requested with no preset (the agent then falls back to
+// LOCAL_AI_*/config, defaulting to Ollama). A string is a validated preset name.
+function resolveLocalAiTarget(opts) {
+  const raw = opts.localAi;
+  if (raw === undefined || raw === false) return null;
+  if (raw === true) return true;
+  if (!LOCAL_AI_TARGETS.includes(raw)) {
+    console.error(`❌ Unknown --local-ai target "${raw}" — one of: ${LOCAL_AI_TARGETS.join(', ')}.`);
+    console.error('   Any other OpenAI-compatible server works by URL instead: LOCAL_AI_URL=http://host:8000/v1');
+    process.exit(1);
+  }
+  return raw;
+}
+
 const STACKS = {
   node: {
     label: 'Node.js / TypeScript',
@@ -86,7 +109,7 @@ const STACKS = {
   },
   // Frontend-only kits (UI-only: build STATE_CHANGE/STATE_VIEW slices, not
   // AUTOMATION — those belong to whichever backend stack is installed alongside).
-  // react overrides lib/ralph.js (+ralph-claude.js/ralph-ollama.js/package.json/
+  // react overrides lib/ralph.js (+ralph-claude.js/ralph-local-ai.js/package.json/
   // README.md) for board-polling instead of the realtime channel every other
   // stack uses; supabase-react needs no overrides at all — it uses
   // shared/build-kit's realtime agent as-is. react's CLAUDE.md/build-*
@@ -199,9 +222,11 @@ const MCP_MANUAL_CLIENTS = [
 // directory tells it to go read the canonical .claude/skills/<name>/SKILL.md and
 // follow it — the same pattern spec-kitty uses (verified directly against its repo,
 // not just its docs: every "stub" host below reads plain Markdown, no per-host
-// format transform needed). Codex CLI, Mistral Vibe, Pi, and Letta Code share one
-// convention that already matches our native SKILL.md format, so those get the
-// real file copied as-is instead of a stub.
+// format transform needed). Codex CLI, Mistral Vibe, Pi, Letta Code, and Hermes
+// share one convention that already matches our native SKILL.md format, so those
+// get the real file copied as-is instead of a stub. (Hermes also has a native
+// .hermes/skills/ location, but its docs list .agents/skills/ as an equally
+// first-class project skill root, so there's no reason to write the tree twice.)
 const AGENT_HOSTS = {
   cursor: { label: 'Cursor', dir: '.cursor/commands', kind: 'stub' },
   windsurf: { label: 'Windsurf', dir: '.windsurf/workflows', kind: 'stub' },
@@ -215,12 +240,33 @@ const AGENT_HOSTS = {
   augment: { label: 'Augment Code', dir: '.augment/commands', kind: 'stub' },
   antigravity: { label: 'Google Antigravity', dir: '.agent/workflows', kind: 'stub' },
   codex: {
-    label: 'Codex CLI / Mistral Vibe / Pi / Letta Code (shared .agents/skills/ convention)',
+    label: 'Codex CLI / Mistral Vibe / Pi / Letta Code / Hermes (shared .agents/skills/ convention)',
     dir: '.agents/skills',
     kind: 'skill-package',
   },
 };
 
+// Several hosts share one directory convention, so they resolve to a single
+// canonical entry above instead of each getting their own: writing the same
+// .agents/skills/ tree four times would be pure duplication, and `--hosts all`
+// would print four "installed" lines for one install. These exist so people can
+// name the agent they actually use — `--hosts pi` is a friendlier spelling of
+// `--hosts codex`, not a different install.
+const AGENT_HOST_ALIASES = {
+  pi: 'codex',
+  hermes: 'codex',
+  vibe: 'codex',
+  'mistral-vibe': 'codex',
+  letta: 'codex',
+  'letta-code': 'codex',
+};
+
+// Alias -> canonical, deduped and order-preserving. Unknown keys pass through
+// untouched so the caller keeps reporting them as unknown.
+function resolveAgentHostKeys(keys) {
+  return [...new Set(keys.map((k) => AGENT_HOST_ALIASES[k] || k))];
+}
+
 function agentHostStub(skillName) {
   return `# ${skillName} (eventmodelers)\n\nThis host should read the canonical skill at:\n\n**\`.claude/skills/${skillName}/SKILL.md\`**\n\nFollow those instructions when this command is invoked.\n`;
 }
@@ -246,15 +292,18 @@ async function configureAgentHosts({ hosts, global: useGlobal } = {}) {
   if (!hostKeys || !hostKeys.length) {
     console.log('\nAvailable agent hosts:');
     Object.entries(AGENT_HOSTS).forEach(([key, h]) => console.log(`  ${key.padEnd(12)} ${h.label}`));
+    const aliasKeys = Object.keys(AGENT_HOST_ALIASES);
+    if (aliasKeys.length) console.log(`\n  (also accepted: ${aliasKeys.join(', ')})`);
     const answer = await prompt('\nWhich hosts? (comma-separated keys, or "all"): ');
     hostKeys = answer.trim() === 'all'
       ? Object.keys(AGENT_HOSTS)
       : answer.split(',').map((s) => s.trim()).filter(Boolean);
   }
+  hostKeys = resolveAgentHostKeys(hostKeys);
 
   const unknown = hostKeys.filter((k) => !AGENT_HOSTS[k]);
   if (unknown.length) {
-    console.error(`❌ Unknown host(s): ${unknown.join(', ')}. Available: ${Object.keys(AGENT_HOSTS).join(', ')}`);
+    console.error(`❌ Unknown host(s): ${unknown.join(', ')}. Available: ${Object.keys(AGENT_HOSTS).join(', ')} (aliases: ${Object.keys(AGENT_HOST_ALIASES).join(', ')})`);
     process.exit(1);
   }
   if (!hostKeys.length) {
@@ -988,7 +1037,7 @@ async function installStack(stackKey, stackCfg, options = {}) {
     }
 
     // Make scripts executable
-    for (const script of ['ralph.sh', 'lib/agent.sh', 'ralph-claude.js', 'ralph-ollama.js']) {
+    for (const script of ['ralph.sh', 'lib/agent.sh', 'ralph-claude.js', 'ralph-local-ai.js', 'ralph-exec.js']) {
       const p = join(kitDir, script);
       if (existsSync(p)) {
         try { execSync(`chmod +x "${p}"`); } catch {}
@@ -1096,7 +1145,7 @@ async function installStack(stackKey, stackCfg, options = {}) {
     } else if (isModelingKit) {
       console.log('  npx @eventmodelers/cli run --modeling\n');
     } else {
-      console.log('  npx @eventmodelers/cli run          (--ollama or --bash for other runners)\n');
+      console.log('  npx @eventmodelers/cli run          (--local-ai or --bash for other runners)\n');
     }
     console.log('Connect this project to an MCP client (Claude Code, VS Code, ...):\n');
     console.log(`  npx @eventmodelers/cli init-mcp\n`);
@@ -2798,7 +2847,7 @@ program
 program
   .command('init-agents')
   .description(`Expose installed skills to other AI agent hosts (${Object.keys(AGENT_HOSTS).join(', ')}) as thin stub commands pointing at the canonical .claude/skills/ files — no skill content duplicated per host`)
-  .option('--hosts <list>', `Comma-separated host keys (${Object.keys(AGENT_HOSTS).join(', ')})`)
+  .option('--hosts <list>', `Comma-separated host keys (${Object.keys(AGENT_HOSTS).join(', ')}; aliases: ${Object.keys(AGENT_HOST_ALIASES).join(', ')})`)
   .option('--all', 'Expose to every known host')
   .option('--global', 'Read skills from ~/.claude/skills/ instead of the project')
   .action(async (opts) => {
@@ -3017,7 +3066,8 @@ credentialFlags(program
 credentialFlags(program
   .command('run')
   .description('Start the agent loop from the installed kit dir — build-kit stacks: ralph-claude.js (default); modeling-kit: --modeling, or --standalone, which needs no install at all')
-  .option('--ollama', 'Use ralph-ollama.js instead of the default Claude runner (build-kit stacks only)')
+  .option('--local-ai [target]', `Drive the loop with a local (or self-hosted) model instead of the default Claude runner, via ralph-local-ai.js (build-kit stacks only). Optional target preset picks the URL and wire dialect: ${LOCAL_AI_TARGETS.join(', ')} — bare --local-ai means ollama. Anything OpenAI-compatible (vLLM, LM Studio, llama.cpp, TGI) works by pointing LOCAL_AI_URL at it; see LOCAL_AI_* in the docs. Claude remains the default when this flag is absent.`)
+  .option('--exec [command]', 'Hand each prompt to an external agent command instead of the default Claude runner, via ralph-exec.js (build-kit stacks only) — for agentic harnesses that bring their own tool loop, e.g. "codex exec --full-auto" or "opencode run". The prompt is appended as a quoted argument and also written to the file named by RALPH_PROMPT_FILE. Bare --exec uses localAi.exec from .eventmodelers/config.json. Claude remains the default when this flag is absent.')
   .option('--bash', 'Use the bash-only ralph.sh loop (build-kit stacks only, no realtime)')
   .option('--modeling', 'Keep one Claude process warm across prompts instead of spawning a fresh one per task, for low-latency voice/live use. Runs from a modeling-kit install in this directory, or from the global install (~/.eventmodelers/kit) when there is none. Built into the CLI, not a per-project file.')
   .option('--standalone', 'Let the modeling agent work the board in the background, on its own initiative: on top of direct prompts it subscribes to the board\'s change channel (like the build agents do) and, whenever the board goes quiet after an edit — or has simply been idle for a while — it takes a turn nobody asked for. Changed nodes are a notification, not the task: it judges the model as a whole and fans the work out over parallel subagents, one per changed area (examples on a new node, specs for a new command or read model, a missing attribute along a chain, a screen, a question comment). Filling that detail in while the human keeps modeling is the point — it does not wait for the board to be finished. Implies --modeling.')
@@ -3071,13 +3121,13 @@ credentialFlags(program
     const bridgeKitDir = installedKitDirs.find((d) => d.endsWith(BRIDGE_KIT.kitDirName)) ?? null;
     // A bridge kit is not a build-kit stand-in even though it also reuses
     // lib/ralph.js — it has its own `eventmodelers bridge` entrypoint (no
-    // onPlannedSlice/--ollama/--bash support), so it's excluded here rather
+    // onPlannedSlice/--local-ai/--bash support), so it's excluded here rather
     // than falling through to the generic build-kit runner below.
     const buildKitDir = installedKitDirs.find((d) => d !== modelingKitDir && d !== bridgeKitDir) ?? null;
 
     // No overlap between the two stacks' runtimes: modeling-kit only ever runs the
     // warm, direct-dispatch loop (--modeling); build-kit only ever runs the
-    // cold-spawn/tasks.json loop (default, or --ollama/--bash). Neither falls back
+    // cold-spawn/tasks.json loop (default, or --local-ai/--bash). Neither falls back
     // to the other's mechanism, so each side is gated explicitly below rather than
     // just being left to fail on a missing file.
     // --standalone implies --modeling: it already refused every other runner, so there
@@ -3086,8 +3136,8 @@ credentialFlags(program
     // no meaning for a build kit, which is scaffolded per project by definition.
     if (opts.modeling || opts.standalone || opts.global) {
       const picked = opts.modeling ? '--modeling' : opts.standalone ? '--standalone' : '--global';
-      if (opts.bash || opts.ollama) {
-        console.error(`❌ ${picked} is mutually exclusive with --bash/--ollama — those select a build-kit runner, which the modeling loop has no use for.`);
+      if (opts.bash || opts.localAi || opts.exec) {
+        console.error(`❌ ${picked} is mutually exclusive with --bash/--local-ai/--exec — those select a build-kit runner, which the modeling loop has no use for.`);
         process.exit(1);
       }
       if (opts.local) {
@@ -3136,7 +3186,7 @@ credentialFlags(program
       if (modelingKitDir) {
         console.error(`❌ A modeling-kit install (${MODELING_KIT.kitDirName}/) only runs via \`eventmodelers run --modeling\` — there is no cold-spawn/tasks.json loop for modeling-only projects.`);
       } else if (bridgeKitDir) {
-        console.error(`❌ A bridge-kit install (${BRIDGE_KIT.kitDirName}/) only runs via \`eventmodelers bridge\` — it has no --modeling/--ollama/--bash modes.`);
+        console.error(`❌ A bridge-kit install (${BRIDGE_KIT.kitDirName}/) only runs via \`eventmodelers bridge\` — it has no --modeling/--local-ai/--bash modes.`);
       } else {
         console.error(`❌ No kit installed in ${cwd} — run \`eventmodelers install\` first.`);
         console.error('   (A modeling agent needs no install at all: eventmodelers run --standalone --board-id <uuid>)');
@@ -3145,9 +3195,10 @@ credentialFlags(program
     }
     const kitDir = buildKitDir;
 
-    const pickedCount = [opts.bash, opts.ollama].filter(Boolean).length;
+    const localAiTarget = resolveLocalAiTarget(opts);
+    const pickedCount = [opts.bash, localAiTarget !== null, !!opts.exec].filter(Boolean).length;
     if (pickedCount > 1) {
-      console.error('❌ --bash and --ollama are mutually exclusive — pick one.');
+      console.error('❌ --bash, --local-ai and --exec are mutually exclusive — pick one runner.');
       process.exit(1);
     }
 
@@ -3155,7 +3206,7 @@ credentialFlags(program
     // is just a thin dispatcher so users don't have to remember the kit-dir name or which
     // runner file to invoke. Users (and the agent itself, via AGENT.md) may customize these
     // files freely; `run` always executes whatever is currently on disk.
-    const runner = opts.bash ? 'ralph.sh' : opts.ollama ? 'ralph-ollama.js' : 'ralph-claude.js';
+    const runner = opts.bash ? 'ralph.sh' : opts.exec ? 'ralph-exec.js' : localAiTarget !== null ? 'ralph-local-ai.js' : 'ralph-claude.js';
     const runnerPath = join(kitDir, runner);
     if (!existsSync(runnerPath)) {
       console.error(`❌ ${relative(cwd, runnerPath)} not found.`);
@@ -3165,13 +3216,13 @@ credentialFlags(program
     console.log(`▶ Starting ${relative(cwd, runnerPath)}...\n`);
     const cmd = runner.endsWith('.sh') ? `"${runnerPath}"` : `node "${runnerPath}"`;
     try {
-      // Only ralph-claude.js reads RALPH_VERBOSE — the bash loop and the ollama executor have
+      // Only ralph-claude.js reads RALPH_VERBOSE — the bash loop and the local-AI executor have
       // their own separate output paths with no stream-json parsing to gate. RALPH_LOCAL is
       // read by all three runners (ralph.js's startRalph, and ralph.sh directly) to force the
       // local-only branch even when .eventmodelers/config.json has valid credentials.
       // RALPH_AGENT_ID/RALPH_AGENT_NAME (--id/--name) are read in ralph.js's startRalph, so
       // they reach both node runners but not ralph.sh, which has no heartbeat to identify.
-      execSync(cmd, { cwd: kitDir, stdio: 'inherit', env: { ...process.env, RALPH_VERBOSE: opts.verbose ? '1' : '', RALPH_LOCAL: opts.local ? '1' : '', RALPH_AGENT_ID: identity.agentId ?? '', RALPH_AGENT_NAME: identity.agentName ?? '' } });
+      execSync(cmd, { cwd: kitDir, stdio: 'inherit', env: { ...process.env, RALPH_VERBOSE: opts.verbose ? '1' : '', RALPH_LOCAL: opts.local ? '1' : '', RALPH_AGENT_ID: identity.agentId ?? '', RALPH_AGENT_NAME: identity.agentName ?? '', ...(typeof localAiTarget === 'string' ? { LOCAL_AI_TARGET: localAiTarget } : {}), ...(typeof opts.exec === 'string' ? { RALPH_EXEC_CMD: opts.exec } : {}) } });
     } catch (err) {
       process.exit(err.status || 1);
     }
@@ -3179,8 +3230,8 @@ credentialFlags(program
 
 program
   .command('bridge')
-  .description('Start the bridge agent loop from the installed .bridge-kit/ — translates board slice changes into another spec framework instead of building code. A deterministic adapter runs with no LLM call if one exists for the configured target (e.g. spec-kitty); otherwise Claude is the default executor. --ollama, --hook, or --claude override the pick.')
-  .option('--ollama', 'Use ralph-ollama.js instead of the default runner')
+  .description('Start the bridge agent loop from the installed .bridge-kit/ — translates board slice changes into another spec framework instead of building code. A deterministic adapter runs with no LLM call if one exists for the configured target (e.g. spec-kitty); otherwise Claude is the default executor. --local-ai, --hook, or --claude override the pick.')
+  .option('--local-ai [target]', `Use ralph-local-ai.js instead of the default runner — a local or self-hosted model. Optional target preset: ${LOCAL_AI_TARGETS.join(', ')} (bare flag means ollama).`)
   .option('--hook <command>', 'Run this shell command instead of an AI agent for each batch of slice changes (e.g. commit + push .slices/ for a CI pipeline to pick up) — overrides any hook persisted via `init --bridge --hook` for this run only')
   .option('--claude', 'Force the Claude runner even if a static adapter exists for this target')
   .action((opts) => {
@@ -3191,8 +3242,9 @@ program
       process.exit(1);
     }
 
-    if ([opts.ollama, opts.hook, opts.claude].filter(Boolean).length > 1) {
-      console.error('❌ --ollama, --hook, and --claude are mutually exclusive — pick one executor.');
+    const localAiTarget = resolveLocalAiTarget(opts);
+    if ([localAiTarget !== null, opts.hook, opts.claude].filter(Boolean).length > 1) {
+      console.error('❌ --local-ai, --hook, and --claude are mutually exclusive — pick one executor.');
       process.exit(1);
     }
 
@@ -3212,8 +3264,8 @@ program
 
     const runner = hookCmd
       ? 'ralph-hook.js'
-      : opts.ollama
-        ? 'ralph-ollama.js'
+      : localAiTarget !== null
+        ? 'ralph-local-ai.js'
         : !opts.claude && hasStaticAdapter
           ? 'ralph-static.js'
           : 'ralph-claude.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eventmodelers/cli",
-  "version": "1.0.74",
+  "version": "1.0.76",
   "description": "Eventmodelers CLI — real-time Claude agent + skills for Claude Code, for any stack (Node, Supabase, Axon, OpenCQRS, UmaDB, Kurrent, or modeling-only)",
   "type": "module",
   "bin": {

package/shared/build-kit/README.md

@@ -8,8 +8,11 @@ Ralph's runtime directory. Contains the agent loop, realtime subscription, promp
 # Claude (default)
 node .build-kit/ralph-claude.js
 
-# Local Ollama model — run `ollama serve` first
-OLLAMA_MODEL=qwen3.5:9b node .build-kit/ralph-ollama.js
+# Local or self-hosted model — Ollama (run `ollama serve` first)
+LOCAL_AI_TARGET=ollama node .build-kit/ralph-local-ai.js
+
+# …or any OpenAI-compatible server (vLLM, LM Studio, llama.cpp, TGI)
+LOCAL_AI_TARGET=vllm LOCAL_AI_MODEL=Qwen/Qwen3-8B node .build-kit/ralph-local-ai.js
 
 # Custom project directory (defaults to the parent of .build-kit)
 node .build-kit/ralph-claude.js /path/to/project
@@ -22,7 +25,8 @@ node .build-kit/ralph-claude.js /path/to/project
 | File | Purpose |
 |------|---------|
 | `ralph-claude.js` | Runs the full loop using Claude Code as the executor |
-| `ralph-ollama.js` | Runs the full loop using a local Ollama model |
+| `ralph-local-ai.js` | Runs the full loop using a local/self-hosted model (Ollama, vLLM, LM Studio, llama.cpp) |
+| `ralph-exec.js` | Runs the full loop handing each prompt to an external agent command (Codex CLI, OpenCode, …) |
 | `ralph.sh` | Shell-based loop — alternative to the JS entry points |
 | `realtime-agent.js` | Standalone realtime agent — only needed to run it in a separate terminal |
 
@@ -31,7 +35,7 @@ node .build-kit/ralph-claude.js /path/to/project
 | File | Purpose |
 |------|---------|
 | `lib/ralph.js` | Shared library — realtime agent + loop logic; imported by the entry points |
-| `lib/ollama-agent.js` | Ollama executor — called by `ralph-ollama.js`, can also run manually |
+| `lib/local-ai-agent.js` | Local-AI executor — called by `ralph-local-ai.js`, can also run manually |
 | `lib/agent.sh` | Thin shell wrapper around `claude` — called by `ralph.sh` |
 | `lib/prompt.md` | Phase 1 prompt: tells Claude how to load a slice from the board |
 | `lib/backend-prompt.md` | Phase 2 prompt: tells Claude how to build a planned slice |
@@ -41,13 +45,13 @@ node .build-kit/ralph-claude.js /path/to/project
 
 **Phase 1** — triggered when `tasks.json` has entries:
 - The realtime agent writes a task to `tasks.json` each time a `slice:changed` event arrives from the board
-- The loop picks it up and runs Claude (or Ollama) with `prompt.md`
+- The loop picks it up and runs Claude (or a local model) with `prompt.md`
 - Claude loads the slice data and updates `.slices/`
 
 **Phase 2** — triggered when any file in `.slices/` contains `"status": "Planned"`:
 - The loop runs Claude with `backend-prompt.md`
 - Claude implements the slice in the project
-- Phase 2 is Claude-only; Ollama mode skips it (ollama-agent handles its own queue)
+- Phase 2 is Claude-only; local-AI mode skips it (local-ai-agent handles its own queue)
 
 Both phases run in a continuous loop with a 3-second idle sleep. The realtime agent runs concurrently in the same process.
 
@@ -63,13 +67,64 @@ node .build-kit/realtime-agent.js
 .build-kit/ralph.sh
 ```
 
-## Ollama configuration
+## Local-AI configuration
+
+`ralph-local-ai.js` drives any local or self-hosted model that can do tool calling.
+Claude (`ralph-claude.js`) stays the default runner — this is opt-in.
+
+```bash
+LOCAL_AI_TARGET=ollama          # preset: ollama | vllm | lmstudio | llamacpp
+LOCAL_AI_URL=http://host:8000/v1  # any OpenAI-compatible server (overrides the preset URL)
+LOCAL_AI_MODEL=qwen3.5:9b       # model name as the server knows it
+LOCAL_AI_API=openai             # force the wire dialect: ollama | openai (normally inferred)
+LOCAL_AI_API_KEY=local          # sent as `Authorization: Bearer` on the openai dialect
+LOCAL_AI_NUM_CTX=32768          # ollama only — context window (default 32768)
+```
+
+**Do not lower `LOCAL_AI_NUM_CTX`.** The MCP tool schemas are ~16k tokens on their own.
+Ollama's own default is 4096, which silently truncates them — the model then sees a
+fragment of the tool list and invents tool names instead of failing, which is why the
+default here is raised rather than left to the server. On the `openai` dialect the
+equivalent is set when you launch the server (vLLM `--max-model-len 32768`,
+llama.cpp `-c 32768`); an overflow there surfaces as an HTTP 400.
+
+
+## External agent commands (`--exec`)
+
+Agentic harnesses that bring their own tool loop — Codex CLI, OpenCode, Gemini CLI —
+are not `--local-ai` targets: `--local-ai` *supplies* the agent loop, while a harness
+already is one and only wants a prompt. They go through `ralph-exec.js` instead:
 
 ```bash
-OLLAMA_MODEL=qwen3.5:9b         # model to use (default: qwen3.5:9b)
-OLLAMA_URL=http://host:11434   # Ollama server URL (default: http://localhost:11434)
+npx @eventmodelers/cli run --exec "codex exec --full-auto"
+npx @eventmodelers/cli run --exec "opencode run"
+
+# …or persist it and use the bare flag
+RALPH_EXEC_CMD="codex exec --full-auto" node .build-kit/ralph-exec.js
 ```
 
+The prompt is appended to the command as one shell-quoted argument, and is also written
+to a temp file named by `RALPH_PROMPT_FILE` for commands that prefer to read it. The
+child runs with the project dir as its cwd and inherits stdio — a harness owns its own
+output format, so there is no condensed per-step logging here the way `ralph-claude.js`
+has it.
+
+Persist a default alongside the local-AI settings:
+
+```json
+{
+  "localAi": {
+    "exec": "codex exec --full-auto"
+  }
+}
+```
+
+One caveat worth knowing before reaching for this: the kits' prompts assume Claude
+Code's `Skill` tool and `CLAUDE.md`. Other harnesses read `AGENTS.md` and have no skill
+primitive, so `init-agents` puts the skill files where they can find them, but
+`lib/prompt.md` / `lib/backend-prompt.md` still need wording that says *read and follow*
+a skill file rather than *invoke* it.
+
 ## Config
 
 Credentials are stored in `.build-kit/.eventmodelers/config.json` (written by `eventmodelers init`):