braintrust-lite 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HongjieRen
+
+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,149 @@
+# braintrust-lite
+
+Claude Code 原生的多模型军师 — 并发调用 Codex + Gemini，主 Claude 担任 Judge 融合输出。
+
+```
+主 Claude → parallel:
+  ├─ Task(subagent_type=Plan, prompt=X)       ← 正常子 agent
+  └─ mcp__braintrust_lite__consult(prompt=X) ← Codex + Gemini 旁路咨询
+          → 主 Claude 融合三方视角 → 最终方案
+```
+
+vs [`braintrust`](https://github.com/HongjieRen/braintrust): 2 次 API 调用（省 50%），无独立 Judge，无落盘，原生集成 Claude Code。
+
+---
+
+## 安装
+
+**前置条件**：`codex` 和 `gemini` CLI 均已登录。
+
+```bash
+# 克隆
+git clone https://github.com/HongjieRen/braintrust-lite.git
+cd braintrust-lite
+
+# 安装依赖
+npm install
+
+# 可选：把 CLI 软链到 PATH
+ln -sf "$(pwd)/bin/consult" ~/.local/bin/consult
+chmod +x bin/consult
+```
+
+---
+
+## 注册到 Claude Code（MCP）
+
+```bash
+claude mcp add braintrust-lite node "$(pwd)/src/server.js"
+```
+
+注册后，Claude Code 会话里会出现 `mcp__braintrust_lite__consult` tool，和 `Read` / `Bash` 并列可用。
+
+重启 Claude Code 后生效。
+
+---
+
+## 安装 Skill 引导
+
+把 skill 软链到 Claude Code 全局 skill 目录，让主 Claude 知道何时该主动使用 consult：
+
+```bash
+ln -sf "$(pwd)/skills/consult" ~/.claude/skills/consult
+```
+
+安装后可用 `/consult` slash command 激活"军师模式"引导。
+
+---
+
+## 使用方式
+
+### 在 Claude Code 里（推荐）
+
+Claude 会在处理规划/设计类任务时自动（或在 `/consult` 引导下）并发调用：
+
+```
+你处理一个架构选型任务时，Claude 会同时：
+  1. 启动 Plan sub-agent 做深度分析
+  2. 调用 mcp__braintrust_lite__consult 获取 Codex + Gemini 的独立视角
+  3. 融合三方输出给你最终方案
+```
+
+### 终端 CLI（fallback / 调试）
+
+```bash
+consult "解释 CAP 定理"                   # 并发两模型，markdown 输出
+consult --only codex "prompt"             # 只跑 codex
+consult --skip gemini "prompt"            # 跳过 gemini
+consult --timeout 60 "prompt"             # 超时秒数
+consult --dir ~/myproject "review"        # 工作目录
+cat app.ts | consult "review this code"   # stdin 拼接
+consult --json "prompt"                   # JSON 结构化输出
+```
+
+---
+
+## 参数
+
+| 参数 | 默认 | 说明 |
+|---|---|---|
+| `prompt` | 必须 | 问题文本（MCP）/ 位置参数（CLI）|
+| `only` | — | 只调用: `codex` \| `gemini` |
+| `skip` | — | 跳过模型列表 |
+| `timeout_sec` | `90` | 每个模型超时秒数 |
+| `cwd` | server cwd | 子进程工作目录 |
+| `--json` | false | CLI 专用：JSON 格式输出 |
+
+---
+
+## 输出格式
+
+```
+## CODEX (8.2s)
+
+<codex 完整回答>
+
+---
+
+## GEMINI (6.5s)
+
+<gemini 完整回答>
+```
+
+失败的 provider 显示 `*调用失败: timeout*`，另一个照常返回（`Promise.allSettled` 容错）。
+
+---
+
+## 架构
+
+```
+braintrust-lite/
+├── src/
+│   ├── server.js      MCP stdio server
+│   ├── consult.js     核心并发逻辑
+│   ├── providers.js   spawn + Codex/Gemini 解析器
+│   └── format.js      Markdown / JSON 渲染
+├── bin/
+│   └── consult        CLI 入口
+├── skills/
+│   └── consult/
+│       └── SKILL.md   Claude Code skill 引导
+└── docs/
+    └── spec.md        设计文档
+```
+
+---
+
+## 成本
+
+| 场景 | API 调用 | 估算成本 |
+|---|---|---|
+| 简单问题 | 2 | $0.05–0.15 |
+| 中等问题 | 2 | $0.15–0.40 |
+| 复杂问题 | 2 | $0.40–0.80 |
+
+---
+
+## License
+
+MIT

package/bin/consult

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+'use strict';
+
+// CLI entry point for braintrust-lite.
+// Usage: consult [options] "prompt"
+//        cat file | consult "review this"
+
+import { readFileSync } from 'fs';
+import { resolve } from 'path';
+import { consult } from '../src/consult.js';
+import { formatAsMarkdown, formatAsJson } from '../src/format.js';
+
+// ─── Arg parsing ──────────────────────────────────────────────────────────────
+
+const flags = { skip: [] };
+const positional = [];
+const argv = process.argv.slice(2);
+
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a === '--skip') { flags.skip.push(argv[++i]); continue; }
+  if (a === '--only') { flags.only = argv[++i]; continue; }
+  if (a === '--timeout') { flags.timeout = Number(argv[++i]); continue; }
+  if (a === '--dir') { flags.dir = argv[++i]; continue; }
+  if (a === '--json') { flags.json = true; continue; }
+  if (a === '--help' || a === '-h') { printHelp(); process.exit(0); }
+  positional.push(a);
+}
+
+function printHelp() {
+  console.error(`Usage: consult [options] "your question"
+       cat file | consult "explain this"
+
+Options:
+  --only <model>     Only run one model: codex | gemini
+  --skip <model>     Skip a model (repeatable)
+  --timeout <sec>    Per-model timeout in seconds (default: 90)
+  --dir <path>       Working directory for CLI subprocesses
+  --json             Output full JSON instead of markdown
+  --help             Show this help`);
+}
+
+// ─── Prompt ───────────────────────────────────────────────────────────────────
+
+let prompt = positional.join(' ');
+
+if (!process.stdin.isTTY) {
+  const stdin = readFileSync(0, 'utf8').trim();
+  if (stdin) prompt = prompt ? `${prompt}\n\n<context>\n${stdin}\n</context>` : stdin;
+}
+
+if (!prompt) {
+  printHelp();
+  process.exit(1);
+}
+
+// ─── Run ─────────────────────────────────────────────────────────────────────
+
+const results = await consult({
+  prompt,
+  only: flags.only,
+  skip: flags.skip,
+  timeoutMs: flags.timeout ? flags.timeout * 1000 : 90_000,
+  cwd: flags.dir ? resolve(flags.dir) : undefined,
+});
+
+// Progress summary to stderr
+for (const r of results) {
+  const status = r.error ? `⚠ ${r.error}` : `✓ ${(r.duration_ms / 1000).toFixed(1)}s`;
+  process.stderr.write(`[${r.provider}: ${status}]\n`);
+}
+
+// Output to stdout
+if (flags.json) {
+  console.log(formatAsJson(prompt, results));
+} else {
+  console.log('\n' + formatAsMarkdown(results));
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "braintrust-lite",
+  "version": "0.1.0",
+  "description": "Lightweight multi-model advisor for Claude Code — parallel Codex + Gemini consultation via MCP",
+  "type": "module",
+  "bin": {
+    "consult": "./bin/consult",
+    "braintrust-lite": "./src/server.js"
+  },
+  "scripts": {
+    "start": "node src/server.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.10.2"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": ["mcp", "claude-code", "codex", "gemini", "multi-model", "ai"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/HongjieRen/braintrust-lite.git"
+  }
+}

