opencodekit 0.15.12 → 0.15.13

package/README.md

@@ -80,8 +80,8 @@ Background Plugins:
 Supporting:
   • 30+ Skills (domain expertise loaded on-demand)
   • 26+ Commands (workflow shortcuts)
-  • 3 MCP Services (context7, exa, gh_grep) + skill-embedded MCPs
-  • Custom Tools (memory-*, observation, ast-grep, lsp-*)
+  • 3 MCP Services (context7, exa) + grep-search tool + skill-embedded MCPs
+  • Custom Tools (memory-*, observation, grep-search, lsp-*)
   • Beads task tracking (`bd` CLI for multi-session workflows)
   • Manual Handoffs (clean phase transitions)
 ```
@@ -223,9 +223,9 @@ You've successfully set up OpenCodeKit when:
 - ✅ Skills load on-demand (30+ skills)
 - ✅ Delegation is clear (build → specialized subagents)
 - ✅ `/handoff` creates portable bundles (.opencode/memory/handoffs/)
-- ✅ MCP services configured (context7, gh_grep + skill-embedded)
+- ✅ Tools configured (context7, grep-search + skill-embedded MCP)
 - ✅ Background plugins active (enforcer, compactor, truncator)
-- ✅ Custom tools available (memory-_, observation, ast-grep, lsp-_)
+- ✅ Custom tools available (memory-_, observation, grep-search, lsp-_)
 - ✅ Environment variables set (.opencode/.env with API keys)
 
 ---

package/dist/index.js

@@ -750,7 +750,7 @@ var cac = (name = "") => new CAC(name);
 // package.json
 var package_default = {
   name: "opencodekit",
-  version: "0.15.12",
+  version: "0.15.13",
   description: "CLI tool for bootstrapping and managing OpenCodeKit projects",
   keywords: ["agents", "cli", "mcp", "opencode", "opencodekit", "template"],
   license: "MIT",

package/dist/template/.opencode/README.md

@@ -180,16 +180,19 @@ Plugins run automatically in every session:
 **Enabled by default (3 total):**
 
 1. **context7** - Up-to-date library documentation (37.6k+ libraries)
-   - Requires: CONTEXT7_API_KEY
-   - GitHub: https://github.com/upstash/context7
+   - Native tools: `context7_resolve_library_id()` and `context7_query_docs()`
+   - Requires: CONTEXT7_API_KEY (optional - public libraries work without it)
+   - Step 1: Resolve library name → `/libraryId`
+   - Step 2: Query docs with the libraryId
 
 2. **exa** - Web search + code context (3.3k+ repos)
    - Requires: EXA_API_KEY
    - GitHub: https://github.com/exa-labs/exa-mcp-server
 
-3. **gh_grep** - Search 1M+ public GitHub repositories
+3. **grep-search** - Search 1M+ public GitHub repositories via grep.app
+   - Native tool: `grep_search({ query: "...", language: [...] })`
    - No API key needed (public service)
-   - GitHub: https://github.com/Shachlan/grep.app-mcp
+   - Direct HTTP wrapper (no MCP overhead)
 
 **Skill-Embedded MCP (load on-demand):**
 

package/dist/template/.opencode/agent/scout.md

@@ -93,7 +93,7 @@ Run 2-3 tool calls in parallel.
 **Triggers:** "how do others", "compare", "best practices", "production patterns"
 **Target:** Summary, 3-5 code examples, tradeoffs, recommendation
 
-1. Search GitHub with gh_grep_searchGitHub (vary queries for different angles)
+1. Search GitHub with grep_search (vary queries for different angles)
 2. Compare 3-5 implementations from different repositories
 3. Synthesize common patterns
 4. Note tradeoffs and edge cases
@@ -104,30 +104,101 @@ Run 4-6 tool calls in parallel.
 
 Every code reference must include a GitHub permalink. Never link to a branch or tag that can change.
 
-To construct a permalink: use `gh_grep_searchGitHub` to find code, then build the URL from the repository and file path returned. Format: `https://github.com/owner/repo/blob/<sha>/path/to/file#L10-L20`.
+To construct a permalink: use `grep_search` to find code, then build the URL from the repository and file path returned. Format: `https://github.com/owner/repo/blob/<sha>/path/to/file#L10-L20`.
 
 ## Tool Priority (External Sources Only)
 
