@balpal4495/quorum 3.5.0 → 3.6.0

package/README.md

@@ -205,6 +205,79 @@ quorum advisor brief
 
 ---
 
+## LLM setup
+
+LLM-powered commands (`advisor`, `evolve`, `check`, `compass`, `serve`) auto-detect whichever provider is available. No config file is needed — Quorum picks the first working option from the list below.
+
+**Recommended: use a CLI tool you're already logged into.** No API key required.
+
+### Option 1 — Claude Code CLI (recommended)
+
+If you have [Claude Code](https://claude.ai/code) installed and are logged in, Quorum uses it automatically.
+
+```bash
+# Verify it's working
+echo "say hi" | claude --print
+```
+
+Quorum detects the `Claude Code-credentials` keychain entry (macOS) or a session file in `~/.claude/sessions/`. If the command above works, Quorum will use it.
+
+### Option 2 — GitHub Copilot CLI
+
+If you have the [GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/use-copilot-cli) installed and are logged in via VS Code, Quorum uses it automatically.
+
+```bash
+# Verify it's working
+copilot -p "say hi"
+```
+
+Quorum detects `~/.copilot/session-state/` having at least one session (created after first auth). If the command above works, Quorum will use it.
+
+### Option 3 — API keys
+
+Set any one of these environment variables:
+
+| Variable | Provider |
+|---|---|
+| `ANTHROPIC_API_KEY` | Anthropic Claude |
+| `OPENAI_API_KEY` | OpenAI |
+| `GEMINI_API_KEY` | Google Gemini |
+| `OPENAI_BASE_URL` | Any OpenAI-compatible endpoint (Azure, Groq, etc.) |
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+### Option 4 — Gemini CLI
+
+If you have the [Gemini CLI](https://github.com/google-gemini/gemini-cli) installed and authenticated, Quorum uses it automatically.
+
+```bash
+# Verify it's working
+gemini -p "say hi"
+```
+
+### Option 5 — Ollama (local, last resort)
+
+If Ollama is running at `localhost:11434`, Quorum uses the first available model. Set `OLLAMA_MODEL` to pin a specific model, or `OLLAMA_HOST` for a non-default address.
+
+```bash
+ollama serve
+export OLLAMA_MODEL=llama3.2   # optional
+```
+
+### Checking what was detected
+
+```bash
+quorum serve   # startup line shows: LLM: Claude Code CLI
+```
+
+### No LLM — still useful
+
+Without any provider, `advisor query`, `advisor brief`, `check`, and `coverage` all work with no LLM. Commands output Chronicle evidence and a synthesis request that your agent (Claude Code, Copilot, Codex) can answer inline.
+
+---
+
 ## Upgrading from v1
 
 If your project has a `quorum/modules/` folder (the v1 vendored pattern), migrate in one step:
@@ -602,7 +675,7 @@ Refuted entries always elevate risk by at least one level. Citation validation s
 
 ### LLM auto-detection
 
-Quorum finds whichever LLM is available: `ANTHROPIC_API_KEY` → `OPENAI_API_KEY` → `GEMINI_API_KEY` → `OPENAI_BASE_URL` → Ollama at `localhost:11434` → authenticated `gemini` CLI. When running inside an AI agent with no separate key, commands output Chronicle evidence and a synthesis request — the agent answers inline.
+Quorum tries providers in this order: **Claude Code CLI** → **Copilot CLI** → `ANTHROPIC_API_KEY` → `OPENAI_API_KEY` → `GEMINI_API_KEY` → `OPENAI_BASE_URL` → Gemini CLI → Ollama. See [LLM setup](#llm-setup) for how to configure each option.
 
 ---
 

package/bin/commands/llm.js

@@ -0,0 +1,108 @@
+import { probeAll, detectProvider } from "../shared/llm.js"
+import { c } from "../shared/colors.js"
+
+function row(detected, name, note, suffix = "") {
+  const icon  = detected ? c.green("✓") : c.dim("·")
+  const label = detected ? c.bold(name) : c.dim(name)
+  const right  = detected
+    ? (note ? c.dim(`  ${note}`) : "") + (suffix ? `  ${suffix}` : "")
+    : (note ? `  ${c.dim(note)}` : "")
+  return `  ${icon}  ${label.padEnd(26)}${right}`
+}
+
+export async function run(args) {
+  const test = args.includes("--test")
+
+  console.log("")
+  console.log(`${c.bold("quorum llm")}  ${c.dim("— LLM provider status")}`)
+  console.log("")
+
+  // Run all probes in parallel with active provider detection
+  const [providers, active] = await Promise.all([probeAll(), detectProvider()])
+  const activeName = active?.name ?? null
+
+  console.log("  Provider scan")
+  console.log(c.dim("  ─────────────────────────────────────────────────────"))
+
+  // Normalize names for active matching (gatherCandidates uses "Gemini", probeAll uses "Gemini API")
+  const norm = n => n.replace(/ API$/, "").replace(/ \(.*?\)$/, "").toLowerCase()
+
+  for (const p of providers) {
+    const isActive = p.detected && !!activeName && norm(p.name) === norm(activeName)
+
+    const badges = []
+    if (isActive)                                  badges.push(c.green("← active"))
+    if (p.detected && p.id === "ollama" && p.note) badges.push(c.dim(`(${p.note})`))
+    const suffix = badges.join("  ")
+
+    console.log(row(p.detected, p.name, null, suffix))
+    if (!p.detected && p.note) {
+      console.log(`       ${c.dim(p.note)}`)
+    }
+  }
+
+  console.log("")
+
+  if (!activeName) {
+    console.log(`  ${c.yellow("No provider detected.")}`)
+    console.log("")
+    printSetupGuide()
+    return
+  }
+
+  console.log(`  Active: ${c.bold(activeName)}`)
+  console.log("")
+
+  if (!test) {
+    console.log(c.dim("  Run 'quorum llm --test' to send a live request and verify it works."))
+    console.log("")
+    return
+  }
+
+  // ── Live test ──────────────────────────────────────────────────────────────
+  process.stdout.write(`  Testing ${c.bold(activeName)}… `)
+  const t0 = Date.now()
+
+  try {
+    const result = await active.llm([
+      { role: "user", content: "Respond with exactly the word OK and nothing else." },
+    ])
+    const ms = Date.now() - t0
+    const ok = /\bOK\b/i.test(result?.trim() ?? "")
+    if (ok) {
+      console.log(`${c.green("✓")}  ${c.dim(`(${ms}ms)`)}`)
+    } else {
+      console.log(`${c.yellow("✓ (unexpected response)")}  ${c.dim(`(${ms}ms)`)}`)
+      console.log(c.dim(`     → ${(result ?? "").slice(0, 120)}`))
+    }
+  } catch (err) {
+    console.log(c.red("✗"))
+    console.log(`     ${c.red(err.message?.slice(0, 200) ?? String(err))}`)
+    console.log("")
+    console.log(`  ${c.yellow("The detected provider failed.")} Check that you're signed in, then retry.`)
+  }
+  console.log("")
+}
+
+function printSetupGuide() {
+  console.log("  Quickest options:")
+  console.log("")
+  console.log(`  ${c.bold("A")}  ${c.bold("Claude Code CLI")}  ${c.dim("(no API key needed)")}`)
+  console.log(c.dim("     Install and sign in: https://claude.ai/code"))
+  console.log(c.dim("     Quorum auto-detects it once you're signed in."))
+  console.log("")
+  console.log(`  ${c.bold("B")}  ${c.bold("GitHub Copilot CLI")}  ${c.dim("(no API key needed)")}`)
+  console.log(c.dim("     Install VS Code + GitHub Copilot Chat extension, then sign in."))
+  console.log(c.dim("     Quorum auto-detects it once a session exists."))
+  console.log("")
+  console.log(`  ${c.bold("C")}  ${c.bold("API key")}  ${c.dim("(Anthropic, OpenAI, or Gemini)")}`)
+  console.log(c.dim("     export ANTHROPIC_API_KEY=sk-ant-…"))
+  console.log(c.dim("     export OPENAI_API_KEY=sk-…"))
+  console.log(c.dim("     export GEMINI_API_KEY=…"))
+  console.log("")
+  console.log(`  ${c.bold("D")}  ${c.bold("Ollama")}  ${c.dim("(local, free)")}`)
+  console.log(c.dim("     brew install ollama && ollama serve && ollama pull llama3.2"))
+  console.log("")
+  console.log(`  ${c.dim("After setup, run 'quorum llm' again to confirm detection.")}`)
+  console.log("")
+}

package/bin/quorum.js

@@ -23,6 +23,8 @@ ${c.bold("Usage:")}
   ${c.cyan("quorum advisor")} ${c.dim('"question"')}             Ask a plain-language question (uses LLM)
   ${c.cyan("quorum advisor query")} ${c.dim('"topic"')}          Search Chronicle entries (no LLM)
   ${c.cyan("quorum advisor brief")}                 High-level Chronicle summary (no LLM)
+  ${c.cyan("quorum llm")}                           Show LLM provider status and setup guide
+  ${c.cyan("quorum llm --test")}                    Send a live test request to the active provider
   ${c.cyan("quorum init")}                          Scaffold Quorum into a project
   ${c.cyan("quorum status")}                        Show Chronicle health and pending proposals
   ${c.cyan("quorum check")} --outcome <x> --design <y>  Preflight + risk (no LLM)
@@ -116,6 +118,12 @@ async function cli() {
     return
   }
 
+  if (command === "llm") {
+    const { run } = await import(path.join(__dirname, "commands/llm.js"))
+    await run(rest)
+    return
+  }
+
   if (command === "init") {
     const { run } = await import(path.join(__dirname, "commands/init.js"))
     await run(PKG_VERSION)

package/bin/shared/llm.js

@@ -11,10 +11,12 @@ const execAsync = promisify(exec)
  * Detection order (highest priority first):
  *   1. ANTHROPIC_API_KEY            → Anthropic Claude
  *   2. OPENAI_API_KEY               → OpenAI (or compatible via OPENAI_BASE_URL)
- *   3. GEMINI_API_KEY               → Google Gemini (API)
- *   4. OPENAI_BASE_URL (no key)     → OpenAI-compatible endpoint (Azure, Groq, etc.)
- *   5. OLLAMA_HOST / localhost:11434 → Ollama (probed in parallel with the above)
- *   6. gemini CLI in PATH           → Google Gemini (CLI subprocess)
+ *   3. OPENAI_BASE_URL (no key)     → OpenAI-compatible endpoint (Azure, Groq, etc.)
+ *   4. GEMINI_API_KEY               → Google Gemini (API)
+ *   5. claude CLI in PATH           → Claude Code (CLI subprocess, --print mode)
+ *   6. copilot CLI in PATH          → GitHub Copilot CLI (-p / --prompt mode)
+ *   7. gemini CLI in PATH           → Google Gemini (CLI subprocess)
+ *   8. OLLAMA_HOST / localhost:11434 → Ollama (last resort — local models)
  *
  * All detected providers are tried in order. A 429 / quota / rate-limit error
  * from one provider causes a silent fallback to the next rather than a hard
@@ -39,8 +41,10 @@ export async function detectProvider() {
  */
 async function gatherCandidates() {
   // Probe async sources concurrently
-  const [ollamaModel, geminiCLIAvail] = await Promise.all([
+  const [ollamaModel, claudeCLIAvail, copilotCLIAvail, geminiCLIAvail] = await Promise.all([
     probeOllama(process.env.OLLAMA_HOST || "http://localhost:11434"),
+    probeClaudeCLI(),
+    probeCopilotCLI(),
     probeGeminiCLI(),
   ])
 
@@ -77,11 +81,17 @@ async function gatherCandidates() {
     })
   }
 
-  if (ollamaModel) {
-    const host = process.env.OLLAMA_HOST || "http://localhost:11434"
+  if (claudeCLIAvail) {
     candidates.push({
-      llm:  createOpenAICompatProvider("", `${host}/v1`, ollamaModel),
-      name: `Ollama (${ollamaModel})`,
+      llm:  createClaudeCLIProvider(),
+      name: "Claude Code CLI",
+    })
+  }
+
+  if (copilotCLIAvail) {
+    candidates.push({
+      llm:  createCopilotCLIProvider(),
+      name: "Copilot CLI",
     })
   }
 
@@ -92,6 +102,15 @@ async function gatherCandidates() {
     })
   }
 
+  // Ollama is last — local models are the slowest fallback
+  if (ollamaModel) {
+    const host = process.env.OLLAMA_HOST || "http://localhost:11434"
+    candidates.push({
+      llm:  createOpenAICompatProvider("", `${host}/v1`, ollamaModel),
+      name: `Ollama (${ollamaModel})`,
+    })
+  }
+
   return candidates
 }
 
@@ -139,6 +158,113 @@ export async function detectLLMName() {
   return (await detectProvider())?.name ?? null
 }
 
+/**
+ * Probe all providers and return a priority-ordered status array suitable for
+ * display (e.g. quorum llm). Each entry:
+ *   { id, name, detected: bool, note: string|null }
+ * 'detected' = true  → provider is ready to use right now
+ * 'note'            → setup hint when not detected, or detail when detected
+ */
+export async function probeAll() {
+  // Run async probes in parallel
+  const [ollamaModel, claudeDetail, copilotDetail, geminiDetail] = await Promise.all([
+    probeOllama(process.env.OLLAMA_HOST || "http://localhost:11434"),
+    probeCliDetail("claude", async () => {
+      const { platform } = await import("os")
+      if (platform() === "darwin") {
+        await execAsync("security find-generic-password -s 'Claude Code-credentials' 2>/dev/null")
+        return true
+      }
+      const { readdir } = await import("fs/promises")
+      const { homedir } = await import("os")
+      const sessions = await readdir(path.join(homedir(), ".claude", "sessions")).catch(() => [])
+      return sessions.length > 0
+    }),
+    probeCliDetail("copilot", async () => {
+      const { readdir } = await import("fs/promises")
+      const { homedir } = await import("os")
+      const sessions = await readdir(path.join(homedir(), ".copilot", "session-state")).catch(() => [])
+      return sessions.length > 0
+    }),
+    probeCliDetail("gemini", async () => {
+      if (process.env.GOOGLE_GENAI_USE_VERTEXAI || process.env.GOOGLE_APPLICATION_CREDENTIALS) return true
+      const { readFile } = await import("fs/promises")
+      const { homedir } = await import("os")
+      const raw = await readFile(path.join(homedir(), ".gemini", "settings.json"), "utf8")
+      return !!JSON.parse(raw).selectedAuthType
+    }),
+  ])
+
+  const hasOpenAIKey  = !!process.env.OPENAI_API_KEY
+  const hasOpenAIBase = !!process.env.OPENAI_BASE_URL
+  let openAIName = "OpenAI API"
+  if (hasOpenAIBase && !hasOpenAIKey) {
+    try { openAIName = `OpenAI-compatible (${new URL(process.env.OPENAI_BASE_URL).hostname})` } catch { /**/ }
+  }
+
+  return [
+    {
+      id:       "anthropic",
+      name:     "Anthropic API",
+      detected: !!process.env.ANTHROPIC_API_KEY,
+      note:     process.env.ANTHROPIC_API_KEY ? null : "export ANTHROPIC_API_KEY=sk-ant-…",
+    },
+    {
+      id:       "openai",
+      name:     openAIName,
+      detected: hasOpenAIKey || hasOpenAIBase,
+      note:     hasOpenAIKey || hasOpenAIBase ? null : "export OPENAI_API_KEY=sk-…",
+    },
+    {
+      id:       "gemini-api",
+      name:     "Gemini API",
+      detected: !!process.env.GEMINI_API_KEY,
+      note:     process.env.GEMINI_API_KEY ? null : "export GEMINI_API_KEY=…",
+    },
+    {
+      id:       "claude-cli",
+      name:     "Claude Code CLI",
+      detected: claudeDetail.authed,
+      note:     claudeDetail.authed    ? null
+              : claudeDetail.inPath    ? "found in PATH but not signed in — run: claude"
+              :                          "install from claude.ai/code, then sign in once",
+    },
+    {
+      id:       "copilot-cli",
+      name:     "Copilot CLI",
+      detected: copilotDetail.authed,
+      note:     copilotDetail.authed   ? null
+              : copilotDetail.inPath   ? "found but no session — open VS Code and sign into Copilot Chat"
+              :                          "install VS Code + GitHub Copilot Chat extension",
+    },
+    {
+      id:       "gemini-cli",
+      name:     "Gemini CLI",
+      detected: geminiDetail.authed,
+      note:     geminiDetail.authed    ? null
+              : geminiDetail.inPath    ? "found but not authenticated — run: gemini auth"
+              :                          "npm install -g @google/gemini-cli, then: gemini auth",
+    },
+    {
+      id:       "ollama",
+      name:     "Ollama",
+      detected: !!ollamaModel,
+      note:     ollamaModel ?? "run: ollama serve  (then: ollama pull llama3.2)",
+    },
+  ]
+}
+
+/**
+ * Probe a CLI binary — returns { inPath, authed }.
+ * authCheck is called only when the binary is found; errors are treated as "not authed".
+ */
+async function probeCliDetail(binary, authCheck) {
+  let inPath = false
+  try { await execAsync(`which ${binary}`); inPath = true } catch { /**/ }
+  if (!inPath) return { inPath: false, authed: false }
+  try { const authed = await authCheck(); return { inPath: true, authed: !!authed } } catch { return { inPath: true, authed: false } }
+}
+
 // ── Probe Ollama ───────────────────────────────────────────────────────────────
 
 async function probeOllama(host) {
@@ -236,6 +362,115 @@ function createGeminiProvider(apiKey) {
   }
 }
 
+async function probeClaudeCLI() {
+  // Must be in PATH
+  try {
+    await execAsync("which claude")
+  } catch {
+    return false
+  }
+
+  // Must have an active session — Claude Code stores OAuth tokens in the macOS keychain.
+  // A quick smoke-test is cheaper than shelling out; check the keychain entry exists.
+  // On non-macOS, fall back to checking ~/.claude/sessions/ for any session file.
+  try {
+    const { platform } = await import("os")
+    if (platform() === "darwin") {
+      await execAsync("security find-generic-password -s 'Claude Code-credentials' 2>/dev/null")
+      return true
+    }
+    // Non-macOS: check for at least one session file
+    const { readdir } = await import("fs/promises")
+    const { homedir } = await import("os")
+    const sessions = await readdir(path.join(homedir(), ".claude", "sessions")).catch(() => [])
+    return sessions.length > 0
+  } catch {
+    return false
+  }
+}
+
+function createClaudeCLIProvider() {
+  return function llm(messages) {
+    return new Promise((resolve, reject) => {
+      const system      = messages.find(m => m.role === "system")?.content ?? ""
+      const userContent = messages.filter(m => m.role !== "system").map(m => m.content).join("\n\n")
+
+      // Combine system + user into one prompt piped via stdin; --print for non-interactive output.
+      // Do NOT use --bare — that disables keychain OAuth and requires ANTHROPIC_API_KEY instead.
+      const fullPrompt = system ? `${system}\n\n${userContent}` : userContent
+      const child = spawn("claude", ["--print", "--output-format", "text"], { stdio: ["pipe", "pipe", "pipe"] })
+
+      let out = "", err = ""
+      child.stdout.on("data", d => { out += d })
+      child.stderr.on("data", d => { err += d })
+      child.on("error", reject)
+      child.on("close", code => {
+        if (code === 0) resolve(out.trim())
+        else reject(new Error(`claude CLI exited ${code}: ${err.slice(0, 200)}`))
+      })
+      child.stdin.write(fullPrompt)
+      child.stdin.end()
+    })
+  }
+}
+
+async function probeCopilotCLI() {
+  // Must be in PATH (VS Code installs a shell wrapper into PATH automatically)
+  try {
+    await execAsync("which copilot")
+  } catch {
+    return false
+  }
+
+  // Must have at least one session in ~/.copilot/session-state/ — created after first auth
+  try {
+    const { readdir } = await import("fs/promises")
+    const { homedir } = await import("os")
+    const sessions = await readdir(path.join(homedir(), ".copilot", "session-state")).catch(() => [])
+    return sessions.length > 0
+  } catch {
+    return false
+  }
+}
+
+function createCopilotCLIProvider() {
+  return function llm(messages) {
+    return new Promise((resolve, reject) => {
+      const system      = messages.find(m => m.role === "system")?.content ?? ""
+      const userContent = messages.filter(m => m.role !== "system").map(m => m.content).join("\n\n")
+      const fullPrompt  = system ? `${system}\n\n${userContent}` : userContent
+
+      // Use --output-format json so we can parse the JSONL event stream reliably
+      const child = spawn("copilot", ["-p", fullPrompt, "--output-format", "json"], {
+        stdio: ["ignore", "pipe", "pipe"],
+      })
+
+      let out = "", err = ""
+      child.stdout.on("data", d => { out += d })
+      child.stderr.on("data", d => { err += d })
+      child.on("error", reject)
+      child.on("close", code => {
+        if (code !== 0) {
+          return reject(new Error(`copilot CLI exited ${code}: ${err.slice(0, 200)}`))
+        }
+        // Parse JSONL stream — find the assistant.message event
+        const content = out.split("\n")
+          .filter(Boolean)
+          .reduce((found, line) => {
+            if (found) return found
+            try {
+              const evt = JSON.parse(line)
+              if (evt.type === "assistant.message" && evt.data?.content) return evt.data.content
+            } catch { /* skip non-JSON lines */ }
+            return null
+          }, null)
+        if (content == null) return reject(new Error("copilot CLI: no assistant.message event in output"))
+        resolve(content)
+      })
+    })
+  }
+}
+
 async function probeGeminiCLI() {
   try {
     await execAsync("which gemini")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@balpal4495/quorum",
-  "version": "3.5.0",
+  "version": "3.6.0",
   "description": "Git-backed memory and design review for AI coding agents",
   "type": "module",
   "license": "MIT",