forge-delegate 1.0.3 → 1.0.5

package/README.md

@@ -91,16 +91,16 @@ rate-limited; switch anytime with `forge-delegate config set --model <m>`.
 | Tool | What it does | Context cost |
 |---|---|---|
 | `ask_model` | One-shot question to any model (direct API, no file access) | Small |
-| `delegate` | Model works **autonomously** in the **background** (recommended) — returns a job id instantly; poll `check_delegation` | Tiny |
-| `delegate_sync` | Send a task + optional files to a model agent running via opencode; returns the result inline in your context | Medium |
+| `delegate` | Model works **autonomously** via opencode's own tool loop — inline by default; `background:true` returns a job id to poll via `check_delegation` | Tiny→Medium |
 | `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` 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.
+opencode locally. File contents never touch your main agent's context. Fast tasks return
+inline; long ones are auto-backgrounded by Claude Code (past ~2 min) or run detached with
+`background:true` — so the delegation never blocks your session.
 
 ## When to delegate
 
@@ -116,6 +116,17 @@ detached background process, so the MCP call returns instantly.
 
 Full guide: [docs/DELEGATION.md](docs/DELEGATION.md)
 
+### The `delegate-work` skill
+
+Setup also installs a Claude Code skill (`~/.claude/skills/delegate-work/`, or
+`<project>/.claude/skills/` under `--scope project`). Skip it with `--no-skill`.
+
+It exists because MCP server `instructions` are injected once at session start and
+get buried as the context fills — by turn 30 they lose to whatever is in front of the
+model. A skill description is re-matched against every user turn, so the delegation
+triggers ("write tests for", "rename X everywhere", "fix the lint errors") stay live
+for the whole session instead of decaying.
+
 ## Configuration
 
 Stored in `~/.forge-delegate/config.json`, read fresh on every call — change it anytime without

package/cli.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { createInterface } from "node:readline/promises";
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
@@ -35,6 +35,19 @@ function launchArray() {
   return isPublished ? ["npx", "-y", "forge-delegate", "serve"] : [process.execPath, join(here, "cli.mjs"), "serve"];
 }
 
+// The MCP server's `instructions` are injected once at session start and decay as the
+// context fills. A skill is re-matched against every user turn, so the delegation
+// triggers stay live for the whole session.
+function installClaudeSkill(scope, projectDir) {
+  const src = join(here, "skills", "delegate-work", "SKILL.md");
+  if (!existsSync(src)) return;
+  const root = scope === "user" ? join(homedir(), ".claude") : join(projectDir, ".claude");
+  const dest = join(root, "skills", "delegate-work", "SKILL.md");
+  mkdirSync(dirname(dest), { recursive: true });
+  copyFileSync(src, dest);
+  console.log(`  \u2713 delegate-work skill (${dest})`);
+}
+
 function registerClaude(launch, scope) {
   try {
     execSync(`claude mcp remove --scope ${scope} forge-delegate`, { stdio: "ignore" });
@@ -125,7 +138,10 @@ async function setup() {
   // 2. Register with chosen hosts (claude / codex / opencode)
   for (const target of targets) {
     try {
-      if (target === "claude") registerClaude(launch, scope);
+      if (target === "claude") {
+        registerClaude(launch, scope);
+        if (!flags["no-skill"]) installClaudeSkill(scope, projectDir);
+      }
       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)`);
@@ -169,7 +185,6 @@ function configCmd(argv) {
     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()}`);
@@ -236,8 +251,9 @@ forge-delegate — delegate coding work from Claude Code/Codex/opencode to other
 
 Usage:
   forge-delegate setup [--model provider/model] [--targets claude,codex,opencode]
-                       [--scope user|project] [--project-dir <path>]
+                       [--scope user|project] [--project-dir <path>] [--no-skill]
                                              Interactive setup; flags optional (run bare to be prompted)
+                                             --no-skill skips installing the delegate-work skill
   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>]

package/docs/DELEGATION.md

@@ -30,8 +30,8 @@ Unsure → keep it.
 | Need | Tool |
 |---|---|
 | Quick one-shot question, no file access needed | `ask_model` |
-| A self-contained task with concrete code output, inline | `delegate_sync` |
-| Autonomous multi-file work, don't want to block (recommended) | `delegate` + `check_delegation` |
+| A self-contained coding task (inline; auto-backgrounds past ~2 min in Claude Code) | `delegate` |
+| Parallel fan-out or fire-and-forget | `delegate` with `background:true` + `check_delegation` |
 | See what's available | `list_models` |
 
 ## Cost policy (non-negotiable)

package/install.sh

@@ -12,6 +12,7 @@
 #   --targets a,b,c          hosts to register with: claude,codex,opencode (default all)
 #   --scope user|project     registration scope (default user)
 #   --project-dir <path>     project for --scope project (default current dir)
+#   --no-skill               skip installing the delegate-work skill for Claude Code
 #   --no-opencode            skip auto-installing opencode if missing
 #   --no-npx                 skip the npx route, force clone/checkout
 #   --help
@@ -23,6 +24,7 @@ SCOPE="user"
 PROJECT_DIR=""
 NO_OPENCODE=0
 NO_NPX=0
+NO_SKILL=0
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
@@ -34,10 +36,11 @@ while [[ $# -gt 0 ]]; do
     --scope=*) SCOPE="${1#*=}"; shift ;;
     --project-dir) PROJECT_DIR="${2:-}"; shift 2 ;;
     --project-dir=*) PROJECT_DIR="${1#*=}"; shift ;;
+    --no-skill) NO_SKILL=1; shift ;;
     --no-opencode) NO_OPENCODE=1; shift ;;
     --no-npx) NO_NPX=1; shift ;;
     --help|-h)
