feat: Full OpenCode feature parity with Claude Code — pre-tool hook, session-start context, and skill installation

[ZeR020]

Summary

codebase-memory-mcp install configures OpenCode with only bare MCP server registration and a static AGENTS.md file. Claude Code receives three additional integration layers — a PreToolUse hook that auto-injects graph context during Grep/Glob, a SessionStart reminder hook, and a consolidated skill (codebase-memory) — that make the tool proactive rather than passive. OpenCode has equivalent hook primitives (tool.execute.before, experimental.chat.system.transform, plugin system) but the installer does not wire them up.

This issue requests full feature parity for OpenCode so that codebase-memory-mcp install delivers the same proactive integration depth as Claude Code.

Current State

What Claude Code gets

Integration	Mechanism	Location
MCP server	.claude/.mcp.json	—
Consolidated skill	~/.claude/skills/codebase-memory/SKILL.md	cbm_install_skills() — quick decision matrix, exploration/tracing workflows, quality analysis, 14 tool reference, Cypher examples, edge types, gotchas
PreToolUse hook	settings.json → hooks.PreToolUse with matcher `Grep	Glob`
SessionStart hook	~/.claude/hooks/cbm-session-reminder	Injects one-line reminder to prioritize search_graph, trace_path, get_code_snippet, query_graph, get_architecture, search_code over raw grep

What OpenCode gets today

Integration	Mechanism	Location
MCP server	opencode.json	cbm_upsert_opencode_mcp()
Static instructions	~/.config/opencode/AGENTS.md	Static file, no dynamic behavior
PreToolUse hook	Missing	—
SessionStart hook	Missing	—
Skill	Missing	—

The OpenCode install path (cli.c:3094) calls only install_generic_agent_config() with cbm_upsert_opencode_mcp. Compare this to the Claude Code path which additionally calls cbm_install_skills(), cbm_upsert_claude_hooks(), and installs the cbm-session-reminder and cbm-code-discovery-gate shim scripts.

Requested Features

1. Pre-tool hook: tool.execute.before (equivalent to Claude Code PreToolUse)

OpenCode supports a tool.execute.before hook via its plugin system. This should be wired to intercept grep and glob tool calls (never read — same invariant as Claude Code) and inject structured graph context from search_graph as additional context, identical to what the cbm-code-discovery-gate shim does for Claude Code.

Implementation approach:

• Create a small plugin file (e.g. ~/.config/opencode/plugins/cbm-augment.ts or .js) that exports a tool.execute.before hook
• The hook inspects the incoming tool name; if it matches grep or glob, extract the search token, call the codebase-memory-mcp binary in CLI mode (codebase-memory-mcp cli search_graph '{"name_pattern": "..."}'), and inject results as additional context
• Must be non-blocking: all failure paths (binary missing, no indexed project, query timeout) must return silently without preventing the original tool call
• Register the plugin in opencode.json under the "plugin" key

Reference: Claude Code equivalent is cbm_upsert_claude_hooks() in cli.c which registers the cbm-code-discovery-gate shim under hooks.PreToolUse with matcher "Grep|Glob".

2. Session-start context injection (equivalent to SessionStart hook)

OpenCode supports experimental.chat.system.transform which can modify the system prompt sent to the LLM. This should inject the same codebase-memory reminder that cbm-session-reminder provides for Claude Code — instructing the agent to ALWAYS use codebase-memory-mcp tools first for code exploration, listing the specific tools (search_graph, trace_path, get_code_snippet, query_graph, get_architecture, search_code), and advising grep/glob/read for text/configs/non-code files.

Implementation approach:

• Either via the same plugin file (adding an experimental.chat.system.transform hook) or via a separate mechanism
• The injected text should be the same content as cbm-session-reminder (the session reminder script content defined in cli.c)
• Alternatively, this could be folded into the AGENTS.md file dynamically, but the system transform hook is more reliable since it runs on every session regardless of whether the agent reads AGENTS.md

Reference: Claude Code equivalent is cbm-session-reminder script installed to ~/.claude/hooks/ and registered under hooks.SessionStart in settings.json. Codex, Gemini CLI, and Antigravity all get a similar SessionStart reminder — OpenCode is the only hook-capable agent that does not.