package/src/consult.js

@@ -0,0 +1,72 @@
+import {
+  runProcess,
+  adaptCodex,
+  adaptGemini,
+  CODEX_ARGS_PREFIX,
+  GEMINI_ARGS_PREFIX,
+} from './providers.js';
+
+const SYSTEM_PROMPT = `你是一个独立思考的高级专家。请基于自己的判断给出高质量、可执行的回答。
+要求：独立思考，不假设其他专家会补充；区分结论、依据、假设、风险；简洁但完整。`;
+
+const PROVIDERS = {
+  codex: {
+    cmd: 'codex',
+    buildArgs: prompt => [...CODEX_ARGS_PREFIX, `${SYSTEM_PROMPT}\n\n${prompt}`],
+    adapt: adaptCodex,
+  },
+  gemini: {
+    cmd: 'gemini',
+    buildArgs: prompt => ['-p', `${SYSTEM_PROMPT}\n\n${prompt}`, ...GEMINI_ARGS_PREFIX],
+    adapt: adaptGemini,
+  },
+};
+
+/**
+ * Run a single provider and return a normalized result object.
+ * Never throws — errors are captured in the `error` field.
+ */
+async function runOne(name, prompt, { cwd, timeoutMs }) {
+  const p = PROVIDERS[name];
+  const start = Date.now();
+  const raw = await runProcess(p.cmd, p.buildArgs(prompt), { cwd, timeoutMs });
+  const duration_ms = Date.now() - start;
+
+  const error = raw.code === 'timeout' ? 'timeout'
+    : raw.code !== 0 ? `exit ${raw.code}`
+    : null;
+
+  const { content } = error ? { content: '' } : p.adapt(raw);
+  return { provider: name, content, duration_ms, error };
+}
+
+/**
+ * Consult Codex and/or Gemini in parallel.
+ *
+ * @param {object} opts
+ * @param {string}   opts.prompt       - The question to ask.
+ * @param {string}   [opts.only]       - 'codex' | 'gemini' — only run this one.
+ * @param {string[]} [opts.skip]       - Providers to skip.
+ * @param {number}   [opts.timeoutMs]  - Per-provider timeout in ms (default 90 000).
+ * @param {string}   [opts.cwd]        - Working directory for subprocesses.
+ * @returns {Promise<Array<{provider, content, duration_ms, error}>>}
+ */
+export async function consult({ prompt, only, skip = [], timeoutMs = 90_000, cwd } = {}) {
+  const targets = Object.keys(PROVIDERS)
+    .filter(name => (only ? name === only : true))
+    .filter(name => !skip.includes(name));
+
+  if (targets.length === 0) {
+    throw new Error('No providers selected — check --only / --skip flags.');
+  }
+
+  const settled = await Promise.allSettled(
+    targets.map(name => runOne(name, prompt, { cwd, timeoutMs }))
+  );
+
+  return targets.map((name, i) =>
+    settled[i].status === 'fulfilled'
+      ? settled[i].value
+      : { provider: name, content: '', duration_ms: 0, error: settled[i].reason?.message ?? 'unknown' }
+  );
+}

