forge-delegate 1.0.0

package/README.md

@@ -0,0 +1,185 @@
+# forge-delegate
+
+MCP server that delegates coding work from your primary agent (**Claude Code, Codex, or opencode**)
+to other — usually cheaper or free — AI models, so your main agent's context stays small and your
+token bill stays low. Direct API calls for quick questions; full agentic delegation via
+[opencode](https://opencode.ai) for real work.
+
+Your main agent (the expensive one) keeps architecture, critical logic, and hard decisions.
+The cheap model grinds through the high-volume, low-risk work (boilerplate, repetitive edits,
+tests, lint/type fixes) and reports back.
+
+```
+┌──────────────────┐   MCP (stdio)   ┌──────────────────┐   opencode run   ┌──────────────────┐
+│ Claude / Codex / │ ──────────────► │ forge-delegate   │ ───────────────► │ opencode + cheap  │
+│ opencode (primary)│                │  (this server)   │    --model cheap │      model        │
+└──────────────────┘ ◄────────────── └──────────────────┘ ◄─────────────── └──────────────────┘
+        result: text + session + token usage
+```
+
+## Quick start
+
+**Web configurator** — pick model/targets/scope and get a ready-to-paste command
+(https://muhamadbarzani.github.io/forge-delegate/). The model picker is backed by the live
+[models.dev](https://models.dev) catalog — searchable, with free/cheap filters and real prices,
+so you're picking from actual available models rather than guessing.
+
+**npx (recommended — works everywhere, no bash needed):**
+
+```bash
+npx -y forge-delegate setup --model "opencode/mimo-v2.5-free" --targets "claude,codex,opencode"
+```
+
+That's it — npx pulls the latest package and `setup` registers the MCP server with the agents
+you chose and sets your default model. Works on Windows (cmd/PowerShell), macOS, and Linux —
+no bash needed, and always runs the latest version.
+
+Run `setup` **without flags** and it walks you through the choices interactively (defaults in
+`[brackets]`, Enter accepts); pass any of the flags to skip that prompt. In an automated/non-terminal
+run it just uses sensible defaults.
+
+> GitHub Pages: enable it with *Settings → Pages → Deploy from a branch → `main` / `/docs`*.
+> The configurator lives at `docs/index.html`. `install.sh`'s `FORGE_DELEGATE_REPO` default
+> (and the raw URL inside it) matters only if you self-host the fallback installer.
+>
+> Working on a checkout yourself? `node cli.mjs setup` does the same thing.
+
+`setup` will:
+1. Register the MCP server with each agent you chose (`--targets claude,codex,opencode`).
+2. Set your default model (`--model`) so calls can omit `model`.
+
+Routing and cost-policy guidance is injected by the MCP server itself into the agent's context
+via MCP `instructions` — no memory-file (`CLAUDE.md`/`AGENTS.md`) editing needed.
+
+Then restart your agent and confirm the server is connected: `/mcp` in Claude Code,
+`codex mcp`, or `opencode`.
+
+### What you need
+
+- **Node.js ≥ 18** and **opencode** installed (the installer can fetch opencode for you).
+- **Free `opencode/*` models** (e.g. `opencode/mimo-v2.5-free`) need no auth — zero setup.
+- **Any other provider** (deepseek, openai, google, ollama, …) must be logged into **your**
+  opencode first — that's a step *you* do in your own opencode, not something forge-delegate
+  handles: `opencode auth login <provider>`. forge-delegate reuses your opencode's credentials
+  and never stores API keys. (Ollama needs no key, just the Ollama app running.)
+
+### Windows
+
+Use the `npx` route — no bash needed (works in cmd/PowerShell). Drop `codex` from `--targets`
+(Codex CLI isn't natively supported on Windows; use `--targets "claude,opencode"`).
+
+### Scope
+
+| `--scope` | Claude Code | Codex | opencode |
+|---|---|---|---|
+| `user` (default) | `~/.claude.json` — all projects | `~/.codex/config.toml` — all projects | `~/.config/opencode/opencode.json` — all projects |
+| `project` | `.mcp.json` in the project (needs one-time approval) | `.codex/config.toml` in the project (loads for trusted projects only) | `opencode.json` in the project |
+
+### Try it free — zero signup
+
+opencode ships free no-auth models under `opencode/`:
+
+```bash
+npx -y forge-delegate setup --model "opencode/mimo-v2.5-free" --targets "claude,codex"
+```
+
+Other free options: `opencode/hy3-free`, `opencode/nemotron-3.5-lightning-free`. Free tiers are
+rate-limited; switch anytime with `forge-delegate config set --model <m>`.
+
+## Tools
+
+| Tool | What it does | Context cost |
+|---|---|---|
+| `ask_model` | One-shot question to any model (direct API, no file access) | Small |
+| `delegate_task` | Send a task + optional files to a model agent running via opencode; returns result + session id | Medium |
+| `delegate_agent` | Model works **autonomously** in the **background** — returns a job id instantly; poll `check_delegation` | Tiny |
+| `check_delegation` | Poll a background job (or list all with no id) | Tiny |
+| `list_models` | List local/keyless, direct-API, and agentic models | Small |
+| `get_delegate_config` | Read current configuration (default model, directory, autoApprove, profiles) | Tiny |
+| `set_delegate_config` | Change configuration at runtime — no reinstall | Tiny |
+
+`delegate_agent` is the token-saver: the external model gets its own tool loop executed by
+opencode locally. File contents never touch your main agent's context. The delegation runs as a
+detached background process, so the MCP call returns instantly.
+
+## When to delegate
+
+| ✅ Delegate — high volume, low risk | ⛔ Keep on the primary agent |
+|---|---|
+| Tests for well-specified behavior | Architecture, system design, choosing abstractions |
+| Boilerplate & scaffolding (CRUD, DTOs, fixtures, mocks) | Security-sensitive code (auth, crypto, secrets, permissions) |
+| Mechanical edits across many files (renames, prop propagation, imports) | Concurrency, performance-critical paths, subtle correctness |
+| Lint / formatting / type-error fixes | Ambiguous / underspecified requirements needing judgment |
+| Docstrings, comments, README / changelog sections | Public API / interface design, breaking changes |
+| Straightforward data transforms / migrations with a clear spec | Debugging unknown root causes |
+| Obvious glue code / format conversions | Anything costly or hard to detect if wrong |
+
+Full guide: [docs/DELEGATION.md](docs/DELEGATION.md)
+
+## Configuration
+
+Stored in `~/.forge-delegate/config.json`, read fresh on every call — change it anytime without
+reinstalling. Four ways:
+
+1. **From your agent** via the MCP tools `get_delegate_config` / `set_delegate_config`.
+2. **Terminal CLI**: `forge-delegate config get`, `forge-delegate config set --model <m> --timeout <s> --dir <path> --autoApprove false`, `forge-delegate config path`.
+3. **`setup` flags**: `--model`, `--targets`, `--scope`, `--project-dir`.
+4. **Edit the file** directly.
+
+| Field | Description | Default |
+|---|---|---|
+| `defaultModel` | provider/model used when a call omits `model` | unset |
+| `defaultAgent` | opencode agent used for delegations | unset |
+| `defaultVariant` | default reasoning-effort variant | unset |
+| `autoApprove` | auto-approve permissions so headless delegations don't block | `true` |
+| `timeoutMs` | per-delegation timeout | `900000` (env `FORGE_OPENCODE_TIMEOUT`) |
+| `defaultDirectory` | default working directory for delegations | unset (server cwd) |
+| `profiles` | named presets `{ name: { model, agent, variant, autoApprove, directory } }` | `{}` |
+
+Every delegation tool also accepts per-call `model`, `directory`, `agent`, `autoApprove`, and
+`profile` overrides. Per-call values beat profile values beat config defaults.
+
+## Models
+
+- **opencode provider** — free no-auth models (`opencode/mimo-v2.5-free`, ...) plus
+  anything you have logged in via `opencode auth login <provider>`.
+- **Direct API from opencode logins** — `provider/model` for OpenAI-compatible providers.
+- **Custom providers** — OpenAI-compatible providers defined in `opencode.json`
+  (`@ai-sdk/openai-compatible` + `baseURL`), callable as `provider/model`.
+- **Ollama (local)** — `ollama:llama3`, `local:qwen2.5-coder`, no key needed.
+
+## Safety notes
+
+- `autoApprove: true` runs delegations non-interactively with tool permissions granted — point
+  them at repositories you trust and review the diffs. Set `autoApprove: false` to require
+  manual approval.
+- This server never stores API keys — provider auth lives in opencode's own auth store.
+- Usage is logged to `~/.forge-delegate/usage.jsonl`; see `forge-delegate stats`.
+
+## CLI
+
+```text
+forge-delegate setup      Register with Claude Code / Codex / opencode
+forge-delegate serve      Start the MCP server (used internally)
+forge-delegate config     get | set | path
+forge-delegate status     Show opencode logins and usage summary
+forge-delegate stats      Show detailed usage statistics
+```
+
+## Publishing (npm)
+
+The primary install is `npx -y forge-delegate setup`, so the package must be on npm. Checklist:
+
+1. `npm run prepublishOnly` — syntax-checks all entry files (runs automatically on publish).
+2. `npm pack --dry-run` — confirm the tarball contains only `cli.mjs`, `server.mjs`, `lib.mjs`,
+   `install.sh`, `docs/`, `README.md` (via the `files` field), not `node_modules`.
+3. Bump `version` in `package.json` (and the root `version` in `package-lock.json`).
+4. `npm login && npm publish` — the `bin` field makes `npx forge-delegate …` work.
+
+Also make sure the GitHub repo exists at `MuhamadBarzani/forge-delegate` with Pages enabled on
+`/docs` (configurator) — the `raw.githubusercontent.com` install URL and the configurator's
+hardcoded URL point there.
+
+## License
+
+MIT

package/cli.mjs

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+import { createInterface } from "node:readline/promises";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { execSync } from "node:child_process";
+import { loadConfig, saveConfig, configPath } from "./lib.mjs";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith("--")) continue;
+    const eq = a.indexOf("=");
+    const key = eq >= 0 ? a.slice(2, eq) : a.slice(2);
+    if (eq >= 0) args[key] = a.slice(eq + 1);
+    else if (i + 1 < argv.length && !argv[i + 1].startsWith("--")) {
+      args[key] = argv[i + 1];
+      i++;
+    } else args[key] = true;
+  }
+  return args;
+}
+
+function launchCommand() {
+  const isPublished = here.includes(join("node_modules", "forge-delegate")) || here.includes("/.npm/_npx/");
+  return isPublished ? "npx -y forge-delegate serve" : `node ${join(here, "cli.mjs")} serve`;
+}
+
+function launchArray() {
+  const isPublished = here.includes(join("node_modules", "forge-delegate")) || here.includes("/.npm/_npx/");
+  return isPublished ? ["npx", "-y", "forge-delegate", "serve"] : [process.execPath, join(here, "cli.mjs"), "serve"];
+}
+
+function registerClaude(launch, scope) {
+  try {
+    execSync(`claude mcp remove --scope ${scope} forge-delegate`, { stdio: "ignore" });
+  } catch {}
+  try {
+    execSync(`claude mcp remove forge-delegate`, { stdio: "ignore" });
+  } catch {}
+  execSync(`claude mcp add --scope ${scope} forge-delegate -- ${launch}`, { stdio: "inherit" });
+  console.log(`  ✓ Claude Code (scope=${scope})`);
+}
+
+function codexConfigPath(scope, projectDir) {
+  return scope === "user" ? join(homedir(), ".codex", "config.toml") : join(projectDir, ".codex", "config.toml");
+}
+
+function registerCodex(launchArr, scope, projectDir) {
+  const path = codexConfigPath(scope, projectDir);
+  mkdirSync(dirname(path), { recursive: true });
+  let toml = "";
+  try {
+    toml = readFileSync(path, "utf8");
+  } catch {}
+  const section = `[mcp_servers.forge-delegate]`;
+  const block = `${section}\ncommand = ${JSON.stringify(launchArr[0])}\nargs = ${JSON.stringify(launchArr.slice(1))}\n`;
+  const escaped = section.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  if (toml.includes(section)) {
+    toml = toml.replace(new RegExp(`${escaped}[\\s\\S]*?(?=\\n\\[|$)`), block.trimEnd());
+  } else {
+    toml += (toml.endsWith("\n") || toml === "" ? "" : "\n") + "\n" + block;
+  }
+  writeFileSync(path, toml);
+  console.log(`  ✓ Codex (${path})`);
+}
+
+function opencodeConfigPath(scope, projectDir) {
+  return scope === "user" ? join(homedir(), ".config", "opencode", "opencode.json") : join(projectDir, "opencode.json");
+}
+
+function registerOpencode(launchArr, scope, projectDir) {
+  const path = opencodeConfigPath(scope, projectDir);
+  mkdirSync(dirname(path), { recursive: true });
+  let cfg = {};
+  try {
+    cfg = JSON.parse(readFileSync(path, "utf8"));
+  } catch {}
+  cfg.mcp = cfg.mcp ?? {};
+  cfg.mcp["forge-delegate"] = { type: "local", command: launchArr, enabled: true };
+  writeFileSync(path, JSON.stringify(cfg, null, 2) + "\n");
+  console.log(`  ✓ opencode (${path})`);
+}
+
+async function setup() {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q) => rl.question(q);
+  const flags = parseArgs(process.argv.slice(3));
+  const current = loadConfig();
+
+  // Flags win; anything omitted is asked interactively (Enter accepts the [default]).
+  // In a non-terminal (piped/automated) run, prompts are skipped and defaults are used.
+  const interactive = !!process.stdin.isTTY;
+  let model = flags.model;
+  let targets = flags.targets;
+  let scope = flags.scope;
+  let projectDir = flags["project-dir"];
+
+  console.log("\n=== forge-delegate setup ===\n");
+  if (interactive) console.log("Press Enter to accept the suggested [default], or type a value.\n");
+
+  if (!model) {
+    const def = current.defaultModel ?? "opencode/mimo-v2.5-free";
+    model = interactive ? ((await ask(`Default model [${def}]: `)) ?? "").trim() || def : def;
+  }
+  if (!targets) targets = "claude,codex,opencode";
+  if (!scope) scope = "user";
+  if (scope === "project" && !projectDir) projectDir = process.cwd();
+  projectDir = projectDir ?? process.cwd();
+  targets = targets.split(",").map((s) => s.trim().toLowerCase());
+
+  const launch = launchCommand();
+  const launchArr = launchArray();
+
+  // 1. Set the default model first so it's saved even if registration hits an issue
+  if (model && model !== current.defaultModel) {
+    saveConfig({ defaultModel: model });
+    console.log(`  ✓ default model set: ${model}`);
+  }
+
+  // 2. Register with chosen hosts (claude / codex / opencode)
+  for (const target of targets) {
+    try {
+      if (target === "claude") registerClaude(launch, scope);
+      else if (target === "codex") registerCodex(launchArr, scope, projectDir);
+      else if (target === "opencode") registerOpencode(launchArr, scope, projectDir);
+      else console.log(`  ✗ unknown target '${target}' (use claude,codex,opencode)`);
+    } catch (e) {
+      console.log(`  ✗ ${target}: ${e.message}`);
+    }
+  }
+
+  // 3. Check opencode logins
+  let authCount = 0;
+  try {
+    const authPath = join(homedir(), ".local/share/opencode/auth.json");
+    authCount = Object.keys(JSON.parse(readFileSync(authPath, "utf8"))).length;
+  } catch {}
+  if (authCount > 0) {
+    console.log(`Found ${authCount} opencode provider login(s) — ready to use.`);
+  } else {
+    console.log("\nNo opencode logins found. To enable models, run:");
+    console.log("  opencode auth login <provider>   (e.g. opencode auth login deepseek)");
+    if (interactive) await ask("Press Enter when done (or Ctrl+C to skip): ");
+  }
+
+  console.log(`
+Done! Restart your agent, then run /mcp (Claude Code) or \`codex mcp\` / \`opencode\` to confirm "forge-delegate" is connected.
+Use list_models inside the agent to see everything available.
+`);
+  rl.close();
+}
+
+function configCmd(argv) {
+  const sub = argv[0];
+  if (sub === "path") {
+    console.log(configPath());
+    return;
+  }
+  const flags = parseArgs(argv);
+  if (sub === "set") {
+    const patch = {};
+    if (flags.model) patch.defaultModel = flags.model;
+    if (flags.agent) patch.defaultAgent = flags.agent;
+    if (flags.variant) patch.defaultVariant = flags.variant;
+    if (flags.timeout) patch.timeoutMs = Number(flags.timeout) * 1000;
+    if (flags.dir) patch.defaultDirectory = flags.dir;
+    if (flags["default-dir"]) patch.defaultDirectory = flags["default-dir"];
+    if (flags.autoApprove !== undefined) patch.autoApprove = flags.autoApprove === "true" || flags.autoApprove === "1" || flags.autoApprove === true;
+    saveConfig(patch);
+    console.log(`updated ${configPath()}`);
+  }
+  const cfg = loadConfig();
+  console.log(JSON.stringify(cfg, null, 2));
+}
+
+async function status() {
+  let providers = [];
+  try {
+    const authPath = join(homedir(), ".local/share/opencode/auth.json");
+    const { listAuthDirectProviders } = await import("./lib.mjs");
+    const auth = JSON.parse(readFileSync(authPath, "utf8"));
+    providers = Object.keys(auth);
+  } catch {}
+  console.log(`\nopencode logins: ${providers.length ? providers.join(", ") : "none (run 'opencode auth login <provider>')"}\n`);
+  try {
+    const usagePath = join(homedir(), ".forge-delegate", "usage.jsonl");
+    if (existsSync(usagePath)) {
+      const lines = readFileSync(usagePath, "utf8").trim().split("\n").length;
+      console.log(`recorded delegations: ${lines} (see 'forge-delegate stats')`);
+    }
+  } catch {}
+}
+
+function stats() {
+  const usagePath = join(homedir(), ".forge-delegate", "usage.jsonl");
+  if (!existsSync(usagePath)) {
+    console.log("no usage recorded yet");
+    return;
+  }
+  const byKey = new Map();
+  for (const line of readFileSync(usagePath, "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const u = JSON.parse(line);
+      const key = `${u.tool} · ${u.model}`;
+      const s = byKey.get(key) ?? { calls: 0, ok: 0, ms: 0, tokens: 0 };
+      s.calls++;
+      if (u.ok) s.ok++;
+      s.ms += u.ms ?? 0;
+      s.tokens += u.tokens ?? 0;
+      byKey.set(key, s);
+    } catch {}
+  }
+  console.log("\nforge-delegate usage\n");
+  console.log("calls  ok%   avg(s)   tokens  tool · model");
+  for (const [key, s] of [...byKey.entries()].sort((a, b) => b[1].calls - a[1].calls)) {
+    console.log(
+      String(s.calls).padStart(5),
+      Math.round((s.ok / s.calls) * 100).toString().padStart(4) + "%",
+      (s.ms / s.calls / 1000).toFixed(1).padStart(7),
+      s.tokens ? String(s.tokens).padStart(8) : "       —",
+      " ", key
+    );
+  }
+  console.log(`\nlog: ${usagePath}\n`);
+}
+
+function help() {
+  console.log(`
+forge-delegate — delegate coding work from Claude Code/Codex/opencode to other AI models
+
+Usage:
+  forge-delegate setup [--model provider/model] [--targets claude,codex,opencode]
+                       [--scope user|project] [--project-dir <path>]
+                                             Interactive setup; flags optional (run bare to be prompted)
+  forge-delegate serve                        Start the MCP server (used internally by agents)
+  forge-delegate config get                   Show current configuration
+  forge-delegate config set --model <m> [--agent <a>] [--variant <v>]
+                          [--timeout <s>] [--dir <path>] [--autoApprove true|false]
+  forge-delegate config path                  Print config file path
+  forge-delegate status                       Show opencode logins and usage summary
+  forge-delegate stats                        Show detailed usage statistics
+
+Models come from your opencode installation:
+  opencode auth login <provider>   add a provider
+  opencode models                  list available models
+`);
+}
+
+const cmd = process.argv[2] ?? "help";
+if (cmd === "setup") await setup();
+else if (cmd === "serve") await import("./server.mjs");
+else if (cmd === "config") configCmd(process.argv.slice(3));
+else if (cmd === "status") await status();
+else if (cmd === "stats") stats();
+else help();