3. Skill installation (equivalent to Claude Code codebase-memory skill)

Install the consolidated codebase-memory skill to OpenCode's skills/instructions directory. The skill content is already defined in the skill_content static variable in cli.c and includes:

• Quick Decision Matrix (question to tool mapping)
• Exploration Workflow (list_projects, get_graph_schema, search_graph, get_code_snippet)
• Tracing Workflow (search_graph, trace_path, detect_changes)
• Quality Analysis (dead code, fan-out, fan-in)
• 14 MCP Tools reference
• Edge Types reference
• Cypher query examples
• Gotchas and tips

Implementation approach:

• Install the skill to the appropriate OpenCode location (e.g. ~/.config/opencode/skills/codebase-memory/ or wherever OpenCode discovers instruction files)
• The skill content (SKILL.md with YAML frontmatter) can be reused as-is from the Claude Code skill — the tool names and workflows are agent-agnostic
• Add a call to cbm_install_skills() (or equivalent) in the OpenCode branch of install_cli_agent_configs()

Reference: Claude Code equivalent is cbm_install_skills() which writes SKILL.md to ~/.claude/skills/codebase-memory/. The old 4-skill layout (codebase-memory-exploring, codebase-memory-tracing, codebase-memory-quality, codebase-memory-reference) was consolidated into a single skill (CBM_SKILL_COUNT = 1).

Proposed Multi-Agent Support Table Update

The README table currently shows:

Agent	MCP Config	Instructions	Hooks
Claude Code	.claude/.mcp.json	4 Skills	PreToolUse (Grep/Glob graph augment, non-blocking)
OpenCode	opencode.json	AGENTS.md	—

After this change:

Agent	MCP Config	Instructions	Hooks
Claude Code	.claude/.mcp.json	1 Skill (codebase-memory)	PreToolUse (Grep/Glob graph augment, non-blocking)
OpenCode	opencode.json	1 Skill (codebase-memory) + AGENTS.md	tool.execute.before (grep/glob graph augment, non-blocking) + experimental.chat.system.transform (session reminder)

Technical Notes

• OpenCode's plugin system loads TypeScript/JavaScript files specified in opencode.json under the "plugin" key. A plugin exports a function receiving a context object and returns an object with hook implementations.
• The tool.execute.before hook receives (input, output) where output.args can be mutated before the tool runs. For graph augmentation, the hook should add context to the tool input or system context, not block the tool.
• The experimental.chat.system.transform hook allows modifying the system prompt — this is the correct place to inject the session-start reminder.
• All hooks must be structurally non-blocking (same design principle as Claude Code's cbm-code-discovery-gate which always exits 0).
• The hook-augment subcommand of the codebase-memory-mcp binary already exists and is agent-agnostic — it takes a search token and returns graph context. The OpenCode plugin can call this directly via BunShell ($) or child_process.

Uninstall

codebase-memory-mcp uninstall should also remove:

• The plugin file from ~/.config/opencode/plugins/
• The plugin entry from opencode.json "plugin" array
• The skill from the OpenCode skills directory

Environment

• OS: Linux (but should work cross-platform)
• OpenCode: latest, global config ~/.config/opencode/opencode.json
• codebase-memory-mcp: v0.8.x

Related

• OpenCode MCP registration: wrong config shape, stale paths, short timeout #437 — OpenCode MCP registration bugs (closed, config shape fixed)
• "install" command does not work for opencode in windows 11 #221 — Windows install broken for OpenCode (open)
• The README claims "11 agents, one command — configures MCP entries, instruction files, and pre-tool hooks for each" but OpenCode does not receive hooks or skills, making this claim inaccurate for OpenCode.

[DeusData]

Thanks for the precise gap analysis — OpenCode is indeed the only hook-capable agent getting bare MCP registration + a static AGENTS.md while Claude Code / Codex / Gemini CLI / Antigravity all get the proactive layers.

Wiring tool.execute.before (matching grep / glob only, never read, non-blocking on every failure path), the session-start system transform, and the consolidated skill via the installer is the right parity target. Labeling enhancement / editor/integration and tracking under the integration task #395.

This is a well-scoped contribution if you'd like to take it on.