package/src/format.js

@@ -0,0 +1,20 @@
+/**
+ * Format an array of provider results as human-readable Markdown.
+ * Each provider gets a ## header with timing (or error), then its content.
+ */
+export function formatAsMarkdown(results) {
+  return results.map(r => {
+    const label = r.error
+      ? `## ${r.provider.toUpperCase()} (${r.error})`
+      : `## ${r.provider.toUpperCase()} (${(r.duration_ms / 1000).toFixed(1)}s)`;
+    const body = r.error ? `*调用失败: ${r.error}*` : r.content;
+    return `${label}\n\n${body}`;
+  }).join('\n\n---\n\n');
+}
+
+/**
+ * Format results as a compact JSON string for programmatic consumption.
+ */
+export function formatAsJson(prompt, results) {
+  return JSON.stringify({ prompt, results }, null, 2);
+}

package/src/providers.js

@@ -0,0 +1,78 @@
+import { spawn } from 'child_process';
+
+// ─── Provider argv constants ──────────────────────────────────────────────────
+
+export const CODEX_ARGS_PREFIX = ['exec', '--json', '--skip-git-repo-check', '--ephemeral'];
+export const GEMINI_ARGS_PREFIX = ['-o', 'json', '--allowed-mcp-server-names', 'sequential-thinking'];
+
+// ─── Process runner ───────────────────────────────────────────────────────────
+
+/**
+ * Spawn a subprocess with an AbortController-based timeout.
+ * Returns { stdout, stderr, code } — never rejects.
+ */
+export function runProcess(cmd, args, { cwd, timeoutMs } = {}) {
+  const ac = new AbortController();
+  const proc = spawn(cmd, args, {
+    signal: ac.signal,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    ...(cwd ? { cwd } : {}),
+  });
+
+  let stdout = '';
+  let stderr = '';
+  proc.stdout.on('data', d => { stdout += d; });
+  proc.stderr.on('data', d => { stderr += d; });
+
+  const timer = timeoutMs ? setTimeout(() => ac.abort(), timeoutMs) : null;
+
+  return new Promise(resolve => {
+    const done = code => {
+      if (timer) clearTimeout(timer);
+      resolve({ stdout, stderr, code });
+    };
+    proc.on('close', done);
+    proc.on('error', err => done(err.name === 'AbortError' ? 'timeout' : -1));
+  });
+}
+
+// ─── Adapters ─────────────────────────────────────────────────────────────────
+
+/** Last-resort: take the tail of raw stdout. */
+export function fallback(rawStdout) {
+  return { content: rawStdout.slice(-2000).trim() || '[no output]', parse_mode: 'fallback' };
+}
+
+/** Parse Codex JSONL stream → extract the last agent_message text. */
+export function adaptCodex(raw) {
+  try {
+    const events = raw.stdout.trim().split('\n').flatMap(l => {
+      try { return [JSON.parse(l)]; } catch { return []; }
+    });
+    const msg = events.filter(e => e.type === 'item.completed' && e.item?.type === 'agent_message').pop()
+      ?? events.filter(e => e.type === 'item.completed').pop();
+    if (msg?.item?.text) return { content: msg.item.text, parse_mode: 'jsonl' };
+  } catch { /* fall through */ }
+  return fallback(raw.stdout);
+}
+
+/** Skip any MCP startup noise before the first '{', then extract .response */
+export function parseGeminiResponse(stdout) {
+  const jsonStart = stdout.indexOf('{');
+  if (jsonStart === -1) return null;
+  const j = JSON.parse(stdout.slice(jsonStart));
+  if (typeof j.response === 'string') return j.response;
+  for (const v of Object.values(j)) {
+    if (v && typeof v === 'object' && typeof v.response === 'string') return v.response;
+  }
+  return null;
+}
+
+/** Parse Gemini JSON output → content string. */
+export function adaptGemini(raw) {
+  try {
+    const response = parseGeminiResponse(raw.stdout);
+    if (response) return { content: response, parse_mode: 'json' };
+  } catch { /* fall through */ }
+  return fallback(raw.stdout);
+}