-      sed -n '3,18p' "$0"
+      sed -n '3,19p' "$0"
       exit 0 ;;
     *) echo "unknown option: $1"; exit 1 ;;
   esac
@@ -68,6 +71,7 @@ fi
 ARGS=(--targets "$TARGETS" --scope "$SCOPE")
 if [[ -n "$MODEL" ]]; then ARGS+=(--model "$MODEL"); fi
 if [[ "$SCOPE" == "project" ]]; then ARGS+=(--project-dir "$PROJECT_DIR"); fi
+if [[ "$NO_SKILL" -eq 1 ]]; then ARGS+=(--no-skill); fi
 
 # 3. Preferred route: published npm package (works on Windows, always latest)
 if [[ "$NO_NPX" -eq 0 ]] && command -v npx >/dev/null 2>&1; then

package/lib.mjs

@@ -1,10 +1,8 @@
-import { execFile, spawn } from "node:child_process";
-import { promisify } from "node:util";
+import { spawn } from "node:child_process";
 import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 
-const execFileAsync = promisify(execFile);
 export const OPENCODE_TIMEOUT = Number(process.env.FORGE_OPENCODE_TIMEOUT ?? 900_000);
 const CONFIG_DIR = join(homedir(), ".forge-delegate");
 const AUTH_PATH = join(homedir(), ".local/share/opencode/auth.json");
@@ -344,14 +342,3 @@ export async function runOne(model, prompt) {
   throw new Error(`unknown model '${model}' — see list_models`);
 }
 
-export async function gitDiff() {  try {
-    const { stdout } = await execFileAsync("git", ["diff", "HEAD"], {
-      cwd: process.cwd(),
-      maxBuffer: 5 * 1024 * 1024,
-    });
-    return stdout.trim();
-  } catch {
-    return null;
-  }
-}
-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-delegate",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "MCP server that relays coding work to other AI models (DeepSeek, Gemini, OpenAI, Ollama) so Claude Code saves tokens",
   "type": "module",
   "bin": {
@@ -16,6 +16,7 @@
     "server.mjs",
     "lib.mjs",
     "install.sh",
+    "skills/",
     "docs/",
     "README.md"
   ],

package/server.mjs

@@ -4,13 +4,13 @@ import { z } from "zod";
 import { execFile, spawn } from "node:child_process";
 import { promisify } from "node:util";
 import { mkdirSync, writeFileSync, readFileSync, existsSync, openSync, readdirSync } from "node:fs";
