@chamba/claude-extras 0.1.0 → 0.2.0

package/README.md

@@ -26,6 +26,97 @@ existing files and preserves any other MCP servers.
 
 Then, in Claude Code: `/orq add a health check endpoint`
 
+## Configuration: per-agent model + effort
+
+chamba lets you pick which **model** and **effort** each **role** uses
+(orchestrator, planner, reviewer, implementer, tester, summarizer, researcher).
+
+> **chamba never calls these models.** This config is declarative metadata. For
+> Claude Code it's written into each subagent's frontmatter (`model:` + `effort:`)
+> in `~/.claude/agents/*.md`; Claude Code is what runs the model. Other editors read
+> the same config through the MCP tool `chamba_get_agent_config`. No API keys, ever.
+
+### The recommended defaults (and why)
+
+The philosophy: **critical reasoning gets powerful models, mechanical execution gets
+fast/cheap ones.** These ship pre-configured — you only change what you want.
+
+| Role | Default model | Effort | Why |
+|---|---|---|---|
+| **orchestrator** | `claude-opus-4-8` | high | The brain: decomposes, plans, decides. Worth the tokens. |
+| **planner** | `claude-opus-4-8` | extreme | Max reasoning when planning is delegated. Invoked rarely. |
+| **reviewer** | `claude-opus-4-7` | high | Critical audit; deep reasoning, doesn't need the very latest model. |
+| **implementer** | `claude-sonnet-4-6` | medium | Executes clear specs; speed matters, medium reasoning is enough. |
+| **tester** | `claude-sonnet-4-6` | medium | Tests over already-implemented code; same profile. |
+| **summarizer** | `claude-haiku-4-5` | low | Summaries are mechanical; a fast, cheap model is perfect. |
+| **researcher** | `claude-opus-4-7` | high | Research + synthesis; high reasoning, doesn't need Opus 4.8. |
+
+### The wizard
+
+The first `install` offers an interactive wizard (skipped automatically with
+`--defaults` or in non-TTY/CI environments — defaults apply, install never blocks):
+
+```text
+chamba per-agent config
+Pick which model + effort each role uses. …
+
+? Use the recommended defaults? (No lets you customize each role) (Y/n)
+```
+
+Pick **Yes** to take the table above, or **No** to choose a model + effort for each
+role. Cancelling (Ctrl+C) installs the defaults anyway.
+
+### Reconfigure anytime
+
+```bash
+npx @chamba/claude-extras config show                  # resolved config + where each value comes from
+npx @chamba/claude-extras config models                # list available models
+npx @chamba/claude-extras config set tester claude-haiku-4-5 --effort low
+npx @chamba/claude-extras config apply                 # regenerate ~/.claude/agents from the config
+npx @chamba/claude-extras config wizard                # re-run the wizard
+npx @chamba/claude-extras config reset --yes           # back to defaults
+npx @chamba/claude-extras config edit                  # open ~/.chamba/config.json in $EDITOR
+```
+
+### Override per project
+
+`~/.chamba/config.json` is your global config; a `./.chamba/config.json` in a repo
+overrides it **per role and per field**. Example — use a cheaper reviewer in one repo:
+
+```json
+{ "version": 1, "overrides": { "reviewer": { "model": "claude-sonnet-4-6" } } }
+```
+
+Every other role still falls back to your global config, then to the defaults.
+
+### How `effort` maps per provider
+
+`effort` is provider-neutral (`low | medium | high | extreme`); chamba translates it:
+
+| `effort` | Claude Code | OpenAI (`reasoning_effort`) | Gemini (`thinkingLevel`) | Ollama |
+|---|---|---|---|---|
+| low | low | low | low | n/a (model-defined) |
+| medium | medium | medium | medium | n/a |
+| high | high | high | high | n/a |
+| extreme | **max** | **xhigh** | high | n/a |
+
+The subagent frontmatter always uses Claude Code's vocabulary, so `extreme` → `max`.
+If you set a **non-Anthropic** model for a Claude Code subagent, Claude Code can't run
+it, so `model:` is omitted (the subagent inherits the session model) and a comment
+records why — the config still drives every other editor through the MCP tool.
+
+### FAQ
+
+- **Why so many different models?** Different roles need different things. Spending
+  Opus-tier reasoning on a one-line summary is waste; using Haiku to plan an
+  architecture is a false economy. The defaults encode that trade-off.
+- **How do I change one role without re-running the wizard?**
+  `config set <role> <model> [--effort <level>]`, then `config apply`.
+- **What if my config gets corrupted?** chamba degrades to the compiled defaults and
+  surfaces a warning (`config show` marks the source as `IGNORED`). Nothing breaks.
+- **Why does `extreme` become `max` in Claude Code?** Claude Code's effort scale tops
+  out at `max`; `extreme` is chamba's name for "the ceiling".
+
 ## License
 
 MIT

