braintrust-lite 0.1.6 → 0.1.8

package/README.md

@@ -1,149 +1,120 @@
-# braintrust-lite
+# brantrust
 
-Claude Code 原生的多模型军师 — 并发调用 Codex + Gemini，主 Claude 担任 Judge 融合输出。
+同题多模型融合器 — 把同一个问题同时发给 Claude、Codex、Gemini，然后用一个 Judge 综合出"集大成方案"。
 
 ```
-主 Claude → parallel:
-  ├─ Task(subagent_type=Plan, prompt=X)       ← 正常子 agent
-  └─ mcp__braintrust_lite__consult(prompt=X) ← Codex + Gemini 旁路咨询
-          → 主 Claude 融合三方视角 → 最终方案
+输入 → 并发生成(3) → 清洗归一化 → Judge 融合(1) → 输出 + 落盘
 ```
 
-vs [`braintrust`](https://github.com/HongjieRen/braintrust): 2 次 API 调用（省 50%），无独立 Judge，无落盘，原生集成 Claude Code。
+4 次 API 调用，低成本，天天能用。
 
 ---
 
 ## 安装
 
-**前置条件**：`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
-```
+git clone https://github.com/HongjieRen/brantrust.git
+cd brantrust
 
----
-
-## 注册到 Claude Code（MCP）
-
-```bash
-claude mcp add braintrust-lite node "$(pwd)/src/server.js"
+# 软链接到 PATH
+ln -sf "$(pwd)/brantrust" ~/.local/bin/brantrust
+chmod +x brantrust
 ```
 
-注册后，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
-```
+**前置依赖**（三个 CLI 均需已登录）：
 
-安装后可用 `/consult` slash command 激活"军师模式"引导。
+| Provider | CLI | 验证命令 |
+|----------|-----|---------|
+| Claude | `claude` | `claude -p "hi" --output-format json` |
+| OpenAI Codex | `codex` | `codex exec "hi" --json --skip-git-repo-check --ephemeral` |
+| Google Gemini | `gemini` | `gemini -p "hi" -o json` |
 
 ---
 
-## 使用方式
-
-### 在 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 结构化输出
+brantrust "解释 CAP 定理"                      # 默认：3 generator + 1 judge
+brantrust --no-judge "React vs Vue"            # 只并发收集，不 judge
+brantrust --judge-model gemini "数据库选型"    # 切换 Judge 模型
+brantrust --skip codex "量子计算"              # 跳过某个模型（可多次）
+cat app.ts | brantrust "review 这段代码"       # stdin 管道
+brantrust --dir ~/project "项目分析"           # 指定工作目录
+brantrust --context-file design.md "实现方案"  # 附加上下文文件
+brantrust --timeout 60 "快速问题"              # 超时秒数
+brantrust --no-save "临时问答"                 # 不保存到磁盘
+brantrust --json "问题"                        # 输出完整 JSON
+brantrust --list                               # 查看历史运行
+brantrust --strict "关键决策"                  # [v2] 完整 Judge 流水线
 ```
 
----
-
-## 参数
+### 参数一览
 
 | 参数 | 默认 | 说明 |
-|---|---|---|
-| `prompt` | 必须 | 问题文本（MCP）/ 位置参数（CLI）|
-| `only` | — | 只调用: `codex` \| `gemini` |
-| `skip` | — | 跳过模型列表 |
-| `timeout_sec` | `90` | 每个模型超时秒数 |
-| `cwd` | server cwd | 子进程工作目录 |
-| `--json` | false | CLI 专用：JSON 格式输出 |
+|------|------|------|
+| `"prompt"` | 必须 | 问题文本 |
+| `--skip <model>` | — | 跳过模型：claude / codex / gemini，可多次使用 |
+| `--judge-model <model>` | `claude` | Judge 使用的模型 |
+| `--no-judge` | false | 关闭 Judge，只展示各模型原始回答 |
+| `--timeout <sec>` | `120` | 每个模型的超时秒数 |
+| `--dir <path>` | cwd | CLI 工具的工作目录 |
+| `--context-file <file>` | — | 附加文件内容作为上下文（最多 8000 字符）|
+| `--no-save` | false | 不保存结果到磁盘 |
+| `--json` | false | 将完整结果以 JSON 格式输出到 stdout |
+| `--list` | — | 列出最近 20 条历史运行 |
+| `--strict` | — | [v2 占位] 两阶段 Judge + swap-compare |
 
 ---
 
-## 输出格式
+## 输出
 
-```
-## CODEX (8.2s)
-
-<codex 完整回答>
-
----
+**终端**：各模型回答 + Judge 融合报告（Markdown 格式）
 
-## GEMINI (6.5s)
+**落盘**（`~/ai-outputs/<timestamp>/`）：
 
-<gemini 完整回答>
 ```
-
-失败的 provider 显示 `*调用失败: timeout*`，另一个照常返回（`Promise.allSettled` 容错）。
+~/ai-outputs/2026-04-09T11-23-45-678/
+├── raw/
+│   ├── claude.txt
+│   ├── codex.txt
+│   └── gemini.txt
+├── normalized.json    # 三个模型的结构化摘要
+└── report.md          # 最终融合报告
+```
 
 ---
 
 ## 架构
 
 ```
-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        设计文档
+runGenerators()         # 并发调用三个 CLI，AbortController 超时，Promise.allSettled 容错
+normalizeResults()      # 各适配器提取 content / key_claims / assumptions / risks
+runSimpleJudge()        # 单次 Judge 调用，只传归一化摘要（非全文），控制 token
+writeRunArtifacts()     # 落盘 raw/ + normalized.json + report.md
+runFullJudgePipeline()  # [v2 占位] 两阶段 Judge + swap-compare + 抗偏置
 ```
 
+**Judge prompt 匿名化**：候选标签只用 A / B / C，不暴露 provider 名称，避免模型偏置。
+
 ---
 
-## 成本
+## 成本估算
+
+每次运行 = 4 次 API 调用（3 generator + 1 judge）：
 
-| 场景 | API 调用 | 估算成本 |
-|---|---|---|
-| 简单问题 | 2 | $0.05–0.15 |
-| 中等问题 | 2 | $0.15–0.40 |
-| 复杂问题 | 2 | $0.40–0.80 |
+| 问题复杂度 | 估算成本 |
+|-----------|---------|
+| 简单 | $0.20 – 0.50 |
+| 中等 | $0.50 – 1.00 |
+| 复杂 | $1.00 – 2.00 |
 
 ---
 
-## License
+## V2 路线图
 
-MIT
+1. `--strict`：两阶段 Judge (A+B) + swap-compare + 抗偏置
+2. `--continue`：线程续聊
+3. `--context-file` 智能截断 + git diff 注入
+4. 成本 / token 预算控制器
+5. 更多 provider（Goose、本地模型等）

package/bin/braintrust

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+'use strict';
+
+// Shim: delegates to src/main.js
+// The symlink ~/.local/bin/braintrust → this file remains unchanged.
+
+const { main } = require('../src/main.js');
+
+main(process.argv.slice(2)).catch(e => {
+  process.stderr.write(`[braintrust error] ${e.message}\n`);
+  process.exit(1);
+});

package/package.json

@@ -1,32 +1,40 @@
 {
   "name": "braintrust-lite",
-  "version": "0.1.6",
-  "description": "Lightweight multi-model advisor for Claude Code — parallel Codex + Gemini consultation via MCP",
-  "type": "module",
+  "version": "0.1.8",
+  "description": "Multi-model AI consultation MCP for Claude Code — runs Claude, Codex, and Gemini in parallel for Judge-style synthesis",
   "bin": {
-    "consult": "bin/consult",
-    "braintrust-lite": "src/server.js"
+    "braintrust-lite": "./src/server.js",
+    "braintrust": "./bin/braintrust",
+    "braintrust-doctor": "./src/doctor.js"
   },
+  "main": "src/main.js",
+  "files": [
+    "src/",
+    "skills/",
+    "bin/",
+    "README.md"
+  ],
   "scripts": {
-    "start": "node src/server.js"
+    "test": "node --test src/normalize.test.js"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.10.2"
+    "better-sqlite3": "^11.0.0"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=18.0.0"
   },
   "keywords": [
     "mcp",
     "claude-code",
+    "multi-model",
+    "ai",
     "codex",
     "gemini",
-    "multi-model",
-    "ai"
+    "braintrust"
   ],
-  "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/HongjieRen/braintrust-lite.git"
-  }
+    "url": "https://github.com/HongjieRen/braintrust.git"
+  },
+  "license": "MIT"
 }

package/skills/consult/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: consult
+version: 1.4.0
+description: 在处理规划/设计/架构/调研类任务时，并发调用 codex + gemini + claude 获取多视角，主 Claude 担任 Judge 盲评综合输出。支持渐进式多轮对话和自动更新。
+---
+
+# consult — 多模型旁路军师
+
+## Preamble（每次调用前先执行）
+
+```bash
+_REMOTE_VER=$(curl -sf --max-time 3 "https://raw.githubusercontent.com/HongjieRen/braintrust/main/skills/consult/SKILL.md" | awk '/^version:/ {print $2; exit}')
+_LOCAL_VER=$(awk '/^version:/ {print $2; exit}' ~/.claude/skills/consult/SKILL.md 2>/dev/null)
+[ -n "$_REMOTE_VER" ] && [ "$_REMOTE_VER" != "$_LOCAL_VER" ] && echo "UPGRADE_AVAILABLE $_LOCAL_VER $_REMOTE_VER" || echo "UP_TO_DATE $_LOCAL_VER"
+```
+
+**如果输出 `UPGRADE_AVAILABLE <old> <new>`**：静默自动更新，不打断用户：
+```bash
+cp ~/.claude/skills/consult/SKILL.md ~/.claude/skills/consult/SKILL.md.bak 2>/dev/null || true
+curl -fsSL "https://raw.githubusercontent.com/HongjieRen/braintrust/main/skills/consult/SKILL.md" \
+  -o ~/.claude/skills/consult/SKILL.md && echo "Updated consult skill $_old → $_new"
+```
+更新完成后继续执行本次任务，在最终回复末尾附一行：`*(consult skill 已自动更新 v{old} → v{new})*`
+
+**如果输出 `UP_TO_DATE`**：直接继续，无需提示。  
+**如果 curl 失败**：忽略，继续执行，不提示用户。
+
+---
+
+## 这是什么
+
+`braintrust-lite` 提供的 MCP tool `mcp__braintrust_lite__consult` 会在后台并发调用 **Codex CLI**、**Gemini CLI** 和 **Claude CLI**，把三个顶尖模型的独立回答以匿名形式（Model A/B/C）交回给你。
+
+你（主 Claude）负责担任 Judge——盲评内容，提炼共识、标注独特洞见、裁决分歧，输出集大成方案。
+
+## 何时使用
+
+对以下类型的任务，**在启动子 agent 的同时并行调用 consult**：
+
+- 架构选型、技术选型、框架比较
+- 方案设计（新功能、重大重构、系统集成）
+- 复杂 bug 根因分析（多种假设并存时）
+- 非显而易见的技术决策（有明显 trade-off 的场景）
+- 安全或性能评审
+
+## 何时跳过
+
+- typo 修复、单行改动、简单 rename
+- 只读信息查询（用 Grep / Read 就够）
+- 用户已经明确指定方案，不需要二次意见
+- 已知有标准答案的操作性任务
+
+---
+
+## 工作流：单轮
+
+```
+1. 发一条 message，同时 parallel call：
+   ├─ Task(subagent_type=Plan/Explore/..., prompt=X)
+   └─ mcp__braintrust_lite__consult(prompt=X, timeout_sec=<见下表>)
+
+2. 等两者都返回后，你亲自担任 Judge（盲评流程）：
+
+   步骤一：只看 Model A/B/C 内容，按结构完成评估（见下方 Judge 输出格式）
+
+   步骤二：读 REVEAL 映射表
+
+   步骤三：在回复末尾揭晓：
+   "揭晓：Model A = Gemini，Model B = Claude，Model C = Codex"
+```
+
+### Judge 输出格式（必须分节，供多轮渐进加载）
+
+每轮 Judge 输出**强制使用以下四节**，不可合并：
+
+```
+### VERDICT
+<核心结论，1-3句，永远保留进历史>
+
+### REASONING
+<关键推理和裁决依据，有追问才加载>
+
+### TRADEOFFS
+<权衡分析、已排除方案及理由，用户问"有没有其他方案"时加载>
+
+### OPEN_QUESTIONS
+<未解决的分歧或待确认的假设，用户问"还有什么不确定"时加载>
+```
+
+---
+
+## 工作流：多轮对话（会话模式）
+
+### 进入信号
+
+`/consult` 触发后，第一轮回复顶部显示：
+
+```
+┌─ Consult 会话已启动 ──────────────────────────┐
+│ 模型：Codex · Gemini · Claude CLI              │
+│ 记忆：Balanced（可用 !brief / !deep 切换）      │
+│ 输入问题继续追问，或输入 /done 退出             │
+└────────────────────────────────────────────────┘
+```
+
+### 每轮状态栏（**每轮回复第一行**，始终显示）
+
+每轮 Judge 输出**最开始**，必须先输出这一行状态栏，再输出任何正文：
+
+```
+[Consult·R{N} | 3 models | Consensus: {High/Split}]
+```
+
+- `R{N}` = 第几轮，帮助用户感知多轮积累
+- `Consensus: Split` 时额外显示一行分歧摘要：`Note: split on <主要分歧点>`
+- 平时无分歧则只显示 `High`，不展开
+- 若模型降级（实际跑了少于 3 个），显示 `⚠ 2/3 models` 代替 `3 models`
+
+### 多轮上下文：渐进式加载（核心设计）
+
+**设计原则：不预先决定压缩多少，而是根据 follow-up 意图决定加载什么。**
+
+每轮结束后维护一个**会话状态对象**（始终随 prompt 携带，~100 token）：
+
+```
+[Session State]
+Goal: <用户核心目标>
+Constraints: <已确认约束>
+Decisions: <已做决策及理由>
+Rejected: <已排除选项>
+Open: <未解决问题>
+Current best: <当前推荐方案一句话>
+```
+
+历史内容**按意图懒加载**，不机械按轮次：
+
+| follow-up 意图 | 加载的历史内容 |
+|---------------|--------------|
+| 普通追问、深入某方向 | Session State + 所有历史 VERDICT |
+| "为什么这样判断" | + 最近1轮 REASONING |
+| "有没有其他方案" | + 最近1轮 TRADEOFFS |
+| "还有什么不确定" | + 最近1轮 OPEN_QUESTIONS |
+| "刚才某模型说的那个点" | + 按需检索原文片段（Model A/B/C 原始回答存档备查） |
+
+历史 VERDICT 全部保留（每条 ~50 token），其余节只保留最近1-2轮，更老的丢弃。
+
+### 自动降级
+
+用户回复是简单确认时（"好的"、"谢谢"、"明白了"等），**不触发三模型并发**，由主 Claude 直接响应，节省成本和延迟。
+
+判断标准：用户回复 < 20 字且不含实质性新问题。
+
+### 多轮终止条件
+
+- 用户输入 `/done`（或 `!stop`）
+- 用户明确表示满意（"好了"、"没问题了"）
+- 用户切换到无关新话题
+- 已进行 5 轮（自动退出，告知用户可重新 `/consult`）
+
+退出时显示：`── Consult 会话结束（共 {N} 轮）──`
+
+### 用户控制命令
+
+```
+!brief    切换到精简记忆（只带 VERDICT，适合快速迭代）
+!deep     切换到完整记忆（带最近1轮 REASONING + TRADEOFFS，适合复杂设计）
+/done     退出 Consult 会话模式（!stop 同效）
+!deltas   展开本轮三模型核心主张各一句（不显示原文全文）
+!raw      展开本轮三模型完整原始回答
+```
+
+---
+
+## consult tool 参数
+
+```
+prompt      (必须) 问题，建议精炼、自包含，含必要上下文
+only        (可选) "codex" | "gemini" | "claude" — 只调用一个
+skip        (可选) ["codex"] | ["gemini"] | ["claude"] — 跳过某个
+timeout_sec (可选) 每个模型超时秒数，默认 90；传 0 = 不限时等待完成
+blind       (可选) 默认 true；传 false 可直接看真实模型名称
+cwd         (可选) 子进程工作目录
+```
+
+## timeout 选择策略
+
+**你（主 Claude）负责决定 timeout_sec：**
+
+| 任务类型 | timeout_sec |
+|---------|------------|
+| 深度调研、市场分析、可行性研究 | **0**（不限时） |
+| 架构设计、复杂方案对比 | **0**（不限时） |
+| 代码审查、技术选型 | 180 |
+| 简单问答、快速决策 | 90（默认） |
+
+调研类任务一律传 `timeout_sec: 0`。
+
+## 成本与延迟
+
+- 每次 consult = 3 次 API 调用（codex + gemini + claude）
+- 延迟 = `max(三者响应时间)`（并发）
+- 简单问题 ~$0.05–0.20，中等 ~$0.20–0.50
+- 自动降级（简单确认）= 0 次额外 API 调用
+
+## 终端 fallback
+
+```bash
+consult "你的问题"
+consult --only codex "快速问题"
+consult --timeout 0 "深度调研问题"
+consult --dir /your/project "review this project"
+cat file.ts | consult "review this code"
+```

package/src/config.js

@@ -0,0 +1,60 @@
+'use strict';
+
+const { join } = require('path');
+
+const PROJECT_ROOT = join(__dirname, '..');
+const OUTPUT_DIR = join(PROJECT_ROOT, 'ai-outputs');
+const STATE_DIR = join(OUTPUT_DIR, '.state');
+const DB_PATH = join(STATE_DIR, 'braintrust.sqlite');
+const POLICY_PATH = join(STATE_DIR, 'policy.json');
+const REFLECTOR_LOG = join(STATE_DIR, 'reflector.log');
+
+const DEFAULT_TIMEOUT_S = 120;
+const DEFAULT_JUDGE_MODEL = 'claude';
+const DEFAULT_MEMORY_K = 3;
+const MAX_CONTEXT_CHARS = 30000;
+const CONTEXT_FILE_MAX = 8000;
+
+// Memory injection hard limits (chars)
+const MEMORY_INJECT_LIMIT = 1500;
+const LESSONS_INJECT_LIMIT = 600;
+const SKILLS_INJECT_LIMIT = 800;
+
+// Novelty check threshold: cosine similarity above this → prompt reuse
+const NOVELTY_THRESHOLD = 0.9;
+
+// Critique-revise disagreement threshold
+const DISAGREE_THRESHOLD = 0.5;
+
+// Economy mode: disable all extra LLM calls
+const ECONOMY = process.env.BRAINTRUST_ECONOMY === '1';
+
+// Reflector model: codex with gpt-5.4-mini.
+// Chosen over haiku/flash for better Chinese text quality.
+// Must differ from the default judge model (claude) to avoid self-evaluation bias.
+const REFLECTOR_MODEL = 'gpt-5.4-mini';
+const REFLECTOR_CMD = 'codex';
+const REFLECTOR_ARGS_PREFIX = ['exec', '--json', '--skip-git-repo-check', '--ephemeral', '-m', REFLECTOR_MODEL];
+
+module.exports = {
+  PROJECT_ROOT,
+  OUTPUT_DIR,
+  STATE_DIR,
+  DB_PATH,
+  POLICY_PATH,
+  REFLECTOR_LOG,
+  DEFAULT_TIMEOUT_S,
+  DEFAULT_JUDGE_MODEL,
+  DEFAULT_MEMORY_K,
+  MAX_CONTEXT_CHARS,
+  CONTEXT_FILE_MAX,
+  MEMORY_INJECT_LIMIT,
+  LESSONS_INJECT_LIMIT,
+  SKILLS_INJECT_LIMIT,
+  NOVELTY_THRESHOLD,
+  DISAGREE_THRESHOLD,
+  ECONOMY,
+  REFLECTOR_MODEL,
+  REFLECTOR_CMD,
+  REFLECTOR_ARGS_PREFIX,
+};

package/src/doctor.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+'use strict';
+
+const { execFileSync, spawnSync } = require('child_process');
+const { existsSync, readFileSync } = require('fs');
+const { join } = require('path');
+const { version: PKG_VERSION } = require('../package.json');
+
+const GREEN = '\x1b[32m✓\x1b[0m';
+const RED   = '\x1b[31m✗\x1b[0m';
+const WARN  = '\x1b[33m!\x1b[0m';
+
+function check(label, ok, detail) {
+  const icon = ok === true ? GREEN : ok === 'warn' ? WARN : RED;
+  const line = `  ${icon}  ${label.padEnd(28)} ${detail || ''}`;
+  console.log(line);
+  return ok === true;
+}
+
+function getVersion(cmd, args) {
+  try {
+    const result = spawnSync(cmd, args, { timeout: 5000, encoding: 'utf8' });
+    if (result.status === 0) {
+      return (result.stdout || result.stderr || '').split('\n')[0].trim().slice(0, 40);
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function getSkillVersion(skillPath) {
+  try {
+    const content = readFileSync(skillPath, 'utf8');
+    const m = content.match(/^version:\s*(.+)$/m);
+    return m ? m[1].trim() : 'unknown';
+  } catch {
+    return null;
+  }
+}
+
+function checkMcpServer() {
+  // Probe MCP server: send initialize, expect a valid JSON-RPC response
+  const serverPath = join(__dirname, 'server.js');
+  if (!existsSync(serverPath)) return { ok: false, detail: 'src/server.js not found' };
+
+  try {
+    const msg = JSON.stringify({
+      jsonrpc: '2.0', id: 1, method: 'initialize',
+      params: { protocolVersion: '2024-11-05', capabilities: {}, clientInfo: { name: 'doctor', version: '0' } },
+    });
+    const result = spawnSync(process.execPath, [serverPath], {
+      input: msg + '\n',
+      timeout: 5000,
+      encoding: 'utf8',
+    });
+    const line = (result.stdout || '').split('\n').find(l => l.trim().startsWith('{'));
+    if (!line) return { ok: false, detail: 'no JSON response from server' };
+    const resp = JSON.parse(line);
+    if (resp.result && resp.result.serverInfo) {
+      return { ok: true, detail: `v${resp.result.serverInfo.version}` };
+    }
+    return { ok: false, detail: 'unexpected response shape' };
+  } catch (err) {
+    return { ok: false, detail: err.message.slice(0, 60) };
+  }
+}
+
+function main() {
+  console.log(`\nbraintrust doctor  (package v${PKG_VERSION})\n`);
+
+  let allOk = true;
+
+  // ── CLI tools ──────────────────────────────────────────────────────────────
+  console.log('CLI tools:');
+  for (const [cmd, vArgs, installHint] of [
+    ['claude', ['--version'],      'https://claude.ai/download'],
+    ['codex',  ['--version'],      'npm i -g @openai/codex'],
+    ['gemini', ['--version'],      'npm i -g @google/gemini-cli'],
+  ]) {
+    const ver = getVersion(cmd, vArgs);
+    if (ver) {
+      check(cmd, true, ver);
+    } else {
+      check(cmd, false, `not found — ${installHint}`);
+      allOk = false;
+    }
+  }
+
+  // ── MCP server ─────────────────────────────────────────────────────────────
+  console.log('\nMCP server:');
+  const mcp = checkMcpServer();
+  if (!check('braintrust-lite server', mcp.ok, mcp.detail)) allOk = false;
+
+  // ── Skill ──────────────────────────────────────────────────────────────────
+  console.log('\nConsult skill:');
+  const skillPath = join(process.env.HOME || '~', '.claude', 'skills', 'consult', 'SKILL.md');
+  const skillVer = getSkillVersion(skillPath);
+  if (skillVer) {
+    check('SKILL.md installed', true, `v${skillVer}  at ${skillPath}`);
+  } else {
+    check('SKILL.md installed', false, `not found at ${skillPath}`);
+    allOk = false;
+  }
+
+  const bakPath = skillPath + '.bak';
+  check('SKILL.md.bak exists', existsSync(bakPath) ? 'warn' : 'warn',
+    existsSync(bakPath) ? 'backup present' : 'no backup yet (created on first auto-update)');
+
+  // ── Summary ────────────────────────────────────────────────────────────────
+  console.log();
+  if (allOk) {
+    console.log('  \x1b[32mAll checks passed — braintrust is ready.\x1b[0m\n');
+  } else {
+    console.log('  \x1b[31mSome checks failed — fix the issues above before using braintrust.\x1b[0m\n');
+    process.exit(1);
+  }
+}
+
+main();