create-merlin-brain 3.22.0 → 4.0.0

package/README.md

@@ -1,4 +1,4 @@
-# Merlin - The Ultimate AI Brain for Claude Code
+# Merlin - The Ultimate AI Brain for Claude Code and Codex
 
 ```
   ███╗   ███╗███████╗██████╗ ██╗     ██╗███╗   ██╗
@@ -9,7 +9,7 @@
   ╚═╝     ╚═╝╚══════╝╚═╝  ╚═╝╚══════╝╚═╝╚═╝  ╚═══╝
 ```
 
-Merlin is a complete AI-powered development system for Claude Code with three integrated layers:
+Merlin is a complete AI-powered development system for Claude Code, Codex, and other CLI runtimes with three integrated layers:
 
 - **Merlin Sights** - Knowledge layer (instant codebase context)
 - **Merlin Workflows** - Planning & execution (`/merlin:*` commands)
@@ -21,6 +21,12 @@ Merlin is a complete AI-powered development system for Claude Code with three in
 npx create-merlin-brain
 ```
 
+### Runtime Support
+
+- Claude Code: full Merlin install with workflows, agents, hooks, statusline, and shell integration
+- Codex: Merlin MCP, `AGENTS.md`, Codex hooks, custom Codex agents, repo skills, and project `.codex` config
+- OpenCode / Gemini CLI: Merlin MCP plus instruction-file integration
+
 ## What You Get
 
 ### Workflows (`/merlin:*` commands)
@@ -88,10 +94,10 @@ Merlin Sights provides instant codebase context across sessions. Get your API ke
    npx create-merlin-brain
    ```
 
-2. Open Claude Code in any project
+2. Open Claude Code or Codex in any project
 
 3. Run your first command:
-   ```
+   ```text
    /merlin:map-codebase
    ```
 
@@ -100,6 +106,34 @@ Merlin Sights provides instant codebase context across sessions. Get your API ke
    /merlin:new-project
    ```
 
