opencode-task-router 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Doug Ritter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,172 @@
+# OpenCode Task Router
+
+An [OpenCode](https://opencode.ai) plugin that classifies a development task with a local Ollama model and recommends the right cost tier and agent to use.
+
+It is designed to keep simple work on free local models and reserve paid models for tasks that actually need them.
+
+## What You Get
+
+- A `route_task` tool for task-to-model routing recommendations
+- Cost-tier recommendations: `free`, `cheap`, `moderate`, `expensive`
+- Agent guidance based on the recommended tier
+- Lightweight learning from your past routing decisions
+
+## Prerequisites
+
+1. [OpenCode](https://opencode.ai) installed
+2. [Ollama](https://ollama.ai) installed and running
+3. The classifier model pulled locally:
+
+```bash
+ollama serve
+ollama pull qwen3:8b
+```
+
+If your global OpenCode config uses `enabled_providers`, include `ollama` there too:
+
+```jsonc
+{
+  "enabled_providers": ["github-copilot", "ollama"]
+}
+```
+
+## Install From NPM
+
+Add the plugin package to your OpenCode config:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-task-router"]
+}
+```
+
+Then restart OpenCode. OpenCode installs npm plugins automatically with Bun at startup.
+
+## Minimal Usage
+
+Ask OpenCode to call the tool directly:
+
+```text
+Use the route_task tool to analyze this task: refactor the authentication module
+```
+
+Typical output:
+
+```text
+## Task Routing Recommendation
+
+| Factor | Assessment |
+|--------|-----------|
+| Complexity | **moderate** |
+| Context needs | **medium** |
+| Cost tier | **moderate** |
+
+**Reasoning:** Multi-file refactoring usually needs broader codebase context.
+```
+
+## Optional Full Setup
+
+The npm package guarantees the `route_task` tool.
+
+If you also want the `/route` shortcut, a local free-tier agent, and an example Ollama provider config, copy the example files from `examples/opencode/` into your project:
+
+```text
+examples/opencode/
+├── opencode.json
+└── .opencode/
+    ├── agents/
+    │   └── local-worker.md
+    └── commands/
+        └── route.md
+```
+
+Suggested mapping:
+
+- `examples/opencode/.opencode/commands/route.md` -> `.opencode/commands/route.md`
+- `examples/opencode/.opencode/agents/local-worker.md` -> `.opencode/agents/local-worker.md`
+- `examples/opencode/opencode.json` -> merge into your project `opencode.json`
+
+## How It Works
+
+1. `route_task` sends your task description to a local Ollama classifier
+2. The classifier returns task complexity, context estimate, and cost tier
+3. The plugin recommends an agent and model tier
+4. When the session goes idle, the plugin logs what was recommended to `.opencode/router-history.jsonl`
+5. Recent history is reused as calibration on future routing decisions
+
+## Configuration
+
+The plugin currently defaults to:
+
+```ts
+const OLLAMA_BASE_URL = "http://localhost:11434"
+const CLASSIFIER_MODEL = "qwen3:8b"
+const MAX_HISTORY_EXAMPLES = 20
+```
+
+These live in `src/index.ts`.
+
+## Local Development
+
+Install dependencies and build the package:
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+For local OpenCode development in this repo, the project plugin entrypoint at `.opencode/plugins/task-router.ts` re-exports the package source from `src/index.ts`.
+
+The smoke test automates what is practical without depending on a real OpenCode session:
+
+- builds the package
+- creates a tarball
+- installs the tarball into a temporary directory
+- imports the installed package
+- executes `route_task` with a mocked Ollama response
+- verifies the history file is written
+
+The unit tests cover the internal routing logic directly:
+
+- cost-tier inference from provider/model ids
+- classifier response parsing and normalization
+- prompt construction with calibration history
+- history file read/write helpers
+- plugin recommendation, retry, and idle logging behavior
+
+## CI And Publishing
+
+This repo includes GitHub Actions for:
+
+- CI on pushes to `main` and pull requests
+- npm publishing from version tags like `v0.1.0`
+- manual publish dry runs through `workflow_dispatch`
+
+Publishing can be fully automated through GitHub Actions using npm trusted publishing with GitHub OIDC.
+
+See `RELEASE.md` for the release checklist and tag-based publishing flow.
+
+## Troubleshooting
+
+### Cannot connect to Ollama
+
+Make sure Ollama is running and the model is installed:
+
+```bash
+ollama serve
+ollama pull qwen3:8b
+```
+
+### Plugin loads but routing falls back to moderate
+
+That usually means the classifier returned invalid output. The plugin retries once, then falls back to a safe default.
+
+### No history file created yet
+
+The history file is only written after a routing recommendation and when the session goes idle.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+import { type Plugin } from "@opencode-ai/plugin";
+interface ClassifierResponse {
+    complexity: "trivial" | "simple" | "moderate" | "complex";
+    contextEstimate: "small" | "medium" | "large";
+    costTier: "free" | "cheap" | "moderate" | "expensive";
+    reasoning: string;
+}
+interface HistoryEntry {
+    ts: string;
+    prompt: string;
+    recommendedTier: string;
+    accepted?: boolean;
+    actualTier?: string;
+    actualModel?: string;
+}
+declare function inferTierFromModel(providerID: string, modelID: string): string;
+declare function getHistoryDir(worktree: string): string;
+declare function getHistoryPath(worktree: string): string;
+declare function readHistory(worktree: string): HistoryEntry[];
+declare function appendHistory(worktree: string, entry: HistoryEntry): void;
+declare function buildClassifierPrompt(taskPrompt: string, history: HistoryEntry[]): string;
+declare function truncate(value: string, maxLength: number): string;
+declare function callOllama(prompt: string): Promise<string>;
+declare function parseClassifierResponse(raw: string): ClassifierResponse;
+export declare const __testUtils: {
+    buildClassifierPrompt: typeof buildClassifierPrompt;
+    callOllama: typeof callOllama;
+    getHistoryDir: typeof getHistoryDir;
+    getHistoryPath: typeof getHistoryPath;
+    inferTierFromModel: typeof inferTierFromModel;
+    parseClassifierResponse: typeof parseClassifierResponse;
+    readHistory: typeof readHistory;
+    appendHistory: typeof appendHistory;
+    truncate: typeof truncate;
+};
+export declare const TaskRouterPlugin: Plugin;
+export default TaskRouterPlugin;

package/dist/index.js

@@ -0,0 +1,355 @@
+import { tool } from "@opencode-ai/plugin";
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+const OLLAMA_BASE_URL = "http://localhost:11434";
+const CLASSIFIER_MODEL = "qwen3:8b";
+const HISTORY_DIR = ".opencode";
+const HISTORY_FILE = "router-history.jsonl";
+const MAX_HISTORY_EXAMPLES = 20;
+const TIER_INFO = {
+    free: {
+        description: "Local model (Ollama) -- zero cost, good for trivial/simple tasks",
+        agent: "local-worker",
+    },
+    cheap: {
+        description: "Fast paid model (e.g. Haiku, GPT-4o Mini, Gemini Flash)",
+        agent: "build",
+    },
+    moderate: {
+        description: "Capable paid model (e.g. Sonnet, GPT-4o, Codex)",
+        agent: "build",
+    },
+    expensive: {
+        description: "Premium paid model (e.g. Opus, GPT-5, o1-pro)",
+        agent: "build",
+    },
+};
+function inferTierFromModel(providerID, modelID) {
+    const provider = providerID.toLowerCase();
+    const model = modelID.toLowerCase();
+    if (provider === "ollama" ||
+        provider === "lmstudio" ||
+        provider === "llama.cpp" ||
+        provider === "llamacpp") {
+        return "free";
+    }
+    if (/opus|o1-pro|gpt-?5|gemini[.-_]?ultra/.test(model)) {
+        return "expensive";
+    }
+    if (/haiku|gpt-?4o-?mini|gemini[.-_]?flash|nano|mini|small/.test(model) &&
+        !/sonnet/.test(model)) {
+        return "cheap";
+    }
+    return "moderate";
+}
+function getHistoryDir(worktree) {
+    return join(worktree, HISTORY_DIR);
+}
+function getHistoryPath(worktree) {
+    return join(getHistoryDir(worktree), HISTORY_FILE);
+}
+function readHistory(worktree) {
+    const historyPath = getHistoryPath(worktree);
+    if (!existsSync(historyPath)) {
+        return [];
+    }
+    try {
+        const content = readFileSync(historyPath, "utf-8");
+        const trimmed = content.trim();
+        if (!trimmed) {
+            return [];
+        }
+        return trimmed
+            .split("\n")
+            .filter(Boolean)
+            .slice(-MAX_HISTORY_EXAMPLES)
+            .map((line) => JSON.parse(line));
+    }
+    catch {
+        return [];
+    }
+}
+function appendHistory(worktree, entry) {
+    const historyDir = getHistoryDir(worktree);
+    if (!existsSync(historyDir)) {
+        mkdirSync(historyDir, { recursive: true });
+    }
+    appendFileSync(getHistoryPath(worktree), JSON.stringify(entry) + "\n", "utf-8");
+}
+function buildClassifierPrompt(taskPrompt, history) {
+    let prompt = `You are a task classifier for software development work.
+Your job is to analyze a task description and classify it so the developer
+can pick the right AI model (local/free vs. paid/premium).
+
+Respond with ONLY a valid JSON object. No markdown fences, no explanation
+outside the JSON. Do not use any thinking tags.
+
+The JSON must have exactly these fields:
+{
+  "complexity": "trivial" | "simple" | "moderate" | "complex",
+  "contextEstimate": "small" | "medium" | "large",
+  "costTier": "free" | "cheap" | "moderate" | "expensive",
+  "reasoning": "one sentence explaining your classification"
+}
+
+Classification rules:
+- trivial: typos, small text edits, renaming, formatting
+- simple: single-file fixes, small scripts, doc edits, straightforward questions
+- moderate: new features, multi-file refactors, bug fixes requiring investigation
+- complex: architecture changes, security-sensitive work, multi-system integration
+
+Context size rules:
+- small (<2K tokens of codebase context needed): simple lookups, isolated changes
+- medium (2K-20K tokens): moderate features, understanding a module
+- large (20K+ tokens): cross-cutting changes, architectural understanding
+
+Cost tier mapping:
+- free: trivial + simple tasks -> use a local model (zero cost)
+- cheap: moderate tasks with small context -> use a fast paid model
+- moderate: moderate tasks with medium/large context -> use a capable paid model
+- expensive: complex tasks -> use a premium paid model
+`;
+    if (history.length > 0) {
+        prompt += `
+Here are recent routing decisions for calibration.
+When "accepted" is false, the developer disagreed with the recommendation
+and chose a different tier -- adjust your future classifications accordingly:
+
+`;
+        for (const entry of history) {
+            if (entry.accepted === false && entry.actualTier) {
+                prompt += `- "${truncate(entry.prompt, 80)}" -> recommended: ${entry.recommendedTier}, OVERRIDDEN -> developer used: ${entry.actualTier}\n`;
+                continue;
+            }
+            if (entry.accepted === true) {
+                prompt += `- "${truncate(entry.prompt, 80)}" -> recommended: ${entry.recommendedTier}, accepted\n`;
+                continue;
+            }
+            prompt += `- "${truncate(entry.prompt, 80)}" -> recommended: ${entry.recommendedTier}\n`;
+        }
+        prompt += "\n";
+    }
+    prompt += `\nNow classify this task:\n${taskPrompt}`;
+    return prompt;
+}
+function truncate(value, maxLength) {
+    return value.length > maxLength ? `${value.slice(0, maxLength)}...` : value;
+}
+async function callOllama(prompt) {
+    const response = await fetch(`${OLLAMA_BASE_URL}/api/generate`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            model: CLASSIFIER_MODEL,
+            prompt,
+            stream: false,
+            options: {
+                temperature: 0.1,
+                num_predict: 256,
+            },
+        }),
+    });
+    if (!response.ok) {
+        throw new Error(`Ollama returned ${response.status}: ${response.statusText}`);
+    }
+    const data = (await response.json());
+    return data.response;
+}
+function parseClassifierResponse(raw) {
+    let cleaned = raw
+        .replace(/```json\s*/g, "")
+        .replace(/```\s*/g, "")
+        .replace(/<think>[\s\S]*?<\/think>/g, "")
+        .trim();
+    const jsonMatch = cleaned.match(/\{[\s\S]*\}/);
+    if (jsonMatch) {
+        cleaned = jsonMatch[0];
+    }
+    const parsed = JSON.parse(cleaned);
+    const validComplexity = ["trivial", "simple", "moderate", "complex"];
+    const validContext = ["small", "medium", "large"];
+    const validCost = ["free", "cheap", "moderate", "expensive"];
+    if (!validComplexity.includes(parsed.complexity)) {
+        parsed.complexity = "moderate";
+    }
+    if (!validContext.includes(parsed.contextEstimate)) {
+        parsed.contextEstimate = "medium";
+    }
+    if (!validCost.includes(parsed.costTier)) {
+        parsed.costTier = "moderate";
+    }
+    return {
+        complexity: parsed.complexity,
+        contextEstimate: parsed.contextEstimate,
+        costTier: parsed.costTier,
+        reasoning: parsed.reasoning || "No reasoning provided",
+    };
+}
+export const __testUtils = {
+    buildClassifierPrompt,
+    callOllama,
+    getHistoryDir,
+    getHistoryPath,
+    inferTierFromModel,
+    parseClassifierResponse,
+    readHistory,
+    appendHistory,
+    truncate,
+};
+export const TaskRouterPlugin = async ({ directory, worktree }) => {
+    let pending = null;
+    const sessionModels = new Map();
+    return {
+        tool: {
+            route_task: tool({
+                description: "Analyze a development task and recommend the best cost tier " +
+                    "(free/cheap/moderate/expensive) and agent to use. " +
+                    "Evaluates task complexity, context size needs, and cost implications. " +
+                    "Uses a local Ollama model for classification (zero cost).",
+                args: {
+                    prompt: tool.schema
+                        .string()
+                        .describe("The task description or prompt to analyze for routing"),
+                },
+                async execute(args, context) {
+                    const projectRoot = context.worktree || context.directory;
+                    const history = readHistory(projectRoot);
+                    const classifierPrompt = buildClassifierPrompt(args.prompt, history);
+                    let classification;
+                    try {
+                        const rawResponse = await callOllama(classifierPrompt);
+                        classification = parseClassifierResponse(rawResponse);
+                    }
+                    catch (error) {
+                        try {
+                            const retryPrompt = `Respond with ONLY valid JSON, no other text.\n\n${classifierPrompt}`;
+                            const rawRetry = await callOllama(retryPrompt);
+                            classification = parseClassifierResponse(rawRetry);
+                        }
+                        catch {
+                            try {
+                                await fetch(`${OLLAMA_BASE_URL}/api/tags`);
+                            }
+                            catch {
+                                return [
+                                    "## Router Error",
+                                    "",
+                                    "Cannot connect to Ollama. Make sure it is running:",
+                                    "```",
+                                    "ollama serve",
+                                    "```",
+                                    "",
+                                    `And that the model \`${CLASSIFIER_MODEL}\` is pulled:`,
+                                    "```",
+                                    `ollama pull ${CLASSIFIER_MODEL}`,
+                                    "```",
+                                ].join("\n");
+                            }
+                            return [
+                                "## Router Warning",
+                                "",
+                                `Classification failed (${error}). Defaulting to **moderate** tier.`,
+                                "",
+                                "Run **`/models`** to pick a capable paid model, or just continue.",
+                            ].join("\n");
+                        }
+                    }
+                    const tierInfo = TIER_INFO[classification.costTier];
+                    pending = {
+                        ts: new Date().toISOString(),
+                        prompt: args.prompt,
+                        tier: classification.costTier,
+                        sessionID: context.sessionID,
+                    };
+                    const historyNote = history.length > 0
+                        ? `*Calibrated from ${history.length} past routing decisions.*`
+                        : "*No routing history yet -- recommendations will improve as you use the router.*";
+                    const tierLines = ["", "**Cost tiers:**", ""];
+                    for (const [tier, info] of Object.entries(TIER_INFO)) {
+                        const marker = tier === classification.costTier ? " **<-- recommended**" : "";
+                        tierLines.push(`- **${tier}**: ${info.description}${marker}`);
+                    }
+                    return [
+                        "## Task Routing Recommendation",
+                        "",
+                        "| Factor | Assessment |",
+                        "|--------|-----------|",
+                        `| Complexity | **${classification.complexity}** |`,
+                        `| Context needs | **${classification.contextEstimate}** |`,
+                        `| Cost tier | **${classification.costTier}** |`,
+                        "",
+                        `**Reasoning:** ${classification.reasoning}`,
+                        "",
+                        historyNote,
+                        ...tierLines,
+                        "",
+                        "---",
+                        "",
+                        "### How to proceed",
+                        "",
+                        `1. **Switch agent** -- press \`Tab\` and select **\`${tierInfo.agent}\`**`,
+                        `2. **Switch model** -- run **\`/models\`** and pick a **${classification.costTier}**-tier model`,
+                        "3. **Ignore** -- just keep working with your current setup if you disagree",
+                        "",
+                        "*Your choice will be observed and used to improve future recommendations.*",
+                    ].join("\n");
+                },
+            }),
+        },
+        event: async ({ event }) => {
+            if (event.type === "message.updated") {
+                const msg = event.properties?.info;
+                if (!msg) {
+                    return;
+                }
+                if (msg.role === "user" && msg.sessionID) {
+                    sessionModels.set(msg.sessionID, {
+                        providerID: msg.model?.providerID || "unknown",
+                        modelID: msg.model?.modelID || "unknown",
+                        agent: msg.agent || "unknown",
+                    });
+                }
+                if (msg.role === "assistant" && msg.sessionID) {
+                    sessionModels.set(msg.sessionID, {
+                        providerID: msg.providerID || "unknown",
+                        modelID: msg.modelID || "unknown",
+                        agent: msg.mode || "unknown",
+                    });
+                }
+            }
+            if (event.type === "session.idle" && pending) {
+                try {
+                    const projectRoot = worktree || directory;
+                    const sessionID = event.properties?.sessionID;
+                    const actualInfo = sessionID ? sessionModels.get(sessionID) : null;
+                    let accepted;
+                    let actualTier;
+                    let actualModel;
+                    if (actualInfo && actualInfo.providerID !== "unknown") {
+                        actualTier = inferTierFromModel(actualInfo.providerID, actualInfo.modelID);
+                        actualModel = `${actualInfo.providerID}/${actualInfo.modelID}`;
+                        accepted = actualTier === pending.tier;
+                    }
+                    appendHistory(projectRoot, {
+                        ts: pending.ts,
+                        prompt: truncate(pending.prompt, 200),
+                        recommendedTier: pending.tier,
+                        accepted,
+                        actualTier,
+                        actualModel,
+                    });
+                    if (sessionID) {
+                        sessionModels.delete(sessionID);
+                    }
+                }
+                catch {
+                    // Ignore history logging failures.
+                }
+                finally {
+                    pending = null;
+                }
+            }
+        },
+    };
+};
+export default TaskRouterPlugin;