package/dist/cli.js

@@ -1,11 +1,122 @@
 // src/cli.ts
+import { homedir as homedir2 } from "os";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { NodeFilesystem as NodeFilesystem2 } from "@chamba/adapters";
+import { joinPath as joinPath3 } from "@chamba/core";
+
+// src/config-cli.ts
+import { spawnSync } from "child_process";
 import { homedir } from "os";
 import { fileURLToPath } from "url";
 import { NodeFilesystem } from "@chamba/adapters";
-import { joinPath as joinPath2 } from "@chamba/core";
+import {
+  AGENT_ROLES as AGENT_ROLES2,
+  ConfigError as ConfigError2,
+  joinPath as joinPath2,
+  loadConfig as loadConfig2,
+  MODEL_CATALOG as MODEL_CATALOG2
+} from "@chamba/core";
+import { confirm as confirm2 } from "@inquirer/prompts";
+
+// src/config-store.ts
+import { ConfigError, DEFAULT_CONFIG, dirname, parseChambaConfig } from "@chamba/core";
+var ConfigStore = class {
+  constructor(fs, path) {
+    this.fs = fs;
+    this.path = path;
+  }
+  fs;
+  path;
+  /** The current file, or an empty `{ version: 1 }` if it doesn't exist. */
+  async read() {
+    if (!await this.fs.exists(this.path)) return { version: 1 };
+    let raw;
+    try {
+      raw = JSON.parse(await this.fs.readFile(this.path));
+    } catch (e) {
+      throw new ConfigError(`invalid JSON in ${this.path}: ${e.message}`);
+    }
+    const parsed = parseChambaConfig(raw);
+    if (!parsed.ok) throw new ConfigError(`invalid config in ${this.path}: ${parsed.error}`);
+    return parsed.value;
+  }
+  async write(config) {
+    await this.fs.mkdir(dirname(this.path));
+    await this.fs.writeFile(this.path, `${JSON.stringify(config, null, 2)}
+`);
+  }
+  /** Merge a single role's patch into `overrides` and persist (validated). */
+  async setRole(role, patch) {
+    const current = await this.read();
+    const overrides = { ...current.overrides ?? {} };
+    overrides[role] = { ...overrides[role] ?? {}, ...patch };
+    const next = { ...current, version: 1, overrides };
+    const parsed = parseChambaConfig(next);
+    if (!parsed.ok) throw new ConfigError(parsed.error);
+    await this.write(parsed.value);
+    return parsed.value;
+  }
+  /** Write the compiled defaults as the full config. */
+  async reset() {
+    await this.write({ version: 1, defaults: DEFAULT_CONFIG.defaults });
+  }
+  get filePath() {
+    return this.path;
+  }
+};
+
+// src/installer.ts
+import { joinPath, loadConfig } from "@chamba/core";
+
+// src/agent-frontmatter.ts
+import { getModel } from "@chamba/core";
+var AGENT_ROLE_BY_FILE = {
+  "implementer.md": "implementer",
+  "reviewer.md": "reviewer",
+  "tester.md": "tester"
+};
+var CLAUDE_CODE_EFFORT = {
+  low: "low",
+  medium: "medium",
+  high: "high",
+  extreme: "max"
+};
+function parseAgentMarkdown(text) {
+  const fm = text.match(/^---\n([\s\S]*?)\n---\n?/);
+  const meta = {};
+  if (fm?.[1]) {
+    for (const line of fm[1].split("\n")) {
+      const m = line.match(/^(\w+):\s*(.*)$/);
+      if (m?.[1]) meta[m[1]] = (m[2] ?? "").trim();
+    }
+  }
+  const body = fm ? text.slice(fm[0].length) : text;
+  return {
+    name: meta.name ?? "",
+    description: meta.description ?? "",
+    body: body.trim()
+  };
+}
+function renderAgentMarkdown(parsed, cfg) {
+  const model = getModel(cfg.model);
+  const isAnthropic = model?.provider === "anthropic";
+  const effort = CLAUDE_CODE_EFFORT[cfg.effort];
+  const lines = ["---", `name: ${parsed.name}`, `description: ${parsed.description}`];
+  if (isAnthropic) {
+    lines.push(`model: ${cfg.model}`);
+  } else {
+    lines.push(
+      `# requested model '${cfg.model}' is not an Anthropic model; Claude Code uses the session model (inherit)`
+    );
+  }
+  lines.push(`effort: ${effort}`, "---");
+  return `${lines.join("\n")}
+
+${parsed.body}
+`;
+}
 
 // src/installer.ts