package/src/server.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { consult } from './consult.js';
+import { formatAsMarkdown } from './format.js';
+
+// ─── Tool definition ──────────────────────────────────────────────────────────
+
+const CONSULT_TOOL = {
+  name: 'consult',
+  description:
+    '并发调用 Codex 和 Gemini CLI，获取两个顶尖模型对同一问题的独立视角。' +
+    '适合架构选型、方案设计、技术决策、复杂调研。' +
+    '调用方（通常是主 Claude）负责综合融合输出，自己担任 Judge。' +
+    '不适合：typo 修复、单行改动、只读信息查询。',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      prompt: {
+        type: 'string',
+        description: '要问两个模型的问题。建议精炼、自包含（含必要上下文）。',
+      },
+      only: {
+        type: 'string',
+        enum: ['codex', 'gemini'],
+        description: '只调用指定一个模型（省成本或调试）。',
+      },
+      skip: {
+        type: 'array',
+        items: { type: 'string', enum: ['codex', 'gemini'] },
+        description: '跳过指定模型列表。',
+      },
+      timeout_sec: {
+        type: 'number',
+        description: '每个模型的超时秒数，默认 90。',
+      },
+      cwd: {
+        type: 'string',
+        description: '子进程工作目录，默认继承 MCP server 的 cwd。',
+      },
+    },
+    required: ['prompt'],
+  },
+};
+
+// ─── Server setup ─────────────────────────────────────────────────────────────
+
+const server = new Server(
+  { name: 'braintrust-lite', version: '0.1.0' },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [CONSULT_TOOL],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async req => {
+  if (req.params.name !== 'consult') {
+    throw new Error(`Unknown tool: ${req.params.name}`);
+  }
+
+  const args = req.params.arguments ?? {};
+  const results = await consult({
+    prompt: String(args.prompt ?? ''),
+    only: args.only,
+    skip: Array.isArray(args.skip) ? args.skip : [],
+    timeoutMs: args.timeout_sec ? Number(args.timeout_sec) * 1000 : 90_000,
+    cwd: args.cwd,
+  });
+
+  if (results.every(r => r.error)) {
+    throw new Error(
+      `All providers failed: ${results.map(r => `${r.provider}=${r.error}`).join(', ')}`
+    );
+  }
+
+  return {
+    content: [{ type: 'text', text: formatAsMarkdown(results) }],
+  };
+});
+
+// ─── Start ────────────────────────────────────────────────────────────────────
+
+const transport = new StdioServerTransport();
+await server.connect(transport);