-| Priority | Tool                 | Use Case                                  | Speed   |
-| -------- | -------------------- | ----------------------------------------- | ------- |
-| 1        | memory-search        | Past research findings                    | Instant |
-| 2        | context7             | Official library docs                     | Fast    |
-| 3        | codesearch           | Exa Code API for SDK/library patterns     | Fast    |
-| 4        | gh_grep_searchGitHub | Cross-repo GitHub code search (1M+ repos) | Medium  |
-| 5        | webfetch             | Specific doc URLs, READMEs, changelogs    | Medium  |
-| 6        | opensrc + LSP        | Clone & analyze source code               | Slow    |
-| 7        | websearch            | Tutorials, blog posts, recent news        | Slow    |
+| Priority | Tool          | Use Case                                  | Speed   |
+| -------- | ------------- | ----------------------------------------- | ------- |
+| 1        | memory-search | Past research findings                    | Instant |
+| 2        | context7      | Official library docs                     | Fast    |
+| 3        | codesearch    | Exa Code API for SDK/library patterns     | Fast    |
+| 4        | grep_search   | Cross-repo GitHub code search (1M+ repos) | Medium  |
+| 5        | webfetch      | Specific doc URLs, READMEs, changelogs    | Medium  |
+| 6        | opensrc + LSP | Clone & analyze source code               | Slow    |
+| 7        | websearch     | Tutorials, blog posts, recent news        | Slow    |
 
 **Rule:** Exhaust faster tools before slower ones. Run tools in parallel when independent.
 
-## gh_grep_searchGitHub Tool
+## context7 Tools
+
+Use to access up-to-date library documentation (37.6k+ libraries).
+
+### Two-Step Process
+
+**Step 1: Resolve Library ID**
+
+```typescript
+context7_resolve_library_id({
+  libraryName: "react",              // Required - package/library name
+  query?: "hooks composition",        // Optional - search context
+  limit?: 5                           // Optional - max results (default: 5)
+})
+```
+
+Returns library IDs like `/facebook/react`, `/nodejs/node`, etc.
+
+**Step 2: Query Documentation**
+
+```typescript
+context7_query_docs({
+  libraryId: "/facebook/react",      // From resolve step
+  topic: "useState hook",             // What you want to know
+  maxTokens?: 8000                   // Optional - response size
+})
+```
+
+### Query Patterns
+
+**Good queries (specific features):**
+
+- `useState hook` - Find React useState documentation
+- `async/await` - Node.js async patterns
+- `type decorators` - TypeScript types and decorators
+- `setup instructions` - Getting started guides
+
+**Bad queries (too vague):**
+
+- `react` - Too broad
+- `best practices` - Not a feature
+- `how to use` - Natural language
+
+### Examples
+
+```typescript
+// Find React docs
+const reactId = context7_resolve_library_id({ libraryName: "react" });
+context7_query_docs({ libraryId: reactId, topic: "useEffect cleanup" });
+
+// Find TypeScript docs
+const tsId = context7_resolve_library_id({
+  libraryName: "typescript",
+  query: "types",
+});
+context7_query_docs({ libraryId: tsId, topic: "generic types" });
+
+// Find Node.js docs
+const nodeId = context7_resolve_library_id({ libraryName: "nodejs" });
+context7_query_docs({ libraryId: nodeId, topic: "streams API" });
+```
+
+### Failure Handling
+
+| Problem           | Solution                                       |
+| ----------------- | ---------------------------------------------- |
+| Library not found | Check exact name; try shorter/different names  |
+| No docs for topic | Broaden query - search parent concepts instead |
+| Empty results     | Try related terms or "API reference"           |
+| API error         | Verify CONTEXT7_API_KEY is set (optional)      |
+
+## grep_search Tool
 
 Use for cross-repository code search across 1M+ public GitHub repositories.
 
 ### Schema
 
 ```typescript
-gh_grep_searchGitHub({
+grep_search({
   query: string,              // Required - search pattern (literal code, not keywords)
   repo?: string,              // Optional - filter to specific repo (e.g., "vercel/ai")
   language?: string[],        // Optional - e.g., ["TypeScript", "TSX"]
@@ -157,22 +228,22 @@ gh_grep_searchGitHub({
 
 ```typescript
 // Basic repo search
-gh_grep_searchGitHub({ query: "batch_tool", repo: "anomalyco/opencode" });
+grep_search({ query: "batch_tool", repo: "anomalyco/opencode" });
 
 // With language filter