package/examples/opencode/.opencode/agents/local-worker.md

@@ -0,0 +1,23 @@
+---
+description: Lightweight agent for simple tasks -- switch to this for trivial work
+mode: primary
+model: ollama/qwen3:8b
+temperature: 0.2
+---
+
+You are a lightweight coding assistant running on a local model.
+You handle simple, well-defined tasks efficiently without incurring API costs.
+
+Focus on:
+- Small code fixes, typos, and formatting
+- Simple scripts and utility snippets
+- File renaming and reorganization
+- Documentation edits and updates
+- Straightforward questions about code
+- Generating boilerplate and templates
+
+Guidelines:
+- Be concise and direct in your responses.
+- If a task seems too complex for your capabilities, explicitly suggest
+  the user switch to the build agent with a more capable model by pressing Tab.
+- Prefer simple, working solutions over clever ones.

package/examples/opencode/.opencode/commands/route.md

@@ -0,0 +1,7 @@
+---
+description: Analyze a task and recommend the best model/agent to use
+---
+
+Use the route_task tool to analyze the following task and recommend which model and agent I should use for it:
+
+$ARGUMENTS

package/examples/opencode/opencode.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "ollama": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "Ollama (local)",
+      "options": {
+        "baseURL": "http://localhost:11434/v1"
+      },
+      "models": {
+        "qwen3:8b": {
+          "name": "Qwen3 8B (local/free)",
+          "limit": {
+            "context": 32768,
+            "output": 8192
+          }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "opencode-task-router",
+  "version": "0.1.0",
+  "description": "OpenCode plugin that recommends the right model cost tier for a development task using a local Ollama classifier.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "examples",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run test:unit && npm run test:smoke",
+    "test:smoke": "node scripts/smoke-test.mjs",
+    "test:unit": "npm run build && node --test tests/*.test.mjs",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "opencode",
+    "plugin",
+    "ollama",
+    "routing",
+    "agent",
+    "task-router"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dougritter/opencode-task-router.git"
+  },
+  "bugs": {
+    "url": "https://github.com/dougritter/opencode-task-router/issues"
+  },
+  "homepage": "https://github.com/dougritter/opencode-task-router#readme",
+  "license": "MIT",
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.2.27"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "1.2.27",
+    "@types/node": "^24.3.0",
+    "typescript": "^5.9.2"
+  }
+}