-import { joinPath } from "@chamba/core";
 var CATEGORIES = [
   { dir: "commands", label: "slash commands" },
   { dir: "agents", label: "subagents" },
@@ -18,6 +129,7 @@ var Installer = class {
     this.opts = opts;
   }
   opts;
+  cachedConfig;
   /** True if Claude Code seems present (a config dir or file already exists). */
   async detectClaudeCode() {
     return await this.opts.fs.exists(this.opts.claudeDir) || await this.opts.fs.exists(this.opts.claudeJsonPath);
@@ -38,7 +150,7 @@ var Installer = class {
           skipped.push(`${dir}/${name}`);
           continue;
         }
-        const content = await this.opts.fs.readFile(joinPath(this.opts.assetsDir, dir, name));
+        const content = await this.materialize(dir, name);
         await this.opts.fs.writeFile(target, content);
         installed.push(`${dir}/${name}`);
         counts[dir] = (counts[dir] ?? 0) + 1;
@@ -62,6 +174,53 @@ var Installer = class {
     const mcpRemoved = await this.removeMcpServer();
     return { removed, mcpRemoved };
   }
+  /**
+   * Regenerate the subagent files in `~/.claude/agents/` from the current
+   * config. Idempotent: a file whose rendered content is unchanged is left
+   * untouched. Only role-mapped subagents are (re)generated.
+   */
+  async applyConfig() {
+    const regenerated = [];
+    const unchanged = [];
+    const targetDir = joinPath(this.opts.claudeDir, "agents");
+    await this.opts.fs.mkdir(targetDir);
+    for (const name of await this.assetNames("agents")) {
+      if (!AGENT_ROLE_BY_FILE[name]) continue;
+      const content = await this.materialize("agents", name);
+      const target = joinPath(targetDir, name);
+      if (await this.readIfExists(target) === content) {
+        unchanged.push(`agents/${name}`);
+        continue;
+      }
+      await this.opts.fs.writeFile(target, content);
+      regenerated.push(`agents/${name}`);
+    }
+    return { regenerated, unchanged };
+  }
+  /** Read an asset and, for role-mapped subagents, inject model + effort. */
+  async materialize(dir, name) {
+    const raw = await this.opts.fs.readFile(joinPath(this.opts.assetsDir, dir, name));
+    if (dir !== "agents") return raw;
+    const role = AGENT_ROLE_BY_FILE[name];
+    if (!role) return raw;
+    const config = await this.resolveConfig();
+    return renderAgentMarkdown(parseAgentMarkdown(raw), config[role]);
+  }
+  async resolveConfig() {
+    if (!this.cachedConfig) {
+      const { config } = await loadConfig(this.opts.fs, { globalPath: this.opts.globalConfigPath });
+      this.cachedConfig = config;
+    }
+    return this.cachedConfig;
+  }
+  async readIfExists(path) {
+    try {
+      if (!await this.opts.fs.exists(path)) return null;
+      return await this.opts.fs.readFile(path);
+    } catch {
+      return null;
+    }
+  }
   async assetNames(dir) {
     try {
       const entries = await this.opts.fs.readDir(joinPath(this.opts.assetsDir, dir));
@@ -106,15 +265,233 @@ function asRecord(value) {
   return typeof value === "object" && value !== null ? value : null;
 }
 
-// src/cli.ts
-function buildInstaller() {
+// src/wizard.ts
+import {
+  AGENT_ROLES,
+  DEFAULT_CONFIG as DEFAULT_CONFIG2,
+  EFFORT_LEVELS,
+  MODEL_CATALOG,
+  ROLE_DESCRIPTIONS
+} from "@chamba/core";
+import { confirm, select } from "@inquirer/prompts";
+function defaultConfigFile() {
+  return { version: 1, defaults: DEFAULT_CONFIG2.defaults };
+}
+function buildConfigFromAnswers(answers) {
+  const defaults = {};
+  for (const role of AGENT_ROLES) {
+    const answer = answers.find((a) => a.role === role);
+    const base = DEFAULT_CONFIG2.defaults[role];
+    defaults[role] = answer ? { model: answer.model, effort: answer.effort, reasoning_priority: base.reasoning_priority } : base;
+  }
+  return { version: 1, defaults };
+}
+function modelChoices() {
+  return MODEL_CATALOG.map((m) => ({
+    name: `${m.label} \u2014 ${m.description}`,
+    value: m.id
+  }));
+}
+function effortChoices() {
+  return EFFORT_LEVELS.map((e) => ({ name: e, value: e }));
+}
+function isCancellation(e) {
+  return e instanceof Error && e.name === "ExitPromptError";
+}
+async function runWizard(opts = {}) {
+  if (opts.nonInteractive) return defaultConfigFile();
+  try {
+    process.stdout.write(
+      "chamba per-agent config\nPick which model + effort each role uses. chamba never calls these models \u2014\nthis only tells your editor's model how to delegate. You can change it later\nwith `npx @chamba/claude-extras config`.\n\n"
+    );
+    const useDefaults = await confirm({
+      message: "Use the recommended defaults? (No lets you customize each role)",
+      default: true
+    });
+    if (useDefaults) return defaultConfigFile();
+    const answers = [];
+    for (const role of AGENT_ROLES) {
+      const model = await select({
+        message: `${role} \u2014 ${ROLE_DESCRIPTIONS[role]}`,
+        choices: modelChoices(),
+        default: DEFAULT_CONFIG2.defaults[role].model
+      });
+      const effort = await select({
+        message: `  effort for ${role}`,
+        choices: effortChoices(),
+        default: DEFAULT_CONFIG2.defaults[role].effort
+      });
+      answers.push({ role, model, effort });
+    }
+    process.stdout.write("\nSummary:\n");
+    for (const a of answers) {
+      process.stdout.write(`  ${a.role.padEnd(13)} ${a.model}  \xB7  ${a.effort}
+`);
+    }
+    const ok = await confirm({ message: "Write this config?", default: true });
+    return ok ? buildConfigFromAnswers(answers) : null;
+  } catch (e) {
+    if (isCancellation(e)) return null;
+    throw e;
+  }
+}
+
+// src/config-cli.ts
+var CONFIG_RELATIVE = ".chamba/config.json";
+function globalConfigPath() {
+  return joinPath2(homedir(), CONFIG_RELATIVE);
+}
+function projectConfigPath() {
+  return joinPath2(process.cwd(), CONFIG_RELATIVE);
+}
+function formatModels() {
+  const lines = ["Available models:"];
+  for (const m of MODEL_CATALOG2) {
+    const thinking = m.supports_thinking ? "thinking" : "no-thinking";
+    lines.push(`  ${m.id.padEnd(24)} ${m.provider.padEnd(10)} ${thinking}  \u2014 ${m.description}`);
+  }
+  return lines.join("\n");
+}
+async function formatShow(fs, paths) {
+  const { config, sources } = await loadConfig2(fs, paths);
+  const lines = ["role           model                     effort    priority"];
+  for (const role of AGENT_ROLES2) {
+    const c = config[role];
+    lines.push(
+      `${role.padEnd(15)}${c.model.padEnd(26)}${c.effort.padEnd(10)}${c.reasoning_priority}`
+    );
+  }
+  lines.push("");
+  for (const s of sources) {
+    const where = s.path ? ` (${s.path})` : "";
+    const note = s.status === "invalid" ? ` \u2014 IGNORED: ${s.error}` : "";
+    lines.push(`source: ${s.kind} [${s.status}]${where}${note}`);
+  }
+  return lines.join("\n");
+}
+async function cmdSet(store, args) {
+  if (!AGENT_ROLES2.includes(args.role)) {
+    throw new ConfigError2(`unknown role '${args.role}'; valid roles: ${AGENT_ROLES2.join(", ")}`);
+  }
+  const patch = { model: args.model };
+  if (args.effort !== void 0) patch.effort = args.effort;
+  await store.setRole(args.role, patch);
+  const effortNote = args.effort ? ` with effort ${args.effort}` : "";
+  return `Set ${args.role} \u2192 ${args.model}${effortNote}. Run 'config apply' to regenerate subagents.`;
+}
+function buildInstaller(fs) {
   const home = homedir();
   const assetsDir = fileURLToPath(new URL("../assets", import.meta.url));
   return new Installer({
-    fs: new NodeFilesystem(),
+    fs,
     assetsDir,
     claudeDir: joinPath2(home, ".claude"),
-    claudeJsonPath: joinPath2(home, ".claude.json")
+    claudeJsonPath: joinPath2(home, ".claude.json"),
+    globalConfigPath: globalConfigPath()
+  });
+}
+function parseEffortFlag(rest) {
+  const i = rest.indexOf("--effort");
+  return i >= 0 ? rest[i + 1] : void 0;
+}
+var USAGE = "Usage: chamba-install config <show|models|set|reset|wizard|apply|edit>\n  show                                   resolved config + where each value comes from\n  models                                 list the available models\n  set <role> <model> [--effort <level>]  change one role\n  reset [--yes]                          restore defaults\n  wizard [--defaults]                    (re)run the interactive wizard\n  apply                                  regenerate ~/.claude/agents from the config\n  edit                                   open the config in $EDITOR\n";
+async function runConfigCommand(args) {
+  const [command, ...rest] = args;
+  const fs = new NodeFilesystem();
+  const store = new ConfigStore(fs, globalConfigPath());
+  try {
+    switch (command) {
+      case "show":
+        process.stdout.write(
+          `${await formatShow(fs, { globalPath: globalConfigPath(), projectPath: projectConfigPath() })}
+`
+        );
+        return;
+      case "models":
+        process.stdout.write(`${formatModels()}
+`);
+        return;
+      case "set": {
+        const [role, model] = rest;
+        if (!role || !model) {
+          process.stderr.write("Usage: config set <role> <model> [--effort <level>]\n");
+          process.exitCode = 1;
+          return;
+        }
+        process.stdout.write(
+          `${await cmdSet(store, { role, model, effort: parseEffortFlag(rest) })}
+`
+        );
+        return;
+      }
+      case "reset": {
+        const confirmed = rest.includes("--yes") || await confirm2({ message: "Reset config to defaults?", default: false });
+        if (!confirmed) {
+          process.stdout.write("Cancelled.\n");
+          return;
+        }
+        await store.reset();
+        process.stdout.write(`Reset config to defaults at ${store.filePath}.
+`);
+        return;
+      }
+      case "wizard": {
+        const config = await runWizard({ nonInteractive: rest.includes("--defaults") });
+        if (!config) {
+          process.stdout.write("Wizard cancelled. Config unchanged.\n");
+          return;
+        }
+        await store.write(config);
+        await buildInstaller(fs).applyConfig();
+        process.stdout.write(`Wrote ${store.filePath} and regenerated subagents.
+`);
+        return;
+      }
+      case "apply": {
+        const result = await buildInstaller(fs).applyConfig();
+        process.stdout.write(
+          `Applied config: ${result.regenerated.length} regenerated, ${result.unchanged.length} unchanged.
+`
+        );
+        return;
+      }
+      case "edit": {
+        const editor = process.env.EDITOR;
+        if (!await fs.exists(store.filePath)) await store.reset();
+        if (!editor) {
+          process.stdout.write(`No $EDITOR set. Edit this file directly:
+${store.filePath}
+`);
+          return;
+        }
+        spawnSync(editor, [store.filePath], { stdio: "inherit" });
+        return;
+      }
+      default:
+        process.stderr.write(USAGE);
+        process.exitCode = command ? 1 : 0;
+    }
+  } catch (err) {
+    if (err instanceof ConfigError2) {
+      process.stderr.write(`config error: ${err.message}
+`);
+      process.exitCode = 1;
+      return;
+    }
+    throw err;
+  }
+}
+
+// src/cli.ts
+function buildInstaller2() {
+  const home = homedir2();
+  const assetsDir = fileURLToPath2(new URL("../assets", import.meta.url));
+  return new Installer({
+    fs: new NodeFilesystem2(),
+    assetsDir,
+    claudeDir: joinPath3(home, ".claude"),
+    claudeJsonPath: joinPath3(home, ".claude.json"),
+    globalConfigPath: joinPath3(home, ".chamba/config.json")
   });
 }
 function summarize(result) {
@@ -138,28 +515,56 @@ function labelFor(dir) {
 }
 async function main() {
   const [command, ...rest] = process.argv.slice(2);
-  const installer = buildInstaller();
+  const installer = buildInstaller2();
   if (command === "uninstall") {
     const result = await installer.uninstall();
     process.stdout.write(
       `Removed ${result.removed.length} file(s). ${result.mcpRemoved ? "Removed" : "Did not find"} chamba MCP server in ~/.claude.json
+`
+    );
+    return;
+  }
+  if (command === "config") {
+    await runConfigCommand(rest);
+    return;
+  }
+  if (command === "apply") {
+    const result = await installer.applyConfig();
+    process.stdout.write(
+      `Applied config: ${result.regenerated.length} subagent(s) regenerated, ${result.unchanged.length} unchanged.
 `
     );
     return;
   }
   if (command === void 0 || command === "install") {
     const force = rest.includes("--force");
+    await maybeRunWizard(rest);
     const result = await installer.install({ force });
     process.stdout.write(`${summarize(result)}
 `);
     return;
   }
   process.stderr.write(
-    `Unknown command "${command}". Usage: chamba-install [install|uninstall] [--force]
+    `Unknown command "${command}". Usage: chamba-install [install|uninstall|apply|config <sub>] [--force]
 `
   );
   process.exitCode = 1;
 }
+async function maybeRunWizard(rest) {
+  const fs = new NodeFilesystem2();
+  const configPath = joinPath3(homedir2(), ".chamba/config.json");
+  if (await fs.exists(configPath)) return;
+  const nonInteractive = rest.includes("--defaults") || !process.stdin.isTTY;
+  if (nonInteractive) return;
+  const config = await runWizard();
+  if (!config) {
+    process.stdout.write(
+      "Wizard skipped \u2014 using recommended defaults. Run `npx @chamba/claude-extras config wizard` anytime.\n"
+    );
+    return;
+  }
+  await new ConfigStore(fs, configPath).write(config);
+}
 main().catch((err) => {
   process.stderr.write(`chamba-install failed: ${err.message}
 `);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chamba/claude-extras",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Optional Claude Code extras for chamba: slash commands, subagents and hooks installer",
   "license": "MIT",
   "type": "module",
@@ -30,8 +30,9 @@
     "hooks"
   ],
   "dependencies": {
-    "@chamba/adapters": "0.1.0",
-    "@chamba/core": "0.1.0"
+    "@inquirer/prompts": "^7.0.0",
+    "@chamba/adapters": "0.2.0",
+    "@chamba/core": "0.2.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",