package/docs/DELEGATION.md

@@ -0,0 +1,61 @@
+# Delegation guide
+
+forge-delegate exists so your primary (expensive) agent stays focused on the decisions that
+need its judgment, while a cheap model grinds through the mechanical majority of coding work.
+
+## When does the primary agent delegate?
+
+Installing the tools doesn't force an agent to use them — it decides, guided by the
+`instructions` that forge-delegate injects into its context over MCP. Those instructions
+contain the cost policy, the delegate-vs-keep rules below, and the routing rules for which
+tool to call. Edit them by editing the `INSTRUCTIONS` string in `server.mjs`.
+
+## What to delegate vs. keep
+
+| ✅ Delegate — high volume, low risk | ⛔ Keep on the primary agent |
+|---|---|
+| Tests for well-specified behavior | Architecture, system design, choosing abstractions |
+| Boilerplate & scaffolding (CRUD, DTOs, fixtures, mocks) | Security-sensitive code (auth, crypto, secrets, permissions) |
+| Mechanical edits across many files (renames, prop propagation, imports) | Concurrency, performance-critical paths, subtle correctness |
+| Lint / formatting / type-error fixes | Ambiguous / underspecified requirements needing judgment |
+| Docstrings, comments, README / changelog sections | Public API / interface design, breaking changes |
+| Straightforward data transforms / migrations with a clear spec | Debugging unknown root causes |
+| Obvious glue code / format conversions | Anything costly or hard to detect if wrong |
+
+**Rule of thumb:** high volume + low risk → delegate. Low volume + high risk → keep it.
+Unsure → keep it.
+
+## Which tool?
+
+| Need | Tool |
+|---|---|
+| Quick one-shot question, no file access needed | `ask_model` |
+| A self-contained task with concrete code output | `delegate_task` |
+| Autonomous multi-file work, don't want to block | `delegate_agent` + `check_delegation` |
+| See what's available | `list_models` |
+
+## Cost policy (non-negotiable)
+
+The user pays per delegated call on a budget plan. **Always pick cheap or free models.**
+Never pick top-tier/premium/frontier models — not even "just this once" or for hard tasks.
+If a task seems too hard for a cheap model, split it into smaller delegated steps instead of
+upgrading the model.
+
+## Preconditions for a good delegation
+
+1. **Self-contained prompt.** State the goal, constraints, and acceptance criteria. Don't
+   assume the cheap model saw the surrounding conversation.
+2. **Right working directory.** Pass `directory:` (or set `defaultDirectory`) — don't rely on
+   the server's inherited cwd.
+3. **Bound the blast radius.** Auto-approve is on by default, so point delegations at
+   repositories you trust and review the diffs afterward.
+4. **Follow up cheaply.** Keep the returned `session` id and pass it as `continue_session` for
+   follow-ups — the agent keeps its context instead of re-exploring.
+
+## Tuning
+
+- Change the default model / directory / auto-approve anytime: `set_delegate_config`, or
+  `forge-delegate config set`.
+- Save named presets in `profiles` (e.g. `tests`, `quick`) and reference them per call with
+  `profile: "name"`.
+- Raise/lower the per-delegation timeout with `timeoutMs` (env default `FORGE_OPENCODE_TIMEOUT`).