OpenCode Plugin

The noodlbox plugin for OpenCode provides automatic semantic search augmentation and MCP tools for intelligent codebase exploration.

Installation

Automatic Setup (Recommended)

The easiest way to install the plugin is through the noodlbox CLI:

noodl configure opencode

This automatically:

• Copies the plugin to ~/.config/opencode/plugin/noodlbox/
• Copies skills to ~/.config/opencode/skill/
• Configures MCP server connection in ~/.config/opencode/opencode.json

Manual Setup

If you prefer manual installation:

1. Copy the plugin files:

mkdir -p ~/.config/opencode/plugin/noodlbox
cp -r platforms/opencode/plugin/* ~/.config/opencode/plugin/noodlbox/
cp -r shared/hooks ~/.config/opencode/plugin/noodlbox/shared/

2. Copy skills:

cp -r shared/skills/* ~/.config/opencode/skill/

3. Add MCP config to ~/.config/opencode/opencode.json:

{
  "mcp": {
    "noodlbox": {
      "type": "local",
      "command": ["noodl", "mcp"]
    }
  }
}

Plugin Architecture

The OpenCode plugin uses a multi-hook architecture for seamless integration:

How It Works

Automatic Context Injection

When you use search tools (Glob, Grep, Bash), the plugin automatically:

1. Intercepts the tool call in tool.execute.before
2. Extracts a semantic query from the pattern
3. Runs noodl search against your indexed codebase
4. Stores results in session-scoped storage (with 30s TTL for memory safety)
5. Injects context via chat.message hook into the next LLM message
6. Consumes (clears) the context after injection to prevent stale data

This happens transparently - you get semantic search results without changing your workflow.

Context Format

Search results are injected as XML context:

<noodlbox-context query="authentication">
  <!-- Execution flows, symbols, and call chains -->
</noodlbox-context>

The LLM sees this context alongside your original search results, providing architectural understanding.

MCP Tools

The plugin connects to the noodlbox MCP server, providing these tools:

Skills

Noodlbox provides the noodlbox-setup skill for initializing noodlbox context in a project:

Skills are installed to ~/.config/opencode/skill/ and discovered automatically by OpenCode.

Session Startup

On session start, the plugin logs all indexed repositories:

[noodlbox] Indexed repositories:
  owner/my-app (last analyzed: 2 hours ago)
  owner/other-repo (last analyzed: 1 day ago)

This helps you know which repositories have context available.

Example Usage

Automatic Enhancement

When you search with Grep:

Grep for "handleAuth"

The plugin automatically augments with semantic search, showing:

• Functions that implement authentication
• Related processes and call chains
• Entry points into the auth system

Explicit Tool Calls

For direct queries:

Use noodlbox_query_with_context to find the payment processing flow

Impact Analysis

Before committing:

Use noodlbox_detect_impact to check what my staged changes affect

Configuration

Environment Variables

Debug Mode

Enable debug logging to troubleshoot hook execution:

export NOODLBOX_HOOK_DEBUG=true

Workflow: First-Time Setup

For a new repository:

# 1. Analyze the codebase
noodl analyze /path/to/repo

# 2. Configure OpenCode
noodl configure opencode

# 3. Start coding - hooks work automatically

Workflow: Pre-Commit Review

Before committing changes, ask OpenCode:

Use noodlbox_detect_impact to analyze my staged changes

Review the impacted processes and plan testing accordingly.

Troubleshooting

Hooks Not Firing

1. Check plugin is installed: ls ~/.config/opencode/plugin/noodlbox/
2. Verify shared lib exists: ls ~/.config/opencode/plugin/noodlbox/shared/hooks/lib.js
3. Enable debug mode to see hook execution:

export NOODLBOX_HOOK_DEBUG=true

MCP Tools Not Available

1. Check MCP config: cat ~/.config/opencode/opencode.json
2. Verify noodl is in PATH: which noodl
3. Test MCP server: noodl mcp

No Search Results

1. Verify repository is indexed: noodl list
2. Re-analyze if needed: noodl analyze .

Related

• Getting Started - Installation and MCP setup
• Workflows - Step-by-step guides for common tasks