-import { join } from "node:path";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
 import {
   logUsage,
   opencodeRun,
   runOne,
-  gitDiff,
   opencodeArgs,
   parseEvents,
   pickVariant,
@@ -24,25 +24,35 @@ import {
 
 const execFileAsync = promisify(execFile);
 const RUNS_DIR = join(homedir(), ".forge-delegate", "runs");
+const here = dirname(fileURLToPath(import.meta.url));
+const VERSION = JSON.parse(readFileSync(join(here, "package.json"), "utf8")).version;
 
-const INSTRUCTIONS = `forge-delegate gives you a crew of external AI models to delegate coding work to. Hand off the high-volume, low-risk work (boilerplate, tests, lint/type fixes, mechanical edits) to a cheap or free model and keep the expensive agent focused on architecture and judgment calls.
+const INSTRUCTIONS = `forge-delegate hands coding work to cheap external models running as full agents. They read the project and write the code in their own loop, so the work never passes through your context. Spend your context on judgment; delegate the typing.
 
-COST POLICY — MANDATORY, NON-NEGOTIABLE:
-The user pays per delegated call on a budget plan. You MUST pick only cheap or free models for EVERY delegation (ask_model, delegate_sync, delegate). NEVER pick top-tier, premium, flagship, or 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. Run list_models and prefer free/cheap models (deepseek flash tiers, free opencode models, local ollama).
+DELEGATE BY DEFAULT — do not hand-write these yourself:
+- Tests for code that already exists.
+- Mechanical refactors: renames, signature changes, import rewrites, API migrations.
+- Lint, type, and build errors — paste the error output and delegate the fix.
+- Boilerplate: CRUD endpoints, config and schema files, adapters, fixtures, scaffolding.
+- Ports and translations between languages, frameworks, or file formats.
+- The same edit repeated across 3 or more files.
+- Reading a large file or directory to answer one narrow question — delegate the reading, keep your context clean.
+
+KEEP FOR YOURSELF: architecture, debugging an unknown root cause, security-sensitive code, anything where being wrong is expensive, and the review of whatever comes back. Delegation does not transfer responsibility for the result.
 
 Routing:
-- Quick one-shot questions → ask_model (direct API, no file access).
-- Multi-file edits/refactors/tests → delegate (background, recommended) or delegate_sync (inline).
-- delegate returns a job id instantly; poll check_delegation for the result.
-- Follow-ups on a delegated area: pass the returned session id as continue_session.
-- Omit model/directory to use the configured defaults (get_delegate_config); change them anytime with set_delegate_config — never reinstall.
-- Never paste large files into your own context for delegation — delegate and let the agent read files itself.
+- One-shot question, no file access needed -> ask_model.
+- Anything touching files -> delegate (inline; Claude Code auto-backgrounds calls past 2 minutes).
+- Parallel fan-out or long jobs -> delegate with background:true, then poll check_delegation.
+- Follow-up in the same area -> pass the previous session id as continue_session.
+- Omit model/directory/agent: the configured defaults are already correct (get_delegate_config to see them, set_delegate_config to change them — never reinstall).
+- Never paste file contents into a task. Name the paths; the agent reads them itself.
 
-The per-tool descriptions are the authoritative reference.
+Cost: the configured default model is already a cheap or free tier — just use it. Do not override \`model\` upward to a premium or flagship tier; if a task looks too big for the default, split it into smaller delegations instead.
 `;
 
 const server = new McpServer(
-  { name: "forge-delegate", version: "1.0.0" },
+  { name: "forge-delegate", version: VERSION },
   { instructions: INSTRUCTIONS }
 );
 
@@ -79,7 +89,22 @@ async function startBackgroundJob(model, task, opts = {}) {
     stdio: ["ignore", out, out],
   });
   child.unref();
-  writeFileSync(join(RUNS_DIR, `${id}.json`), JSON.stringify({ id, pid: child.pid, model, directory: cwd, started: Date.now(), logPath }));
+  const started = Date.now();
+  const deadline = opts.timeoutMs ? started + opts.timeoutMs : null;
+  if (deadline) {
+    setTimeout(() => {
+      try {
+        process.kill(-child.pid, "SIGKILL");
+      } catch {}
+      try {
+        process.kill(child.pid, "SIGKILL");
+      } catch {}
+    }, opts.timeoutMs).unref();
+  }
+  writeFileSync(
+    join(RUNS_DIR, `${id}.json`),
+    JSON.stringify({ id, pid: child.pid, model, directory: cwd, started, deadline, logPath })
+  );
   return id;
 }
 
