{"id":50402550,"url":"https://github.com/evilayman/opencode-raven","last_synced_at":"2026-06-05T05:00:48.978Z","repository":{"id":361085261,"uuid":"1253030135","full_name":"evilayman/opencode-raven","owner":"evilayman","description":"Raven is a context firewall for OpenCode. It routes noisy search, docs, web, GitHub, and MCP calls through a free focused agent before they hit your main model. saving cost and context!","archived":false,"fork":false,"pushed_at":"2026-06-03T14:45:37.000Z","size":6948,"stargazers_count":26,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-04T04:13:34.534Z","etag":null,"topics":["ai-agent","context-engineering","context-management","context7","exa","grep-app","mcp","opencode","opencode-plugin","search","subagent","tool-routing","web-search"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/evilayman.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-29T05:06:56.000Z","updated_at":"2026-06-03T04:37:15.000Z","dependencies_parsed_at":"2026-06-03T03:00:47.238Z","dependency_job_id":null,"html_url":"https://github.com/evilayman/opencode-raven","commit_stats":null,"previous_names":["evilayman/opencode-raven"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/evilayman/opencode-raven","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evilayman%2Fopencode-raven","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evilayman%2Fopencode-raven/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evilayman%2Fopencode-raven/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evilayman%2Fopencode-raven/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/evilayman","download_url":"https://codeload.github.com/evilayman/opencode-raven/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evilayman%2Fopencode-raven/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33930311,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-05T02:00:06.157Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","context-engineering","context-management","context7","exa","grep-app","mcp","opencode","opencode-plugin","search","subagent","tool-routing","web-search"],"created_at":"2026-05-31T00:03:23.723Z","updated_at":"2026-06-05T05:00:48.913Z","avatar_url":"https://github.com/evilayman.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# opencode-raven\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003cimg src=\"Raven.png\" alt=\"Raven\" width=\"768\" /\u003e\u003c/td\u003e\n\u003ctd\u003e\n\u003cstrong\u003eSearch-first subagent for \u003ca href=\"https://opencode.ai\"\u003eopencode\u003c/a\u003e\u003c/strong\u003e\u003cbr/\u003e\nIntercepts search tool calls and routes them to a Raven agent with full local filesystem access plus Context7, Exa AI, and Grep.app MCPs.\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n## Why?\n\nSearch is the most common thing agents do — and the most wasteful. Every search call burns tokens and context on results that a cheap, focused agent could handle better. Raven fixes three problems:\n\n1. **Cost** — Use a free model like `opencode/deepseek-v4-flash-free` for all search, saving your expensive model's context for actual work.\n2. **Reliability** — Hard-enforced interception. Other plugins suggest delegation; Raven *blocks* search tools for non-Raven agents and redirects them. No more agents ignoring your instructions and searching directly.\n3. **Simplicity** — One plugin, one agent, auto-configured. No bundled agents or features you don't need. Call Raven directly with `@Raven` or let agents use `raven_seek`. Works with any agent or workflow. Just add it to `opencode.jsonc` and restart.\n\n## Install\n\n```bash\nbun add opencode-raven\n# or\nnpm install opencode-raven\n```\n\nThen add to your `opencode.jsonc`:\n\n```jsonc\n{\n  \"plugin\": [\"opencode-raven\"]\n}\n```\n\nRestart opencode.\n\n## Commands\n\n| Command | Action |\n|---------|--------|\n| `/raven` | Show status — enabled/disabled, version, update availability, model, reasoning effort, timeout (no args) |\n| `/raven on` | Enable search tool redirection (default) |\n| `/raven off` | Disable interception — all agents can use search tools directly |\n| `/raven update` | Check npm for a newer Raven, clear opencode's plugin cache if needed, then restart opencode |\n| `/raven model \u003cname\u003e` | Change Raven's model (requires restart) |\n| `/raven effort \u003cvalue\u003e` | Change Raven's reasoning effort (requires restart) |\n| `/raven timeout \u003cseconds\u003e` | Change raven_seek timeout (min 10s, takes effect immediately) |\n| `/raven stats` | Show context processed (session + all-time, bytes + tokens) |\n\nConfig persists across restarts in `~/.config/opencode/raven-config.json` (global, shared across all projects). Auto-created on first run.\n\n## Updates\n\nopencode caches npm plugins, so `\"opencode-raven\"` / `\"opencode-raven@latest\"` may not automatically refresh after a new npm release.\n\nRaven checks npm after the TUI starts. If an update is available, it shows a notification. `/raven` also shows the current version and update availability. To update:\n\n```txt\n/raven update\n```\n\nThis checks npm, clears Raven's opencode plugin cache when a newer version exists, and tells you to restart opencode.\n\nManual alternatives:\n\n```bash\nbun update --latest opencode-raven\n# or\nnpm install opencode-raven@latest\n```\n\nIf opencode still loads the old cached plugin, clear the opencode plugin cache and restart:\n\n```powershell\nRemove-Item -Recurse -Force \"$HOME\\.cache\\opencode\\packages\\opencode-raven*\"\n```\n\n```bash\nrm -rf ~/.cache/opencode/packages/opencode-raven*\n```\n\n## Direct access\n\nYou can call Raven directly with `@Raven` in any opencode chat. The Raven agent runs with full filesystem and MCP access — no permission prompts.\n\n## raven_seek\n\nWhen search, fetch, or discovery tools are blocked, agents use **`raven_seek`** — a unified tool that handles local codebase search, filesystem discovery, specific URL/page reads, web/docs research, GitHub examples, and command-output/system inspection. Output includes elapsed time and tokens processed.\n\n```\nraven_seek(query: \"how to use useEffect cleanup\")\nraven_seek(query: \"Fetch/read https://example.com and summarize install steps\")\nraven_seek(query: \"Check whether archivemount/libarchive supports ISO or UDF. Use docs, web, or command output as needed.\")\n```\n\nThe agent doesn't see Raven's internal tool calls — just the final findings. Raven parallelizes independent searches internally within a single session.\n\n## Configuration\n\n### raven-config.json\n\nLocated at `~/.config/opencode/raven-config.json`. Auto-created on first run and auto-migrated on startup when new default fields are added. Edit manually or use `/raven` commands:\n\n```json\n{\n  \"enabled\": true,\n  \"model\": \"opencode/deepseek-v4-flash-free\",\n  \"reasoning_effort\": \"low\",\n  \"excludeAgents\": [],\n  \"excludeTools\": [],\n  \"timeout\": 180\n}\n```\n\n| Field | Default | Description |\n|-------|---------|-------------|\n| `enabled` | `true` | Whether search tool interception is active |\n| `model` | *(from Raven.md)* | Override Raven's model without editing package files |\n| `reasoning_effort` | *(from Raven.md)* | Override Raven's reasoning effort (e.g. `\"low\"`, `\"medium\"`, `\"high\"`) |\n| `excludeAgents` | `[]` | Agents that bypass search tool blocking (case-insensitive). e.g. `[\"librarian\", \"explorer\"]` |\n| `excludeTools` | `[]` | Tools that never get blocked. e.g. `[\"glob\", \"webfetch\"]` |\n| `timeout` | `180` | Max seconds for a `raven_seek` call. On timeout the session is kept for inspection. |\n| `stats` | *(auto)* | Session + global context processed by Raven (bytes + tokens). Managed automatically. |\n\n### MCP servers\n\nAll three MCPs work without API keys. Add keys for higher rate limits:\n\n| MCP | URL | API key |\n|-----|-----|---------|\n| Context7 | `https://mcp.context7.com/mcp` | Free key at [context7.com/dashboard](https://context7.com/dashboard) — higher limits |\n| Exa AI | `https://mcp.exa.ai/mcp` | Free key at [exa.ai](https://exa.ai) — higher limits |\n| Grep.app | `https://mcp.grep.app` | Not available — public API, no key needed |\n\nRaven merges these MCP defaults with your existing `opencode.jsonc` settings, preserving custom headers, URLs, and `enabled: false` overrides.\n\nTo add an API key, override the MCP in your `opencode.jsonc` with a `headers` field:\n\n```jsonc\n{\n  \"mcp\": {\n    \"exa\": {\n      \"type\": \"remote\",\n      \"url\": \"https://mcp.exa.ai/mcp\",\n      \"headers\": { \"x-api-key\": \"{env:EXA_API_KEY}\" },\n      \"enabled\": true\n    }\n  }\n}\n```\n\nTo disable an MCP entirely:\n\n```jsonc\n{\n  \"mcp\": {\n    \"exa\": { \"type\": \"remote\", \"url\": \"https://mcp.exa.ai/mcp\", \"enabled\": false }\n  }\n}\n```\n\n## How it works\n\n| Hook | What it does |\n|------|--------------|\n| `config` | Registers Raven agent, merges Context7/Exa/Grep.app MCP defaults, loads MCP guidance |\n| `tool` | Registers `raven_seek` — creates Raven sessions with timeout, error recovery, timing, and session tree visibility. Tracks context processed for stats (both `raven_seek` and direct `@Raven`). |\n| `chat.message` | Tracks agent ↔ session mapping for allowlist and Raven exclusion |\n| `event` | Shows startup update notifications after the TUI event stream is ready |\n| `command.execute.before` | Handles `/raven on\\|off\\|update\\|model\\|effort\\|timeout\\|stats\\|status` |\n| `tool.execute.before` | Blocks search tools for non-Raven, non-excluded agents (respects `excludeTools`). Error output gives the next `raven_seek(query=\"...\")` call. Injects concise `\u003craven_guidance\u003e` into subagent prompts. |\n| `tool.execute.after` | Counts output bytes from direct `@Raven` calls for accurate stats. |\n\n### Blocked tools (redirected except for Raven and any agents in `excludeAgents`)\n\n**Dedicated search tools:**\n\n| Tool | Source |\n|------|--------|\n| `grep`, `glob`, `webfetch`, `fetch`, `websearch` | Built-in |\n| `websearch_web_search_exa` | WebSearch MCP |\n| `context7_resolve-library-id`, `context7_query-docs` | Context7 MCP |\n| `exa_web_search_exa`, `exa_web_fetch_exa`, `exa_web_search_advanced_exa` | Exa AI MCP |\n| `exa_company_research_exa`, `exa_crawling_exa`, `exa_people_search_exa` | Exa AI MCP |\n| `exa_linkedin_search_exa`, `exa_get_code_context_exa` | Exa AI MCP |\n| `exa_deep_researcher_start`, `exa_deep_researcher_check`, `exa_deep_search_exa` | Exa AI MCP |\n| `grep_app_searchGitHub` | Grep.app MCP |\n\n**Bash commands** — intercepted when the command matches a primary search/discovery pattern:\n\n| Pattern | Examples |\n|---------|----------|\n| Content search | `rg`, `grep`, `egrep`, `fgrep`, `git grep`, `ack`, `ag`, `findstr`, `Select-String` |\n| Filesystem exploration | `Get-ChildItem -Recurse`, `gci -Recurse`, `Get-ChildItem -Filter`, `find -name`, `find -type`, `ls -R`, `ls --recursive`, `dir /s` |\n| Shell bypass | `cmd /c dir /s`, `cmd /c findstr`, `cmd /c find`, `cmd /c tree` |\n\n**Unrestricted for non-Raven agents**: `read`, `task`, `subtask`, `raven_seek`, and non-search `bash` commands.\n\n**Allowed output filters**: Piped filters like `command | grep ...`, `command | rg ...`, `command | findstr ...`, and `command | head ...` are allowed. Raven only blocks search commands when they are used as primary discovery commands, not when they filter bounded output from another command.\n\n**Bash quote stripping**: Quoted content in bash commands is stripped before pattern matching — `echo \"use grep here\"` won't falsely trigger blocking.\n\n**Comment stripping**: Shell comments are stripped before matching — `# use grep later` won't falsely trigger blocking.\n\n**Subagent guidance**: Every non-Raven, non-excluded subagent gets `\u003craven_guidance\u003e` injected into its prompt at spawn time.\n\n## Agent capabilities\n\nRaven itself has access to these tools (blocked for other agents by the plugin):\n\n| Tool / MCP | Purpose |\n|------------|---------|\n| `read`, `glob`, `grep`, `list` | Local codebase inspection |\n| `bash` (all commands) | Full local shell access (`rg`, `grep`, `dir`, `ls`, `Get-ChildItem`, `find`, etc.) |\n| `external_directory` | Allowed — no permission prompts when accessing paths outside the workspace |\n| Context7 | Library/framework/SDK/API docs |\n| Exa AI | Web search, news, pages, products |\n| Grep.app | Public GitHub examples |\n\n`raven_seek` is denied inside Raven itself so Raven cannot recursively call its own wrapper tool. Raven uses direct tools/MCPs instead.\n\nRaven returns compact findings: answer, sources, relevant details, recommended next step, and uncertainty.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevilayman%2Fopencode-raven","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fevilayman%2Fopencode-raven","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevilayman%2Fopencode-raven/lists"}