-gh_grep_searchGitHub({
+grep_search({
   query: "getServerSession",
   language: ["TypeScript", "TSX"],
 });
 
 // Regex pattern (multi-line)
-gh_grep_searchGitHub({
+grep_search({
   query: "(?s)useEffect\\(\\(\\) => {.*removeEventListener",
   useRegexp: true,
 });
 
 // Path filter for specific files
-gh_grep_searchGitHub({
+grep_search({
   query: "CORS(",
   language: ["Python"],
   matchCase: true,
@@ -184,7 +255,7 @@ gh_grep_searchGitHub({
 | Problem          | Solution                                         |
 | ---------------- | ------------------------------------------------ |
 | Empty results    | Broaden query - search concepts, not exact names |
-| MCP server error | Fall back to `codesearch` or `websearch`         |
+| API error        | Fall back to `codesearch` or `websearch`         |
 | Rate limited     | Reduce parallel calls, go sequential             |
 | Too many results | Add `language` or `path` filters                 |
 
@@ -316,8 +387,8 @@ Structure your response as:
 
 ```
 context7 fails → try codesearch for patterns
-codesearch empty → try gh_grep_searchGitHub with broader query
-gh_grep_searchGitHub empty → webfetch specific doc URLs if known
+codesearch empty → try grep_search with broader query
+grep_search empty → webfetch specific doc URLs if known
 still stuck → opensrc clone + LSP analysis
 last resort → websearch for tutorials/blogs
 ```
@@ -327,10 +398,10 @@ last resort → websearch for tutorials/blogs
 **context7 doesn't find library:**
 
 1. Try `codesearch({ query: "<library> <function> example" })`
-2. Try `gh_grep_searchGitHub({ query: "import.*from.*<library>", language: ["TypeScript"] })`
+2. Try `grep_search({ query: "import.*from.*<library>", language: ["TypeScript"] })`
 3. Clone with `npx opensrc <library>` and read source
 
-**gh_grep_searchGitHub returns nothing:**
+**grep_search returns nothing:**
 
 - Broaden query: search concepts, not exact function names
 - Remove specific repo filter to search across all repos
@@ -339,9 +410,9 @@ last resort → websearch for tutorials/blogs
 - Search for error messages, config patterns, or import statements
 - Fall back to `codesearch` for conceptual queries
 
-**gh_grep_searchGitHub MCP error:**
+**grep_search API error:**
 
-- MCP server at `mcp.grep.app` may be temporarily down
+- The grep.app API may be temporarily unavailable
 - Fall back to `codesearch` for similar functionality
 - Use `opensrc` to clone specific repos and search locally
 - Try `websearch` as last resort
@@ -368,6 +439,6 @@ NO URL GUESSING: Only use URLs from tools or user input.
 CITE EVERYTHING: No claims without source links.
 
 Quick: context7 → codesearch → websearch (2-3 parallel calls)
-Deep: gh_grep (4-6 parallel calls) → compare 3-5 repos → synthesize
-Fallback: context7 → codesearch → gh_grep → webfetch → opensrc → websearch
+Deep: grep_search (4-6 parallel calls) → compare 3-5 repos → synthesize
+Fallback: context7 → codesearch → grep_search → webfetch → opensrc → websearch
 ```

package/dist/template/.opencode/command/research-ui.md

@@ -212,7 +212,7 @@ context7_resolve_library_id({
 });
 
 // Real-world implementations
-gh_grep_searchGitHub({
+grep_search({
   query: "[pattern to find]",
   language: ["TypeScript", "TSX"],
   path: "components/",

package/dist/template/.opencode/command/research.md

@@ -95,7 +95,7 @@ If memory search fails (Ollama not running), continue to external sources.
 2. **Official docs** (high trust) - What does the library documentation say?
 3. **Context7** (high trust) - API usage and examples
 4. **Source code** (high trust) - Library implementation (use `source-code-research` skill)
-5. **GitHub examples** (medium trust) - Real-world patterns via codesearch/gh_grep
+5. **GitHub examples** (medium trust) - Real-world patterns via codesearch/grep_search
 6. **Web search** (lower trust) - Only if tiers 1-5 don't answer
 
 ## Research

package/dist/template/.opencode/memory/observations/2026-01-28-decision-gh-grep-mcp-wrapper-vs-native-grep-searc.md

@@ -0,0 +1,21 @@
+---
+type: decision
+created: 2026-01-28T16:59:35.621Z
+confidence: high
+valid_until: null
+superseded_by: null
+concepts: ["grep-search", "MCP", "native tool", "architecture", "best practices"]
+---
+
+# 🎯 gh-grep MCP wrapper vs native grep-search tool
+
+🟢 **Confidence:** high
+
+Created two implementations for GitHub code search:
+
+1. **Native tool** (.opencode/tool/grep-search.ts): TypeScript wrapper around grep.app API - WORKING ✅
+2. **MCP skill** (.opencode/skill/gh-grep/): Skill wrapper that calls uvx grep-mcp server - BROKEN ❌
+
+The MCP server has an argument parsing bug ('str' object has no attribute 'get') that prevents tool execution. Even the SKILL.md documentation admits: "Note: The MCP server (grep-mcp) may have bugs. The native grep_search tool is recommended."
+
+**Key insight**: We already documented the problem and recommended against the MCP approach. The native tool works perfectly and doesn't require external process dependencies.

package/dist/template/.opencode/memory/research/opencode-mcp-bug-report.md

@@ -94,10 +94,13 @@ The bug is in **OpenCode's tool response handler**, not the MCP connection layer
 2. `opencode mcp debug` shows HTTP 200 OK responses
 3. The error happens only when the AI agent calls the tool
 
-## Workaround
+## Resolution
 
-Use alternative tools that don't go through MCP:
+✅ **FIXED** - Replaced MCP tools with native HTTP wrappers:
 
+- `context7_resolve-library-id` - Native HTTP wrapper (works)
+- `context7_query-docs` - Native HTTP wrapper (works)
+- `grep-search` - Native HTTP wrapper (works)
 - `codesearch` (Exa Code API) - works
 - `websearch` (Exa Web Search) - works
 

package/dist/template/.opencode/opencode.json

@@ -49,53 +49,22 @@
   "experimental": {},
   "formatter": {
     "biome": {
-      "command": [
-        "npx",
-        "@biomejs/biome",
-        "check",
-        "--write",
-        "$FILE"
-      ],
-      "extensions": [
-        ".js",
-        ".jsx",
-        ".ts",
-        ".tsx",
-        ".json",
-        ".jsonc"
-      ]
+      "command": ["npx", "@biomejs/biome", "check", "--write", "$FILE"],
+      "extensions": [".js", ".jsx", ".ts", ".tsx", ".json", ".jsonc"]
     },
     "cargo-fmt": {
-      "command": [
-        "cargo",
-        "fmt",
-        "--",
-        "$FILE"
-      ],
-      "extensions": [
-        ".rs"
-      ]
+      "command": ["cargo", "fmt", "--", "$FILE"],
+      "extensions": [".rs"]
     },
     "java-formatter": {
-      "command": [
-        "google-java-format",
-        "--replace",
-        "$FILE"
-      ],
+      "command": ["google-java-format", "--replace", "$FILE"],
       "environment": {
         "JAVA_HOME": "{env:JAVA_HOME}"
       },
-      "extensions": [
-        ".java"
-      ]
+      "extensions": [".java"]
     },
     "oxfmt": {
-      "command": [
-        "npx",
-        "oxfmt",
-        "--write",
-        "$FILE"
-      ],
+      "command": ["npx", "oxfmt", "--write", "$FILE"],
       "extensions": [
         ".js",
         ".jsx",
@@ -114,22 +83,11 @@
       ]
     },
     "laravel-pint": {
-      "command": [
-        "npx",
-        "laravel-pint",
-        "--preset",
-        "psr12",
-        "$FILE"
-      ],
-      "extensions": [
-        ".php"
-      ]
+      "command": ["npx", "laravel-pint", "--preset", "psr12", "$FILE"],
+      "extensions": [".php"]
     }
   },
-  "instructions": [
-    ".opencode/memory/user.md",
-    ".opencode/memory/project/*.md"
-  ],
+  "instructions": [".opencode/memory/user.md", ".opencode/memory/project/*.md"],
   "keybinds": {
     "command_list": ";",
     "leader": "`",
@@ -138,17 +96,6 @@
     "session_compact": "ctrl+k"
   },
   "mcp": {
-    "context7": {
-      "type": "remote",
-      "url": "https://mcp.context7.com/mcp",
-      "headers": {
-        "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"
-      }
-    },
-    "gh_grep": {
-      "type": "remote",
-      "url": "https://mcp.grep.app"
-    },
     "stitch": {
       "enabled": false,
       "type": "remote",
@@ -195,6 +142,11 @@
     "@tarquinen/opencode-dcp@latest",
     "@franlol/opencode-md-table-formatter@0.0.3"
   ],
+  "tools": {
+    "grep-search": true,
+    "context7-resolve-library-id": true,
+    "context7-query-docs": true
+  },
   "provider": {
     "github-copilot": {
       "models": {
@@ -338,17 +290,13 @@
               "disabled": true
             },
             "high": {
-              "include": [
-                "reasoning.encrypted_content"
-              ],
+              "include": ["reasoning.encrypted_content"],
               "reasoningEffort": "high",
               "reasoningSummary": "auto",
               "textVerbosity": "low"
             },
             "medium": {
-              "include": [
-                "reasoning.encrypted_content"
-              ],
+              "include": ["reasoning.encrypted_content"],
               "reasoningEffort": "medium",
               "reasoningSummary": "auto",
               "textVerbosity": "low"
@@ -361,17 +309,13 @@
               "disabled": true
             },
             "high": {
-              "include": [
-                "reasoning.encrypted_content"
-              ],
+              "include": ["reasoning.encrypted_content"],
               "reasoningEffort": "high",
               "reasoningSummary": "auto",
               "textVerbosity": "low"
             },
             "medium": {
-              "include": [
-                "reasoning.encrypted_content"
-              ],
+              "include": ["reasoning.encrypted_content"],
               "reasoningEffort": "medium",
               "reasoningSummary": "auto",
               "textVerbosity": "low"
@@ -402,14 +346,8 @@
           },
           "name": "Gemini 2 5 Computer Use Preview 10 2025",
           "modalities": {
-            "input": [
-              "text",
-              "image",
-              "pdf"
-            ],
-            "output": [
-              "text"
-            ]
+            "input": ["text", "image", "pdf"],
+            "output": ["text"]
           }
         },
         "gemini-2.5-flash": {
@@ -419,14 +357,8 @@
           },
           "name": "Gemini 2 5 Flash",
           "modalities": {
-            "input": [
-              "text",
-              "image",
-              "pdf"
-            ],
-            "output": [
-              "text"
-            ]
+            "input": ["text", "image", "pdf"],
+            "output": ["text"]
           }
         },
         "gemini-2.5-flash-lite": {
@@ -436,14 +368,8 @@
           },
           "name": "Gemini 2 5 Flash Lite",
           "modalities": {
-            "input": [
-              "text",
-              "image",
-              "pdf"
-            ],
-            "output": [
-              "text"
-            ]
+            "input": ["text", "image", "pdf"],
+            "output": ["text"]
           }
         },
         "gemini-2.5-pro": {
@@ -453,14 +379,8 @@
           },
           "name": "Gemini 2 5 Pro",
           "modalities": {
-            "input": [
-              "text",
-              "image",
-              "pdf"
-            ],
-            "output": [
-              "text"
-            ]
+            "input": ["text", "image", "pdf"],
+            "output": ["text"]
           }
         },
         "gemini-3-flash-preview": {
@@ -470,14 +390,8 @@
           },
           "name": "Gemini 3 Flash Preview",
           "modalities": {
-            "input": [
-              "text",
-              "image",
-              "pdf"
-            ],
-            "output": [
-              "text"
-            ]
+            "input": ["text", "image", "pdf"],
+            "output": ["text"]
           },
           "variants": {
             "low": {
@@ -499,14 +413,8 @@
           },
           "name": "Gemini 3 Pro Image Preview",
           "modalities": {
-            "input": [
-              "text",
-              "image",
-              "pdf"
-            ],
-            "output": [
-              "text"
-            ]
+            "input": ["text", "image", "pdf"],
+            "output": ["text"]
           }
         },
         "gemini-3-pro-preview": {
@@ -516,14 +424,8 @@
           },
           "name": "Gemini 3 Pro Preview",
           "modalities": {
-            "input": [
-              "text",
-              "image",
-              "pdf"
-            ],
-            "output": [
-              "text"
-            ]
+            "input": ["text", "image", "pdf"],
+            "output": ["text"]
           },
           "variants": {
             "low": {
@@ -541,14 +443,8 @@
             "output": 64000
           },
           "modalities": {
-            "input": [
-              "text",
-              "image",
-              "pdf"
-            ],
-            "output": [
-              "text"
-            ]
+            "input": ["text", "image", "pdf"],
+            "output": ["text"]
           },
           "name": "Gemini Claude Opus 4 5 Thinking",
           "variants": {
@@ -571,14 +467,8 @@
             "output": 64000
           },
           "modalities": {
-            "input": [
-              "text",
-              "image",
-              "pdf"
-            ],
-            "output": [
-              "text"
-            ]
+            "input": ["text", "image", "pdf"],
+            "output": ["text"]
           },
           "name": "Gemini Claude Sonnet 4 5"
         },
@@ -588,14 +478,8 @@
             "output": 64000
           },
           "modalities": {
-            "input": [
-              "text",
-              "image",
-              "pdf"
-            ],
-            "output": [
-              "text"
-            ]
+            "input": ["text", "image", "pdf"],
+            "output": ["text"]
           },
           "name": "Gemini Claude Sonnet 4 5 Thinking",
           "variants": {

package/dist/template/.opencode/plans/1768385996691-silent-wizard.md

@@ -38,7 +38,16 @@ If memory returns high-confidence findings on this exact topic, synthesize and r
 | Priority | Tool | Use Case | Speed |
 |----------|------|----------|-------|
 | 1 | memory-search | Past research findings | Instant |
-| 2 | context7 | Official library docs | Fast |
+| Priority | Tool | Use Case | Speed |
+|----------|------|----------|-------|
+| 1 | memory-search | Past research findings | Instant |
+| 2 | context7_resolve-library-id | Resolve library names to IDs | Fast |
+| 3 | context7_query-docs | Official library docs | Fast |
+| 4 | codesearch | Exa Code API for SDK/library patterns | Fast |
+| 5 | grep-search | Cross-repo GitHub code search | Medium |
+| 6 | webfetch | Specific doc URLs, READMEs, changelogs | Medium |
+| 7 | opensrc + LSP | Clone & analyze source code | Slow |
+| 8 | websearch | Tutorials, blog posts, recent news | Slow |
 | 3 | codesearch | Usage patterns in real code | Fast |
 | 4 | gh_grep | Cross-repo deep code search | Medium |
 | 5 | webfetch | Specific doc URLs, READMEs, changelogs | Medium |
@@ -76,7 +85,8 @@ webfetch({ url: "https://docs.example.com/api/authentication", format: "markdown
 **When to use:**
 
 - User provides a specific URL
-- context7 returns a doc link worth fetching
+- context7_resolve-library-id returns a library ID
+- context7_query-docs returns a doc link worth fetching
 - Need CHANGELOG or release notes
 - GitHub README has details not in context7
 

package/dist/template/.opencode/skill/source-code-research/SKILL.md

@@ -362,20 +362,20 @@ If opensrc doesn't work:
 
 Source code research complements other tools:
 
-| Method         | Best For                   | Source Code Adds               |
-| -------------- | -------------------------- | ------------------------------ |
-| **Context7**   | API docs, official guides  | Implementation details         |
-| **codesearch** | Usage patterns in the wild | Canonical implementation       |
-| **gh_grep**    | Real-world examples        | How library itself works       |
-| **Web search** | Tutorials, blog posts      | Ground truth from source       |
-| **Codebase**   | Project-specific patterns  | How dependencies actually work |
+| Method          | Best For                   | Source Code Adds               |
+| --------------- | -------------------------- | ------------------------------ |
+| **Context7**    | API docs, official guides  | Implementation details         |
+| **codesearch**  | Usage patterns in the wild | Canonical implementation       |
+| **grep_search** | Real-world examples        | How library itself works       |
+| **Web search**  | Tutorials, blog posts      | Ground truth from source       |
+| **Codebase**    | Project-specific patterns  | How dependencies actually work |
 
 **Recommended flow:**
 
 1. Context7 - Check official docs
 2. Codebase - Check existing usage
 3. **Source code** - If still unclear, fetch source
-4. codesearch/gh_grep - See how others use it
+4. codesearch/grep_search - See how others use it
 5. Web search - Last resort for context
 
 ## Cleanup

package/dist/template/.opencode/skill/tool-priority/SKILL.md

@@ -180,9 +180,11 @@ glob ["src/**/*.ts", "tests/**/*.ts"]
 
 ## Research Tools
 
-| Tool           | Use When                                                |
-| -------------- | ------------------------------------------------------- |
-| **context7**   | Library docs (try first). Fast, external APIs.          |
-| **websearch**  | Docs not in Context7, recent releases, troubleshooting. |
-| **codesearch** | Real implementation patterns from GitHub.               |
-| **webfetch**   | Specific URL user provided.                             |
+| Tool                            | Use When                                                |
+| ------------------------------- | ------------------------------------------------------- |
+| **context7_resolve-library-id** | Resolve library names to IDs (try first).               |
+| **context7_query-docs**         | Query official library documentation. Fast.             |
+| **websearch**                   | Docs not in Context7, recent releases, troubleshooting. |
+| **codesearch**                  | Real implementation patterns from GitHub.               |
+| **grep-search**                 | Cross-repo code patterns via grep.app.                  |
+| **webfetch**                    | Specific URL user provided.                             |

package/dist/template/.opencode/tool/context7-query-docs.ts

@@ -0,0 +1,89 @@
+import { tool } from "@opencode-ai/plugin";
+
+// Context7 API v2 - https://context7.com/docs/api-guide
+const CONTEXT7_API = "https://context7.com/api/v2";
+
+export default tool({
+	description: `Query library documentation from Context7 using a library ID.
+
+Use when:
+- You have a library ID (from context7_resolve_library_id)
+- Need specific documentation about a library feature
+- Looking for API reference, examples, or setup instructions
+
+Always resolve library name to ID first with context7_resolve_library_id!
+
+Examples:
+  context7_query_docs({ libraryId: "/reactjs/react.dev", topic: "hooks" })
+  context7_query_docs({ libraryId: "/vercel/next.js", topic: "middleware" })
+  context7_query_docs({ libraryId: "/microsoft/TypeScript", topic: "generics" })
+`,
+	args: {
+		libraryId: tool.schema
+			.string()
+			.describe(
+				"Library ID from context7_resolve_library_id (e.g., '/reactjs/react.dev')",
+			),
+		topic: tool.schema
+			.string()
+			.describe("Documentation topic or feature to search for"),
+	},
+	execute: async (args) => {
+		const { libraryId, topic } = args;
+
+		if (!libraryId || libraryId.trim() === "") {
+			return "Error: libraryId is required (use context7-resolve-library-id first)";
+		}
+
+		if (!topic || topic.trim() === "") {
+			return "Error: topic is required (e.g., 'hooks', 'setup', 'API reference')";
+		}
+
+		try {
+			// Query Context7 documentation - GET /api/v2/context
+			// Returns text format by default which is better for LLM consumption
+			const url = new URL(`${CONTEXT7_API}/context`);
+			url.searchParams.set("libraryId", libraryId);
+			url.searchParams.set("query", topic);
+
+			// Add API key if available (recommended for higher rate limits)
+			const apiKey = process.env.CONTEXT7_API_KEY;
+			const headers: HeadersInit = {
+				Accept: "text/plain",
+				"User-Agent": "OpenCode/1.0",
+			};
+
+			if (apiKey) {
+				headers.Authorization = `Bearer ${apiKey}`;
+			}
+
+			const response = await fetch(url.toString(), { headers });
+
+			if (!response.ok) {
+				if (response.status === 401) {
+					return `Error: Invalid CONTEXT7_API_KEY. Get a free key at https://context7.com/dashboard`;
+				}
+				if (response.status === 404) {
+					return `Error: Library not found: ${libraryId}\n\nUse context7-resolve-library-id first to find the correct ID.`;
+				}
+				if (response.status === 429) {
+					return `Error: Rate limit exceeded. Get a free API key at https://context7.com/dashboard for higher limits.`;
+				}
+				return `Error: Context7 API returned ${response.status}`;
+			}
+
+			const content = await response.text();
+
+			if (!content || content.trim() === "") {
+				return `No documentation found for "${topic}" in ${libraryId}.\n\nTry:\n- Simpler terms (e.g., "useState" instead of "state management")\n- Different topic spelling\n- Broader topics like "API reference" or "getting started"`;
+			}
+
+			return `# Documentation: ${topic} (${libraryId})
+
+${content}`;
+		} catch (error: unknown) {
+			const message = error instanceof Error ? error.message : String(error);
+			return `Error querying documentation: ${message}`;
+		}
+	},
+});

package/dist/template/.opencode/tool/context7-resolve-library-id.ts

@@ -0,0 +1,113 @@
+import { tool } from "@opencode-ai/plugin";
+
+// Context7 API v2 - https://context7.com/docs/api-guide
+const CONTEXT7_API = "https://context7.com/api/v2";
+
+interface LibraryInfo {
+	id: string;
+	title: string;
+	description?: string;
+	totalSnippets?: number;
+	trustScore?: number;
+	benchmarkScore?: number;
+	versions?: string[];
+}
+
+interface SearchResponse {
+	results: LibraryInfo[];
+}
+
+export default tool({
+	description: `Resolve a library name to its Context7 ID for documentation lookup.
+
+Use when:
+- You need to find the exact library ID format for a package
+- Starting a documentation search (get the ID first, then query docs)
+- Normalizing library names (e.g., "react" → "/reactjs/react.dev")
+
+Examples:
+  context7_resolve_library_id({ libraryName: "react" })
+  context7_resolve_library_id({ libraryName: "vue", query: "composition API" })
+  context7_resolve_library_id({ libraryName: "nextjs" })
+`,
+	args: {
+		libraryName: tool.schema
+			.string()
+			.describe(
+				"Library name to resolve (e.g., 'react', 'lodash', 'typescript')",
+			),
+		query: tool.schema
+			.string()
+			.optional()
+			.describe("Optional context for the search (improves relevance ranking)"),
+	},
+	execute: async (args) => {
+		const { libraryName, query = "documentation" } = args;
+
+		if (!libraryName || libraryName.trim() === "") {
+			return "Error: libraryName is required";
+		}
+
+		try {
+			// Query Context7 library search - GET /api/v2/libs/search
+			const url = new URL(`${CONTEXT7_API}/libs/search`);
+			url.searchParams.set("libraryName", libraryName);
+			url.searchParams.set("query", query);
+
+			// Add API key if available (recommended for higher rate limits)
+			const apiKey = process.env.CONTEXT7_API_KEY;
+			const headers: HeadersInit = {
+				Accept: "application/json",
+				"User-Agent": "OpenCode/1.0",
+			};
+
+			if (apiKey) {
+				headers.Authorization = `Bearer ${apiKey}`;
+			}
+
+			const response = await fetch(url.toString(), { headers });
+
+			if (!response.ok) {
+				if (response.status === 401) {
+					return `Error: Invalid CONTEXT7_API_KEY. Get a free key at https://context7.com/dashboard`;
+				}
+				if (response.status === 429) {
+					return `Error: Rate limit exceeded. Get a free API key at https://context7.com/dashboard for higher limits.`;
+				}
+				return `Error: Context7 API returned ${response.status}`;
+			}
+
+			const data = (await response.json()) as SearchResponse;
+			const libraries = data.results || [];
+
+			if (!libraries || libraries.length === 0) {
+				return `No libraries found matching: ${libraryName}\n\nTry:\n- Different library name\n- Check spelling\n- Use official package name`;
+			}
+
+			const formatted = libraries
+				.slice(0, 5)
+				.map((lib, i) => {
+					const desc = lib.description
+						? `\n   ${lib.description.slice(0, 100)}...`
+						: "";
+					const snippets = lib.totalSnippets
+						? ` (${lib.totalSnippets} snippets)`
+						: "";
+					const score = lib.benchmarkScore
+						? ` [score: ${lib.benchmarkScore}]`
+						: "";
+					return `${i + 1}. **${lib.title}** → \`${lib.id}\`${snippets}${score}${desc}`;
+				})
+				.join("\n\n");
+
+			return `Found ${libraries.length} libraries matching "${libraryName}":
+
+${formatted}
+
+**Next step**: Use \`context7-query-docs({ libraryId: "${libraries[0].id}", topic: "your topic" })\` to fetch documentation.`;
+		} catch (error: unknown) {
+			const message = error instanceof Error ? error.message : String(error);
+			return `Error resolving library: ${message}`;
+		}
+	},
+});

package/dist/template/.opencode/tool/grep-search.ts

@@ -0,0 +1,135 @@
+import { tool } from "@opencode-ai/plugin";
+
+const GREP_APP_API = "https://grep.app/api/search";
+
+interface SearchResult {
+	repo: string;
+	path: string;
+	content: { snippet: string };
+	total_matches: string;
+}
+
+interface GrepResponse {
+	hits: { hits: SearchResult[] };
+	time: number;
+}
+
+export default tool({
+	description: `Search real-world code examples from GitHub repositories via grep.app.
+
+Use when:
+- Implementing unfamiliar APIs - see how others use a library
+- Looking for production patterns - find real-world examples
+- Understanding library integrations - see how things work together
+
+IMPORTANT: Search for **literal code patterns**, not keywords:
+✅ Good: "useState(", "import React from", "async function"
+❌ Bad: "react tutorial", "best practices", "how to use"
+
+Examples:
+  grep_search({ query: "getServerSession", language: "TypeScript" })
+  grep_search({ query: "CORS(", language: "Python", repo: "flask" })
+  grep_search({ query: "export async function POST", path: "route.ts" })
+`,
+	args: {
+		query: tool.schema
+			.string()
+			.describe("Code pattern to search for (literal text)"),
+		language: tool.schema
+			.string()
+			.optional()
+			.describe("Filter by language: TypeScript, TSX, Python, Go, Rust, etc."),
+		repo: tool.schema
+			.string()
+			.optional()
+			.describe("Filter by repo: 'owner/repo' or partial match"),
+		path: tool.schema
+			.string()
+			.optional()
+			.describe("Filter by file path: 'src/', '.test.ts', etc."),
+		limit: tool.schema
+			.number()
+			.optional()
+			.describe("Max results to return (default: 10, max: 20)"),
+	},
+	execute: async (args) => {
+		const { query, language, repo, path, limit = 10 } = args;
+
+		if (!query || query.trim() === "") {
+			return "Error: query is required";
+		}
+
+		// Build URL with proper filter parameters
+		// grep.app uses filter[lang][0]=TypeScript format, NOT inline lang:TypeScript
+		const url = new URL(GREP_APP_API);
+		url.searchParams.set("q", query);
+
+		// Add language filter (grep.app uses filter[lang][0] format)
+		if (language) {
+			url.searchParams.set("filter[lang][0]", language);
+		}
+
+		// Add repo filter
+		if (repo) {
+			url.searchParams.set("filter[repo][0]", repo);
+		}
+
+		// Add path filter
+		if (path) {
+			url.searchParams.set("filter[path][0]", path);
+		}
+
+		try {
+			const response = await fetch(url.toString(), {
+				headers: {
+					Accept: "application/json",
+					"User-Agent": "OpenCode/1.0",
+				},
+			});
+
+			if (!response.ok) {
+				return `Error: grep.app API returned ${response.status}`;
+			}
+
+			const data = (await response.json()) as GrepResponse;
+
+			if (!data.hits?.hits?.length) {
+				return `No results found for: ${query}${language ? ` (${language})` : ""}`;
+			}
+
+			const maxResults = Math.min(limit, 20);
+			const results = data.hits.hits.slice(0, maxResults);
+
+			const formatted = results.map((hit, i) => {
+				const repoName = hit.repo || "unknown";
+				const filePath = hit.path || "unknown";
+				const snippet = hit.content?.snippet || "";
+
+				// Clean up HTML from snippet and extract text
+				const cleanCode = snippet
+					.replace(/<[^>]*>/g, "") // Remove HTML tags
+					.replace(/&lt;/g, "<")
+					.replace(/&gt;/g, ">")
+					.replace(/&amp;/g, "&")
+					.replace(/&quot;/g, '"')
+					.split("\n")
+					.slice(0, 8)
+					.join("\n")
+					.trim();
+
+				return `## ${i + 1}. ${repoName}
+**File**: ${filePath}
+\`\`\`
+${cleanCode}
+\`\`\``;
+			});
+
+			return `Found ${data.hits.hits.length} results (showing ${results.length}) in ${data.time}ms:
+
+${formatted.join("\n\n")}`;
+		} catch (error: unknown) {
+			const message = error instanceof Error ? error.message : String(error);
+			return `Error searching grep.app: ${message}`;
+		}
+	},
+});

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencodekit",
-	"version": "0.15.12",
+	"version": "0.15.13",
 	"description": "CLI tool for bootstrapping and managing OpenCodeKit projects",
 	"keywords": ["agents", "cli", "mcp", "opencode", "opencodekit", "template"],
 	"license": "MIT",