@@ -120,7 +145,7 @@ server.tool(
 
 server.tool(
   "ask_model",
-  "Send a one-shot prompt to an external AI model and get its raw response. Fast direct API call; the model has NO file access and CANNOT take actions. For work requiring tools/files use delegate (background) or delegate_sync (inline) instead. model defaults to the configured defaultModel.",
+  "USE THIS INSTEAD OF ANSWERING FROM YOUR OWN REASONING when the question is self-contained and cheap to verify: a syntax or API detail, a regex, a short snippet, a second opinion on a design, a summary of text you already have. Sends a one-shot prompt to an external model and returns its raw response. Fast direct API call; the model has NO file access and CANNOT take actions — for anything touching files use delegate instead. Omit model to use the configured default (already a cheap tier).",
   {
     model: z.string().optional().describe("provider/model, e.g. deepseek/deepseek-v4-flash, ollama:llama3 (defaults to config defaultModel)"),
     prompt: z.string(),
@@ -136,21 +161,35 @@ server.tool(
 );
 
 server.tool(
-  "delegate_sync",
-  "Delegate a coding task to another AI model running as a full agent (via local opencode): it can read your project and answer with concrete code. Runs INLINE (foreground) — the result is returned in your context when done. Prefer `delegate` (background) to keep your context small. Optionally attach specific files. model/directory/agent/autoApprove default from config.",
+  "delegate",
+  "USE THIS INSTEAD OF WRITING THE CODE YOURSELF when the task is: tests for code that already exists; a mechanical refactor (rename, signature change, import rewrite, API migration); fixing lint/type/build errors; boilerplate or scaffolding (CRUD endpoints, config, schemas, adapters, fixtures); a port between languages or frameworks; the same edit repeated across 3 or more files; or reading a large file/directory to answer one narrow question. Hands the task to another AI model running as a full agent via local opencode: it reads your project, explores, and writes concrete code in its own tool loop — none of which enters your context. Keep architecture, unknown-root-cause debugging, and security-sensitive code for yourself, and always review what comes back. Runs INLINE by default (result returned when done; Claude Code auto-backgrounds calls past 2 minutes). Pass background:true to run detached and get a job id instantly, then poll check_delegation — use that for parallel fan-out or hosts that block on long calls. Pass continue_session (returned by a previous delegation) to keep the same agent session instead of re-exploring. Never paste file contents into task: name the paths and let the agent read them. model/directory/agent/autoApprove default from config — omit them.",
   {
     model: z.string().optional().describe("provider/model format, e.g. opencode/mimo-v2.5-free (defaults to config defaultModel)"),
     task: z.string(),
-    files: z.array(z.string()).optional(),
+    files: z.array(z.string()).optional().describe("specific files to attach (inline mode)"),
+    background: z.boolean().optional().describe("run detached and return a job id (default false)"),
+    continue_session: z.string().optional().describe("session id returned by a previous delegation"),
     directory: z.string().optional().describe("absolute path to run in (defaults to config defaultDirectory, else server cwd)"),
     agent: z.string().optional().describe("opencode agent to use (defaults to config defaultAgent)"),
     autoApprove: z.boolean().optional().describe("auto-approve permissions (defaults to config autoApprove, true)"),
     profile: z.string().optional().describe("named config profile to apply"),
   },
-  async ({ model, task, files, directory, agent, autoApprove, profile }) => {
+  async ({ model, task, files, background, continue_session, directory, agent, autoApprove, profile }) => {
     const r = resolveConfig({ model, directory, agent, autoApprove, profile });
     if (!r.model) return { content: [{ type: "text", text: "ERROR: no model specified and no defaultModel configured. Call set_delegate_config or pass model." }], isError: true };
-    return withUsage("delegate_sync", r.model, async () => {
+    if (background) {
+      return withUsage("delegate", r.model, async () => {
+        const id = await startBackgroundJob(r.model, task, {
+          sessionId: continue_session,
+          directory: r.directory,
+          agent: r.agent,
+          autoApprove: r.autoApprove,
+          timeoutMs: r.timeoutMs,
+        });
+        return `Started background job ${id}. Poll with check_delegation(id: "${id}").`;
+      });
+    }
+    return withUsage("delegate", r.model, async () => {
       const res = await opencodeRun(r.model, task, {
         files,
         directory: r.directory,
@@ -163,33 +202,6 @@ server.tool(
   }
 );
 
-server.tool(
-  "delegate",
-  "Fully delegate a coding task to another AI model working autonomously on this project (via local opencode): it explores, reads, edits and creates files in its own loop — invisible to the caller's context. Runs in the BACKGROUND (recommended): returns a job id instantly, poll check_delegation for the result. Pass continue_session (returned by a previous delegation) to keep the same agent session instead of re-exploring. Use this over delegate_sync to keep the caller's context small. model/directory/agent/autoApprove default from config.",
-  {
-    model: z.string().optional().describe("provider/model format, e.g. opencode/mimo-v2.5-free (defaults to config defaultModel)"),
-    task: z.string(),
-    continue_session: z.string().optional().describe("session id returned by a previous delegation"),
-    directory: z.string().optional().describe("absolute path to run in (defaults to config defaultDirectory, else server cwd)"),
-    agent: z.string().optional().describe("opencode agent to use (defaults to config defaultAgent)"),
-    autoApprove: z.boolean().optional().describe("auto-approve permissions (defaults to config autoApprove, true)"),
-    profile: z.string().optional().describe("named config profile to apply"),
-  },
-  async ({ model, task, continue_session, directory, agent, autoApprove, profile }) => {
-    const r = resolveConfig({ model, directory, agent, autoApprove, profile });
-    if (!r.model) return { content: [{ type: "text", text: "ERROR: no model specified and no defaultModel configured. Call set_delegate_config or pass model." }], isError: true };
-    return withUsage("delegate", r.model, async () => {
-      const id = await startBackgroundJob(r.model, task, {
-        sessionId: continue_session,
-        directory: r.directory,
-        agent: r.agent,
-        autoApprove: r.autoApprove,
-      });
-      return `Started background job ${id}. Poll with check_delegation(id: "${id}").`;
-    });
-  }
-);
-
 server.tool(
   "check_delegation",
   "Check status of a background delegation job: running/completed plus output so far. Call with no id to list all jobs.",
@@ -216,7 +228,9 @@ server.tool(
       const parsed = parseEvents(log);
       const tail = parsed.text || "(agent still thinking, no text output yet)";
       const footer = parsed.sessionId ? ` · session: ${parsed.sessionId}` : "";
-      return `[${running ? "RUNNING" : "DONE"}] ${id} (${meta.model}, ${Math.round((Date.now() - meta.started) / 1000)}s)${footer}\n\n${tail.slice(-8000)}`;
+      let status = running ? "RUNNING" : "DONE";
+      if (meta.deadline && Date.now() > meta.deadline) status = "TIMED OUT";
+      return `[${status}] ${id} (${meta.model}, ${Math.round((Date.now() - meta.started) / 1000)}s)${footer}\n\n${tail.slice(-8000)}`;
     })
 );
 

package/skills/delegate-work/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: delegate-work
+description: Hand a coding task to a cheap external model via forge-delegate instead of writing it yourself. Load BEFORE starting work that is high-volume and low-judgment - writing tests for code that already exists, mechanical refactors (renames, signature changes, import rewrites, API migrations), fixing lint/type/build errors, boilerplate and scaffolding (CRUD endpoints, config files, schemas, adapters, fixtures), porting code between languages or frameworks, the same edit repeated across 3 or more files, or reading a large file or directory to answer one narrow question. Triggers on - "write tests for", "add tests", "rename X to Y everywhere", "refactor", "migrate", "port this to", "fix the lint errors", "fix the type errors", "scaffold", "boilerplate", "do the same for the other files".
+---
+
+# Delegating work to a cheap model
+
+`forge-delegate` runs another AI model as a full agent over this project. It reads
+files, explores, and writes code in its own tool loop. None of that passes through
+your context — you get back a summary and a diff on disk.
+
+The point is not to save the user money on your tokens. It is that your context is
+the scarce resource in a long session, and mechanical work burns it fast.
+
+## Decide
+
+Delegate when the task is **high-volume and low-judgment**: the shape of the correct
+answer is already known, and the work is typing it out across files.
+
+| Delegate | Keep |
+|---|---|
+| Tests for code that already exists | Deciding what behaviour to test |
+| Rename / signature change / import rewrite across files | Designing the new interface |
+| Fixing lint, type, or build errors | Debugging an unknown root cause |
+| CRUD endpoints, config, schemas, fixtures, adapters | Architecture and data modelling |
+| Porting between languages or frameworks | Security-sensitive code |
+| The same edit repeated across 3+ files | The first instance, so the pattern is right |
+| Reading a big file to answer one question | Anything where being wrong is expensive |
+
+Delegating does not transfer responsibility. Review what comes back before you
+report it as done.
+
+## Do it
+
+1. Do the judgment part yourself first — decide the interface, write the first
+   instance, name the files.
+2. Call `delegate` with a task that names paths. **Never paste file contents into
+   the task**; the agent reads them itself. That is the whole point.
+3. Omit `model`, `directory`, and `agent` — the configured defaults are already a
+   cheap or free tier. Do not raise `model` to a premium tier; if the task is too
+   big for the default, split it into smaller delegations.
+4. Review the result. Run the tests or the build yourself.
+
+```
+delegate(task: "Write unit tests for the exported functions in src/parser.ts.
+                Follow the style of tests/lexer.test.ts. Cover the error paths.")
+```
+
+Parallel or long-running work: `background: true` returns a job id immediately,
+then poll `check_delegation(id)`. Follow-up in the same area: pass the previous
+`session: <id>` back as `continue_session` so the agent skips re-exploring.
+
+For a question that needs no file access at all — a syntax detail, a regex, a
+second opinion — use `ask_model` instead; it is a direct API call with no agent loop.
+
+## Don't
+
+- Don't delegate a task you cannot describe precisely. Vague task, vague diff.
+- Don't delegate and walk away. Unreviewed delegated code is worse than no code.
+- Don't paste large files into the task text.
+- Don't override `model` upward because a task "seems hard" — split it instead.