+## Codex Experience
+
+On Codex, Merlin now installs beyond basic MCP connectivity:
+
+- Global `~/.codex/config.toml` MCP wiring for Merlin
+- Global `~/.codex/hooks.json` for startup, prompt routing, command guardrails, and session wrap-up
+- Project `.codex/agents/` with Merlin specialist agents
+- Project `.agents/skills/` with Merlin workflow skills
+- Project `AGENTS.md` and `.codex/config.toml` for repo-local guidance
+- Merlin capability discovery via `merlin_help`
+- Automatic steering toward `merlin_smart_route`, `merlin_recommend_for_task`, and `merlin_find_skill` when Codex sees feature, bug, or resume-style prompts
+
+Codex does not currently expose a documented extension point for replacing app-shell chrome or adding a custom sidebar icon, so Merlin parity is implemented on the supported surfaces Codex actually provides.
+
+Typical Codex prompts:
+
+```text
+Use Merlin to map this codebase before changing anything.
+```
+
+```text
+Use Merlin to find the best skill, agent, and workflow for this task: add OAuth login.
+```
+
+```text
+Call merlin_help for this task: debug the failing Stripe webhook tests.
+```
+
 ## Documentation
 
 Visit [merlin.build/docs](https://merlin.build/docs) for full documentation.

package/bin/merlin-ask.cjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+
+/**
+ * merlin-ask — Delegate a prompt to an external AI CLI provider
+ *
+ * Usage:
+ *   merlin-ask claude  "review this code for bugs"
+ *   merlin-ask codex   "add error handling to the payment module"
+ *   merlin-ask gemini  "suggest performance improvements"
+ */
+
+'use strict';
+
+const { spawn, execFileSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const ARTIFACTS_DIR = path.join(os.homedir(), '.merlin', 'artifacts', 'ask');
+
+const COMMANDS = {
+  claude: (p) => ['claude', ['-p', p, '--output-format', 'text']],
+  codex:  (p) => ['codex',  ['exec', p]],
+  gemini: (p) => ['gemini', ['-p', p]],
+};
+
+// ── Args + validation ─────────────────────────────────────────────────────────
+
+const provider = process.argv[2];
+const prompt   = process.argv[3];
+
+if (!provider || !prompt) {
+  console.error('Usage: merlin-ask <claude|codex|gemini> "<prompt>"');
+  process.exit(1);
+}
+
+if (!COMMANDS[provider]) {
+  console.error(`Unknown provider: "${provider}". Valid: ${Object.keys(COMMANDS).join(', ')}`);
+  process.exit(1);
+}
+
+try {
+  execFileSync('which', [provider], { stdio: 'ignore' });
+} catch {
+  console.error(`Error: '${provider}' CLI is not installed or not on PATH.`);
+  console.error(`Install it first, then retry: merlin-ask ${provider} "${prompt}"`);
+  process.exit(1);
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function slugify(text) {
+  return text.toLowerCase().replace(/[^a-z0-9\s-]/g, '').trim().replace(/\s+/g, '-').slice(0, 40);
+}
+
+function saveArtifact(prov, text, output, exitCode, timestamp) {
+  if (!fs.existsSync(ARTIFACTS_DIR)) fs.mkdirSync(ARTIFACTS_DIR, { recursive: true });
+  const filePath = path.join(ARTIFACTS_DIR, `${prov}-${slugify(text)}-${timestamp}.md`);
+  fs.writeFileSync(filePath, [
+    `# Provider Ask — ${prov}`,
+    '',
+    `**Timestamp:** ${timestamp}`,
+    `**Exit Code:** ${exitCode}`,
+    '',
+    '## Prompt',
+    '',
+    text,
+    '',
+    '## Output',
+    '',
+    output || '_(no output)_',
+  ].join('\n'), 'utf-8');
+  return filePath;
+}
+
+// ── Spawn ─────────────────────────────────────────────────────────────────────
+
+const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+const [cmd, args] = COMMANDS[provider](prompt);
+
+const env = { ...process.env };
+if (provider === 'codex') {
+  delete env['RUST_LOG'];
+  delete env['RUST_BACKTRACE'];
+}
+
+const stdoutChunks = [];
+const stderrChunks = [];
+const proc = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'], env });
+
+proc.stdout.on('data', (chunk) => stdoutChunks.push(chunk));
+proc.stderr.on('data', (chunk) => stderrChunks.push(chunk));
+
+proc.on('error', (err) => {
+  console.error(`Failed to start ${provider}: ${err.message}`);
+  process.exit(1);
+});
+
+proc.on('close', (code) => {
+  const output   = Buffer.concat(stdoutChunks).toString('utf-8').trim();
+  const stderr   = Buffer.concat(stderrChunks).toString('utf-8').trim();
+  const exitCode = code ?? -1;
+  const text     = output || stderr;
+
+  const artifactPath = saveArtifact(provider, prompt, text, exitCode, timestamp);
+
+  if (text) process.stdout.write(text + '\n');
+  if (exitCode !== 0) process.stderr.write(`[merlin-ask] ${provider} exited with code ${exitCode}\n`);
+  process.stderr.write(`[merlin-ask] Artifact saved: ${artifactPath}\n`);
+  process.exit(exitCode);
+});

package/bin/merlin-cli.cjs

@@ -353,6 +353,17 @@ async function inject() {
     }
   }
 
+  const agentsMd = path.join(repoRoot, 'AGENTS.md');
+  if (fs.existsSync(agentsMd)) {
+    const content = fs.readFileSync(agentsMd, 'utf-8');
+    if (!content.includes('MERLIN_SIGHT')) {
+      fs.writeFileSync(agentsMd, `# MERLIN_SIGHT: ${sightUrl}\n` + content);
+      console.log('✅ Injected Sight URL into AGENTS.md');
+    } else {
+      console.log('⏭️  AGENTS.md already has MERLIN_SIGHT marker');
+    }
+  }
+
   const cursorRules = path.join(repoRoot, '.cursor', 'rules');
   if (fs.existsSync(cursorRules)) {
     const content = fs.readFileSync(cursorRules, 'utf-8');
@@ -371,6 +382,17 @@ async function inject() {
     }
   }
 
+  const geminiMd = path.join(repoRoot, 'GEMINI.md');
+  if (fs.existsSync(geminiMd)) {
+    const content = fs.readFileSync(geminiMd, 'utf-8');
+    if (!content.includes('MERLIN_SIGHT')) {
+      fs.writeFileSync(geminiMd, `# MERLIN_SIGHT: ${sightUrl}\n` + content);
+      console.log('✅ Injected Sight URL into GEMINI.md');
+    } else {
+      console.log('⏭️  GEMINI.md already has MERLIN_SIGHT marker');
+    }
+  }
+
   console.log(`\n📄 Sight: ${sightUrl}`);
   console.log(`🔗 API:   ${apiUrl}`);
   console.log('\nCommit .merlin.json to make it available to all collaborators.');