opencode-raven 1.0.0

package/README.md

@@ -0,0 +1,111 @@
+# opencode-raven
+
+Search-first subagent for [opencode](https://opencode.ai) — intercepts search tool calls from other agents and routes them to a dedicated **@raven** agent with Context7, Exa AI, and Grep.app MCPs.
+
+## Why?
+
+Other agents (orchestrator, fixer, etc.) waste tokens and context on search tools. Raven gives them a single delegation target that's purpose-built for search, with the right MCPs wired in and a compact-output prompt.
+
+## Install
+
+```bash
+bun add opencode-raven
+```
+
+Then add to your `opencode.jsonc`:
+
+```jsonc
+{
+  "plugin": ["opencode-raven"]
+}
+```
+
+Restart opencode.
+
+## Commands
+
+| Command | Action |
+|---------|--------|
+| `/raven` | Show status — enabled/disabled, current model |
+| `/raven on` | Enable search tool redirection to @raven (default) |
+| `/raven off` | Disable interception — all agents can use search tools directly |
+| `/raven model <name>` | Change Raven's model (e.g. `/raven model opencode/deepseek-v4-flash-free`) |
+
+Config persists across restarts in `raven-config.json` (next to your `opencode.jsonc`).
+
+## Configuration
+
+### raven-config.json
+
+Created automatically in your project root on first toggle. Edit manually or use `/raven` commands:
+
+```json
+{
+  "enabled": true,
+  "model": "opencode/deepseek-v4-flash-free"
+}
+```
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `enabled` | `true` | Whether search tool interception is active |
+| `model` | *(from Raven.md)* | Override Raven's model without editing package files |
+
+### MCP servers
+
+All three MCPs are enabled by default:
+
+| MCP | URL | Notes |
+|-----|-----|-------|
+| Context7 | `https://mcp.context7.com/mcp` | No API key needed |
+| Exa AI | `https://mcp.exa.ai/mcp` | Requires Exa account |
+| Grep.app | `https://mcp.grep.app` | No API key needed |
+
+To disable an MCP, override it in your `opencode.jsonc`:
+
+```jsonc
+{
+  "mcp": {
+    "exa": { "type": "remote", "url": "https://mcp.exa.ai/mcp", "enabled": false }
+  }
+}
+```
+
+## How it works
+
+| Hook | What it does |
+|------|--------------|
+| `config` | Registers Raven agent, adds Context7/Exa/Grep.app MCPs, loads MCP guidance |
+| `chat.message` | Tracks Raven's session IDs so its own tools aren't blocked |
+| `command.execute.before` | Handles `/raven on\|off\|model\|status` |
+| `tool.execute.before` | Nukes search tool args for non-Raven agents (no wasted API calls) |
+| `tool.execute.after` | Replaces search tool output with redirect to Raven |
+
+**Blocked tools** (redirected to Raven for all agents except Raven itself):
+
+| Tool | Raven's equivalent |
+|------|-------------------|
+| `websearch_web_search_exa` | Exa AI (web search) |
+| `exa_web_search_exa` | Exa AI (web search via MCP) |
+| `exa_web_fetch_exa` | Exa AI (page fetch via MCP) |
+| `grep_app_searchGitHub` | Grep.app (GitHub examples) |
+| `grep` | grep/rg (local code search) |
+| `glob` | glob (file search) |
+
+**Unrestricted**: `webfetch`, `read`, `bash`, `task`, and all other tools.
+
+## Agent capabilities
+
+| Tool / MCP | Purpose |
+|------------|---------|
+| `read`, `glob`, `grep`, `list` | Local codebase inspection |
+| `bash` (`rg`, `grep`, `git grep`) | Local search commands |
+| Context7 | Library/framework/SDK/API docs |
+| Exa AI | Web search, news, pages, products |
+| Grep.app | Public GitHub examples |
+
+Raven returns compact findings: answer, sources, relevant details, recommended next step, and uncertainty.
+
+## License
+
+MIT

package/Raven.md

@@ -0,0 +1,61 @@
+---
+description: Search-only agent for web, docs, code, examples, and Unity project inspection.
+mode: subagent
+hidden: true
+model: opencode/deepseek-v4-flash-free
+reasoning_effort: low
+permission:
+  read: allow
+  glob: allow
+  grep: allow
+  list: allow
+  edit: deny
+  bash:
+
+    "rg *": allow
+    "grep *": allow
+    "git grep *": allow
+    "*": deny
+
+  task: deny
+---
+
+You are Raven.
+
+You search only.
+You return compact findings only.
+
+Use tools/MCPs like this:
+
+**Local code search:** use rg, grep, glob, list, and read only small relevant sections.
+
+**MCP usage guidance:**
+
+*Context7:*
+Use when implementing, configuring, or debugging code that depends on a library, framework, SDK, package, or API.
+Prefer Context7 over memory when docs may be version-specific or recently changed.
+
+*Exa AI:*
+Use for live web search, current information, company/product research, reading webpages, comparing tools, and broad external research.
+Use Exa when the answer may depend on recent updates, pricing, docs pages, releases, or online sources.
+
+*Grep.app:*
+Use for searching public GitHub code examples, real-world usage patterns, config examples, and how other projects structure similar code.
+Use Grep.app when docs are unclear or when implementation examples would help.
+
+Output format:
+
+Answer:
+* Short direct finding.
+
+Sources / locations:
+* File paths, URLs, docs, examples, or Unity objects checked.
+
+Relevant details:
+* Small notes only. No long code dumps.
+
+Recommended next step:
+* What the caller should do next.
+
+Uncertainty:
+* Anything unclear or not found.

package/index.ts

@@ -0,0 +1,237 @@
+import type { Plugin, PluginInput } from "@opencode-ai/plugin"
+import { readFileSync, writeFileSync, existsSync } from "node:fs"
+import { join } from "node:path"
+
+// ── Resolve paths relative to this package (works in node_modules/) ──
+const PKG_DIR = import.meta.dirname!
+
+const RAVEN_MD = join(PKG_DIR, "Raven.md")
+const MCP_GUIDANCE_MD = join(PKG_DIR, "mcp-guidance.md")
+
+// ── Search tools that should be intercepted for non-Raven agents ──
+const SEARCH_TOOLS = [
+  "websearch_web_search_exa",
+  "exa_web_search_exa",
+  "exa_web_fetch_exa",
+  "grep_app_searchGitHub",
+  "grep",
+  "glob",
+]
+
+// ── Config file shape ──
+interface RavenConfig {
+  enabled: boolean
+  model?: string
+}
+
+const DEFAULT_CONFIG: RavenConfig = { enabled: true }
+
+// ── Parse Raven.md frontmatter ──
+const ravenMd = readFileSync(RAVEN_MD, "utf-8")
+const { frontmatter: fm, prompt: ravenPrompt } = parseRavenMd(ravenMd)
+
+function parseRavenMd(raw: string): { frontmatter: Record<string, any>; prompt: string } {
+  const parts = raw.split("---")
+  if (parts.length < 3) {
+    throw new Error("Raven.md missing frontmatter (--- delimiters)")
+  }
+  return { frontmatter: parseYaml(parts[1]), prompt: parts.slice(2).join("---").trim() }
+}
+
+// ── Minimal YAML parser (handles the structure used in Raven.md) ──
+function parseYaml(yaml: string): Record<string, any> {
+  const lines = yaml.split("\n")
+  const root: Record<string, any> = {}
+  const stack: Array<{ obj: Record<string, any>; indent: number }> = [
+    { obj: root, indent: -1 },
+  ]
+
+  for (const rawLine of lines) {
+    const line = rawLine.trimEnd()
+    if (!line.trim() || line.trim().startsWith("#")) continue
+
+    const indent = line.search(/\S/)
+    const colonIdx = line.indexOf(":")
+    if (colonIdx === -1) continue
+
+    const rawKey = line.slice(indent, colonIdx).trim()
+    const key =
+      (rawKey.startsWith('"') && rawKey.endsWith('"')) ||
+      (rawKey.startsWith("'") && rawKey.endsWith("'"))
+        ? rawKey.slice(1, -1)
+        : rawKey
+
+    const rawValue = line.slice(colonIdx + 1).trim()
+
+    while (stack.length > 1 && stack[stack.length - 1].indent >= indent) {
+      stack.pop()
+    }
+    const current = stack[stack.length - 1].obj
+
+    if (!rawValue) {
+      const nested: Record<string, any> = {}
+      current[key] = nested
+      stack.push({ obj: nested, indent })
+    } else {
+      let value: any = rawValue
+      if (
+        (value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))
+      ) {
+        value = value.slice(1, -1)
+      } else if (value === "true") {
+        value = true
+      } else if (value === "false") {
+        value = false
+      }
+      current[key] = value
+    }
+  }
+
+  return root
+}
+
+// ── Move unknown frontmatter fields into options ──
+const KNOWN_KEYS = new Set([
+  "description", "mode", "hidden", "model", "permission",
+  "prompt", "name", "color", "steps", "disable",
+  "temperature", "top_p", "variant",
+])
+
+function extractOptions(fm: Record<string, any>): Record<string, any> {
+  const options: Record<string, any> = {}
+  for (const key of Object.keys(fm)) {
+    if (!KNOWN_KEYS.has(key)) options[key] = fm[key]
+  }
+  return options
+}
+
+// ── Plugin ──
+export default ((input: PluginInput) => {
+  // Config file lives in the project directory (next to opencode.jsonc)
+  const configFile = join(input.directory, "raven-config.json")
+
+  function loadConfig(): RavenConfig {
+    try {
+      if (existsSync(configFile)) {
+        const raw = JSON.parse(readFileSync(configFile, "utf-8"))
+        return {
+          enabled: raw.enabled !== false,
+          model: raw.model,
+        }
+      }
+    } catch { /* ignore corruption, use defaults */ }
+    return { ...DEFAULT_CONFIG }
+  }
+
+  function saveConfig(config: RavenConfig) {
+    try {
+      writeFileSync(configFile, JSON.stringify(config, null, 2) + "\n")
+    } catch { /* non-fatal: config won't persist but toggle still works in-session */ }
+  }
+
+  let config = loadConfig()
+  const ravenSessions = new Set<string>()
+
+  return {
+    config(configInput: any) {
+      // MCP servers
+      configInput.mcp = configInput.mcp || {}
+      configInput.mcp.context7 = {
+        type: "remote", url: "https://mcp.context7.com/mcp", enabled: true,
+      }
+      configInput.mcp.exa = {
+        type: "remote", url: "https://mcp.exa.ai/mcp", enabled: true,
+      }
+      configInput.mcp.grep_app = {
+        type: "remote", url: "https://mcp.grep.app", enabled: true,
+      }
+
+      // Inject MCP guidance as a startup instruction file (absolute path for npm compat)
+      configInput.instructions = configInput.instructions || []
+      if (!configInput.instructions.includes(MCP_GUIDANCE_MD)) {
+        configInput.instructions.push(MCP_GUIDANCE_MD)
+      }
+
+      // Register Raven from Raven.md, with config file overrides
+      configInput.agent = configInput.agent || {}
+      configInput.agent.raven = {
+        description: fm.description || "",
+        mode: fm.mode || "subagent",
+        hidden: fm.hidden !== undefined ? fm.hidden : false,
+        model: config.model || fm.model,
+        options: extractOptions(fm),
+        permission: fm.permission || {},
+        prompt: ravenPrompt,
+      }
+
+      // Register /raven command
+      configInput.command = configInput.command || {}
+      if (!configInput.command.raven) {
+        configInput.command.raven = {
+          template: "Manage Raven: /raven on|off|model <name>|status",
+          description: "Toggle search interception or change Raven's model",
+        }
+      }
+    },
+
+    // Track Raven sessions so we don't block its own tools
+    "chat.message"(input: any, _output: any) {
+      if (input.agent === "raven") {
+        ravenSessions.add(input.sessionID)
+      }
+    },
+
+    // /raven on|off|model <name>|status
+    "command.execute.before"(input: any, output: any) {
+      if (input.command !== "raven") return
+      output.parts.length = 0
+      const raw = input.arguments.trim()
+      const arg = raw.toLowerCase()
+
+      if (arg === "on") {
+        config.enabled = true
+        saveConfig(config)
+        output.parts.push({ type: "text", text: "Raven search interception enabled. Non-Raven agents will be redirected to @raven for search tools." })
+      } else if (arg === "off") {
+        config.enabled = false
+        saveConfig(config)
+        output.parts.push({ type: "text", text: "Raven search interception disabled. All agents can use search tools directly." })
+      } else if (arg.startsWith("model ")) {
+        const model = raw.slice(6).trim()
+        if (!model) {
+          output.parts.push({ type: "text", text: `Usage: /raven model <name>\nCurrent model: ${config.model || fm.model || "(default)"}` })
+        } else {
+          config.model = model
+          saveConfig(config)
+          output.parts.push({ type: "text", text: `Raven model set to: ${model}\nRestart opencode for the change to take effect.` })
+        }
+      } else {
+        const enabled = config.enabled ? "enabled" : "disabled"
+        const model = config.model || fm.model || "(default)"
+        output.parts.push({ type: "text", text: `Raven is ${enabled}. Model: ${model}\n\nCommands:\n  /raven on      — enable search interception\n  /raven off     — disable search interception\n  /raven model <name> — change Raven's model (requires restart)` })
+      }
+    },
+
+    "tool.execute.before"(input: any, output: any) {
+      if (!config.enabled) return
+      if (!SEARCH_TOOLS.includes(input.tool)) return
+      if (ravenSessions.has(input.sessionID)) return
+      // Break args to prevent actual API calls
+      const args = output.args || {}
+      if ("query" in args) args.query = ""
+      output.args = { ...output.args, ...args }
+    },
+
+    "tool.execute.after"(input: any, output: any) {
+      if (!config.enabled) return
+      if (!SEARCH_TOOLS.includes(input.tool)) return
+      if (ravenSessions.has(input.sessionID)) return
+      const msg =
+        "This tool is disabled. Delegate to Raven instead: use the task tool with subagent_type=\"raven\"."
+      output.output = msg
+      const raw = output as any
+      if (raw.content?.[0]?.text) raw.content[0].text = msg
+    },
+  }
+}) satisfies Plugin

package/mcp-guidance.md

@@ -0,0 +1,5 @@
+## MCP usage guidance — delegate to Raven (subagent_type="raven") for these:
+
+- Context7: use when implementing, configuring, or debugging code that depends on a library, framework, SDK, package, or API. Prefer over memory when docs may be version-specific or recently changed.
+- Exa AI: use for live web search, current information, company/product research, reading webpages, comparing tools, and broad external research. Use when the answer depends on recent updates, pricing, docs pages, releases, or online sources.
+- Grep.app: use for searching public GitHub code examples, real-world usage patterns, config examples, and how other projects structure similar code. Use when docs are unclear or when implementation examples would help.

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "opencode-raven",
+  "version": "1.0.0",
+  "description": "Search-first subagent for opencode — intercepts search tools and routes them to a dedicated @raven agent with Context7, Exa AI, and Grep.app MCPs",
+  "main": "./index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "types": "./index.ts",
+  "files": [
+    "index.ts",
+    "Raven.md",
+    "Raven.png",
+    "mcp-guidance.md",
+    "README.md"
+  ],
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "search",
+    "subagent",
+    "mcp",
+    "context7",
+    "exa",
+    "grep.app"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.0.0"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  }
+}