Heretek-AI/claude-4-opencode
1
0 Fork 0
mirror of https://github.com/Heretek-AI/claude-4-opencode.git synced 2026-11-07 02:36:06 -10:00
Code Issues Packages Projects Releases 1 Wiki Activity

docs: add README, research notes and the compatibility report

Browse Source 
Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
John SmithandClaude Opus 5.5 committed 2026-10-10 16:46:28 -04:00
1 parent 8b9f7b88fc
commit 2f5266518c
4 files changed
+533
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

COMPATIBILITY.md
+302
View File
@@ -0,0 +1,302 @@
# Compatibility
Generated from an end-to-end run against the real opencode binary. Do not edit by hand: run `bun run e2e` and then `bun run e2e:report`.
- opencode: `opencode v2.0.26`
- claude-4-opencode: `0.0.1`
## Marketplaces
Every entry of each marketplace resolves, every in-repo plugin loads without errors, and opencode lists every skill, command and agent found. Marketplaces are pinned to the commits in `e2e/targets.lock.json`.
| Marketplace | Commit | Entries | In-repo plugins | Skills | Commands | Agents | MCP servers | Plugins with hooks | LSP servers |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| [anthropic-agent-skills](https://github.com/anthropics/skills) | `dbd4588` | 5 | 5 | 19 | 0 | 0 | 0 | 0 | 0 |
| [claude-plugins-official](https://github.com/anthropics/claude-plugins-official) | `b8e53f1` | 315 | 53 | 31 | 32 | 36 | 13 | 7 | 12 |
| [compound-engineering-plugin](https://github.com/EveryInc/compound-engineering-plugin) | `51aa537` | 1 | 1 | 36 | 0 | 0 | 0 | 0 | 0 |
| [knowledge-work-plugins](https://github.com/anthropics/knowledge-work-plugins) | `95bdacc` | 123 | 22 | 225 | 15 | 5 | 156 | 0 | 0 |
| [superpowers-marketplace](https://github.com/obra/superpowers-marketplace) | `2cf27fa` | 10 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| [claude-code-workflows](https://github.com/wshobson/agents) | `46891e7` | 94 | 92 | 184 | 105 | 202 | 0 | 2 | 0 |
## Hook events
How each Claude Code hook event is carried over. Events not listed have no opencode equivalent and are reported by `c4o inspect`.
| Event | Supported | How |
| --- | --- | --- |
| `PreToolUse` | yes | runs before the tool; can block the call, rewrite its input and add context. A request to ask the user blocks instead |
| `PostToolUse` | yes | runs after a successful tool call; feedback is appended to the tool result |
| `PostToolUseFailure` | partial | runs after a failed tool call; its feedback is not delivered to the model |
| `UserPromptSubmit` | partial | runs when a prompt is submitted; context is appended to the prompt, and a blocked prompt is rejected with a generic error |
| `SessionStart` | partial | runs before a session's first model request; context is added to the system prompt. Reports startup or resume, never clear or compact |
| `Stop` | partial | runs when the session finishes a turn; a block continues the session with the reason as the next prompt |
| `SubagentStop` | partial | runs when a subagent session finishes; it cannot be made to continue |
| `SessionEnd` | partial | runs when a session is deleted, not when the client exits |
Events used by plugins in these marketplaces that are not carried over:
| Event | Plugins using it |
| --- | --- |
| `UserPromptExpansion` | 1 |
| `PermissionRequest` | 1 |
| `StopFailure` | 1 |
## Scenarios
32 passed, 0 failed, 10 skipped.
| Suite | Scenario | Result |
| --- | --- | --- |
| claude-plugins-official | every entry resolves and every in-repo plugin loads cleanly, and opencode lists all of it | pass |
| claude-plugins-official | every external plugin fetches and loads cleanly | skipped |
| anthropic-agent-skills | every entry resolves and every in-repo plugin loads cleanly, and opencode lists all of it | pass |
| anthropic-agent-skills | every external plugin fetches and loads cleanly | skipped |
| knowledge-work-plugins | every entry resolves and every in-repo plugin loads cleanly, and opencode lists all of it | pass |
| knowledge-work-plugins | every external plugin fetches and loads cleanly | skipped |
| superpowers-marketplace | every entry resolves and every in-repo plugin loads cleanly, and opencode lists all of it | pass |
| superpowers-marketplace | every external plugin fetches and loads cleanly | skipped |
| wshobson-agents | every entry resolves and every in-repo plugin loads cleanly, and opencode lists all of it | pass |
| wshobson-agents | every external plugin fetches and loads cleanly | skipped |
| compound-engineering | every entry resolves and every in-repo plugin loads cleanly, and opencode lists all of it | pass |
| compound-engineering | every external plugin fetches and loads cleanly | skipped |
| | a marketplace added from GitHub installs and loads: anthropics/skills | pass |
| anthropic-agent-skills matches Claude Code | every plugin exposes the same skills, agents and slash commands | pass |
| compound-engineering matches Claude Code | every plugin exposes the same skills, agents and slash commands | pass |
| claude-plugins-official matches Claude Code | every plugin exposes the same skills, agents and slash commands | pass |
| knowledge-work-plugins matches Claude Code | every plugin exposes the same skills, agents and slash commands | pass |
| wshobson-agents matches Claude Code | every plugin exposes the same skills, agents and slash commands | pass |
| superpowers-marketplace matches Claude Code | every plugin exposes the same skills, agents and slash commands | pass |
| | frontend-design: the model can discover and load the plugin's skill | pass |
| | installed plugins show up in opencode's inventory under their Claude Code names | pass |
| probe plugin | every component is registered under the plugin's namespace | pass |
| probe plugin | hooks: session context, prompt context, blocking, input rewriting, post-tool feedback | pass |
| probe plugin | hooks: a blocked prompt never reaches the model | pass |
| probe plugin | commands: arguments, plugin paths and shell interpolation with bin/ on PATH | pass |
| probe plugin | skills: plugin path variables are substituted in the body | pass |
| probe plugin | mcp: a stdio server starts from the plugin directory and its tool is callable | pass |
| probe plugin | agents: the system prompt is the agent body and its tool allowlist is enforced | pass |
| probe plugin | bin/: the plugin's executables are on PATH for the model's shell calls | pass |
| official plugins | explanatory-output-style: its SessionStart hook shapes every request | pass |
| official plugins | commit-commands: /commit-commands:commit gathers live git context | pass |
| official plugins | feature-dev: the command takes arguments and its agents run with their own prompt and tools | pass |
| official plugins | hookify: a user rule blocks a matching shell command and leaves others alone | pass |
| official plugins | ralph-loop: the Stop hook feeds the prompt back until the completion promise appears | pass |
| superpowers | its SessionStart hook injects the using-superpowers introduction | pass |
| superpowers | the model can load any of its skills by their Claude Code names | pass |
| superpowers | a skill can be run as a slash command with arguments | pass |
| | setup, add a marketplace, then install, disable and uninstall while opencode keeps running | pass |
| live model | a real model loads an official plugin's skill when the task calls for it | skipped |
| live model | a plugin's PreToolUse hook stops a real model's tool call | skipped |
| live model | a plugin's SessionStart context reaches a real model | skipped |
| live model | a real model calls a plugin's MCP tool | skipped |
## Plugins
<details><summary>anthropic-agent-skills: 5 plugins</summary>
| Plugin | Skills | Commands | Agents | MCP | Hooks | Not translated |
| --- | --- | --- | --- | --- | --- | --- |
| document-skills | 4 | 0 | 0 | 0 | - | - |
| example-skills | 12 | 0 | 0 | 0 | - | - |
| claude-api | 1 | 0 | 0 | 0 | - | - |
| academy-guide | 1 | 0 | 0 | 0 | - | - |
| discernment-nudge | 1 | 0 | 0 | 0 | - | - |
</details>
<details><summary>claude-plugins-official: 53 plugins</summary>
| Plugin | Skills | Commands | Agents | MCP | Hooks | Not translated |
| --- | --- | --- | --- | --- | --- | --- |
| agent-sdk-dev | 0 | 1 | 2 | 0 | - | - |
| asana | 0 | 1 | 0 | 0 | - | - |
| clangd-lsp | 0 | 0 | 0 | 0 | - | lsp |
| claude-code-setup | 1 | 0 | 0 | 0 | - | - |
| claude-md-management | 1 | 1 | 0 | 0 | - | - |
| claude-security | 1 | 0 | 9 | 0 | UserPromptExpansion (no), PostToolUse (yes), PostToolUseFailure (partial), PermissionRequest (no) | workflows |
| code-modernization | 0 | 13 | 8 | 0 | UserPromptSubmit (partial), Stop (partial), SessionStart (partial), PostToolUseFailure (partial), StopFailure (no) | workflows |
| code-review | 0 | 1 | 0 | 0 | - | - |
| code-simplifier | 0 | 0 | 1 | 0 | - | - |
| commit-commands | 0 | 3 | 0 | 0 | - | - |
| context7 | 0 | 0 | 0 | 1 | - | - |
| csharp-lsp | 0 | 0 | 0 | 0 | - | lsp |
| cwc-makers | 2 | 1 | 0 | 0 | - | - |
| discord | 2 | 0 | 0 | 1 | - | - |
| explanatory-output-style | 0 | 0 | 0 | 0 | SessionStart (partial) | - |
| fakechat | 0 | 0 | 0 | 1 | - | - |
| feature-dev | 0 | 1 | 3 | 0 | - | - |
| firebase | 0 | 0 | 0 | 1 | - | - |
| frontend-design | 1 | 0 | 0 | 0 | - | - |
| github | 0 | 0 | 0 | 1 | - | - |
| gitlab | 0 | 0 | 0 | 1 | - | - |
| gopls-lsp | 0 | 0 | 0 | 0 | - | lsp |
| hookify | 1 | 4 | 1 | 0 | PreToolUse (yes), PostToolUse (yes), Stop (partial), UserPromptSubmit (partial) | - |
| imessage | 2 | 0 | 0 | 1 | - | - |
| jdtls-lsp | 0 | 0 | 0 | 0 | - | lsp |
| kotlin-lsp | 0 | 0 | 0 | 0 | - | lsp |
| laravel-boost | 0 | 0 | 0 | 1 | - | - |
| learning-output-style | 0 | 0 | 0 | 0 | SessionStart (partial) | - |
| linear | 0 | 0 | 0 | 1 | - | - |
| lua-lsp | 0 | 0 | 0 | 0 | - | lsp |
| math-olympiad | 1 | 0 | 0 | 0 | - | - |
| math-proof | 2 | 0 | 3 | 0 | - | - |
| mcp-server-dev | 3 | 0 | 0 | 0 | - | - |
| mcp-tunnels | 0 | 1 | 0 | 0 | - | - |
| php-lsp | 0 | 0 | 0 | 0 | - | lsp |
| playground | 1 | 0 | 0 | 0 | - | - |
| playwright | 0 | 0 | 0 | 1 | - | - |
| plugin-dev | 7 | 1 | 3 | 0 | - | - |
| pr-review-toolkit | 0 | 1 | 6 | 0 | - | - |
| project-artifact | 1 | 0 | 0 | 0 | - | - |
| pyright-lsp | 0 | 0 | 0 | 0 | - | lsp |
| ralph-loop | 0 | 3 | 0 | 0 | Stop (partial) | - |
| receipts | 1 | 0 | 0 | 0 | - | - |
| ruby-lsp | 0 | 0 | 0 | 0 | - | lsp |
| rust-analyzer-lsp | 0 | 0 | 0 | 0 | - | lsp |
| security-guidance | 0 | 0 | 0 | 0 | SessionStart (partial), UserPromptSubmit (partial), PostToolUse (yes), Stop (partial) | - |
| serena | 0 | 0 | 0 | 1 | - | - |
| session-report | 1 | 0 | 0 | 0 | - | - |
| skill-creator | 1 | 0 | 0 | 0 | - | - |
| swift-lsp | 0 | 0 | 0 | 0 | - | lsp |
| telegram | 2 | 0 | 0 | 1 | - | - |
| terraform | 0 | 0 | 0 | 1 | - | - |
| typescript-lsp | 0 | 0 | 0 | 0 | - | lsp |
</details>
<details><summary>compound-engineering-plugin: 1 plugins</summary>
| Plugin | Skills | Commands | Agents | MCP | Hooks | Not translated |
| --- | --- | --- | --- | --- | --- | --- |
| compound-engineering | 36 | 0 | 0 | 0 | - | - |
</details>
<details><summary>knowledge-work-plugins: 22 plugins</summary>
| Plugin | Skills | Commands | Agents | MCP | Hooks | Not translated |
| --- | --- | --- | --- | --- | --- | --- |
| productivity | 4 | 0 | 0 | 7 | - | - |
| enterprise-search | 5 | 0 | 0 | 5 | - | - |
| cowork-plugin-management | 2 | 0 | 0 | 0 | - | - |
| sales | 36 | 0 | 0 | 20 | - | - |
| finance | 8 | 0 | 0 | 2 | - | - |
| data | 10 | 0 | 0 | 6 | - | - |
| legal | 9 | 0 | 0 | 5 | - | - |
| marketing | 8 | 0 | 0 | 11 | - | - |
| customer-support | 5 | 0 | 0 | 6 | - | - |
| product-management | 8 | 1 | 0 | 14 | - | - |
| bio-research | 6 | 0 | 0 | 10 | - | - |
| slack-by-salesforce | 2 | 5 | 0 | 1 | - | - |
| apollo | 3 | 0 | 0 | 1 | - | - |
| common-room | 6 | 2 | 0 | 1 | - | - |
| engineering | 10 | 0 | 0 | 8 | - | - |
| human-resources | 9 | 0 | 0 | 3 | - | - |
| design | 7 | 0 | 0 | 7 | - | - |
| operations | 9 | 0 | 0 | 4 | - | - |
| small-business | 44 | 0 | 0 | 35 | - | - |
| brand-voice | 3 | 3 | 5 | 6 | - | - |
| zoom-plugin | 30 | 0 | 0 | 3 | - | - |
| pdf-viewer | 1 | 4 | 0 | 1 | - | - |
</details>
<details><summary>claude-code-workflows: 92 plugins</summary>
| Plugin | Skills | Commands | Agents | MCP | Hooks | Not translated |
| --- | --- | --- | --- | --- | --- | --- |
| documentation-standards | 2 | 0 | 0 | 0 | - | - |
| code-documentation | 0 | 2 | 3 | 0 | - | - |
| debugging-toolkit | 0 | 1 | 2 | 0 | - | - |
| git-pr-workflows | 0 | 3 | 1 | 0 | - | - |
| operating-kit | 0 | 0 | 5 | 0 | - | - |
| backend-development | 9 | 1 | 8 | 0 | - | - |
| frontend-mobile-development | 4 | 1 | 2 | 0 | - | - |
| full-stack-orchestration | 0 | 1 | 4 | 0 | - | - |
| unit-testing | 0 | 1 | 2 | 0 | - | - |
| tdd-workflows | 0 | 4 | 2 | 0 | - | - |
| code-refactoring | 0 | 3 | 2 | 0 | - | - |
| dependency-management | 0 | 1 | 1 | 0 | - | - |
| error-debugging | 0 | 3 | 2 | 0 | - | - |
| team-collaboration | 0 | 2 | 1 | 0 | - | - |
| llm-application-dev | 8 | 3 | 3 | 0 | - | - |
| llm-finetuning | 10 | 2 | 3 | 0 | - | - |
| agent-orchestration | 0 | 2 | 1 | 0 | - | - |
| context-management | 0 | 2 | 1 | 0 | - | - |
| machine-learning-ops | 2 | 1 | 3 | 0 | - | - |
| data-engineering | 4 | 2 | 2 | 0 | - | - |
| incident-response | 4 | 2 | 6 | 0 | - | - |
| error-diagnostics | 0 | 3 | 2 | 0 | - | - |
| distributed-debugging | 0 | 1 | 2 | 0 | - | - |
| observability-monitoring | 4 | 2 | 4 | 0 | - | - |
| deployment-strategies | 0 | 0 | 2 | 0 | - | - |
| deployment-validation | 0 | 1 | 1 | 0 | - | - |
| kubernetes-operations | 4 | 0 | 1 | 0 | - | - |
| cloud-infrastructure | 8 | 0 | 7 | 0 | - | - |
| cicd-automation | 4 | 1 | 5 | 0 | - | - |
| application-performance | 0 | 1 | 3 | 0 | - | - |
| database-cloud-optimization | 0 | 1 | 4 | 0 | - | - |
| comprehensive-review | 0 | 2 | 3 | 0 | - | - |
| performance-testing-review | 0 | 2 | 2 | 0 | - | - |
| framework-migration | 4 | 3 | 2 | 0 | - | - |
| codebase-cleanup | 0 | 3 | 2 | 0 | - | - |
| database-design | 1 | 0 | 2 | 0 | - | - |
| database-migrations | 0 | 2 | 2 | 0 | - | - |
| security-scanning | 5 | 3 | 2 | 0 | - | - |
| security-compliance | 0 | 1 | 1 | 0 | - | - |
| backend-api-security | 0 | 0 | 2 | 0 | - | - |
| frontend-mobile-security | 0 | 1 | 3 | 0 | - | - |
| data-validation-suite | 0 | 0 | 1 | 0 | - | - |
| api-scaffolding | 1 | 0 | 4 | 0 | - | - |
| api-testing-observability | 0 | 1 | 1 | 0 | - | - |
| seo-content-creation | 0 | 0 | 3 | 0 | - | - |
| seo-technical-optimization | 0 | 0 | 4 | 0 | - | - |
| seo-analysis-monitoring | 0 | 0 | 3 | 0 | - | - |
| documentation-generation | 3 | 1 | 5 | 0 | - | - |
| c4-architecture | 0 | 1 | 4 | 0 | - | - |
| avoid-ai-writing | 1 | 0 | 0 | 0 | - | - |
| multi-platform-apps | 0 | 1 | 6 | 0 | - | - |
| business-analytics | 2 | 0 | 1 | 0 | - | - |
| startup-business-analyst | 5 | 3 | 1 | 0 | - | - |
| before-you-build | 1 | 0 | 0 | 0 | - | - |
| hr-legal-compliance | 2 | 0 | 2 | 0 | - | - |
| customer-sales-automation | 0 | 0 | 2 | 0 | - | - |
| content-marketing | 0 | 0 | 2 | 0 | - | - |
| social-publishing | 1 | 0 | 1 | 0 | - | - |
| hermes-tweet | 1 | 0 | 0 | 0 | - | - |
| blockchain-web3 | 4 | 0 | 1 | 0 | - | - |
| quantitative-trading | 2 | 0 | 2 | 0 | - | - |
| payment-processing | 4 | 0 | 1 | 0 | - | - |
| game-development | 2 | 0 | 2 | 0 | - | - |
| accessibility-compliance | 2 | 1 | 1 | 0 | - | - |
| python-development | 16 | 1 | 3 | 0 | - | - |
| javascript-typescript | 4 | 1 | 2 | 0 | - | - |
| systems-programming | 3 | 1 | 4 | 0 | - | - |
| jvm-languages | 0 | 0 | 3 | 0 | - | - |
| web-scripting | 0 | 0 | 2 | 0 | - | - |
| functional-programming | 0 | 0 | 2 | 0 | - | - |
| julia-development | 0 | 0 | 1 | 0 | - | - |
| arm-cortex-microcontrollers | 0 | 0 | 1 | 0 | - | - |
| shell-scripting | 3 | 0 | 2 | 0 | - | - |
| developer-essentials | 11 | 0 | 1 | 0 | - | - |
| dgx-spark-ops | 3 | 1 | 1 | 0 | - | - |
| reverse-engineering | 4 | 0 | 3 | 0 | - | - |
| conductor | 3 | 6 | 1 | 0 | - | - |
| superself | 1 | 0 | 0 | 0 | - | - |
| ui-design | 9 | 4 | 3 | 0 | - | - |
| agent-teams | 6 | 7 | 4 | 0 | - | - |
| dotnet-contribution | 1 | 0 | 1 | 0 | - | - |
| meigen-ai-design | 0 | 2 | 3 | 0 | - | - |
| brand-landingpage | 1 | 0 | 0 | 0 | - | - |
| plugin-eval | 1 | 3 | 2 | 0 | - | - |
| block-no-verify | 1 | 1 | 0 | 0 | - | - |
| protect-mcp | 1 | 2 | 2 | 0 | PreToolUse (yes), PostToolUse (yes) | - |
| signed-audit-trails | 1 | 0 | 0 | 0 | - | - |
| review-agent-governance | 1 | 2 | 1 | 0 | PreToolUse (yes), PostToolUse (yes) | - |
| ship-mate | 1 | 2 | 6 | 0 | - | - |
| file-conversion | 1 | 0 | 0 | 0 | - | - |
| skill-forge-essentials | 3 | 0 | 0 | 0 | - | - |
| pptx-deck-creation | 5 | 0 | 1 | 0 | - | - |
</details>
README.md
+139
View File
@@ -0,0 +1,139 @@
# claude-4-opencode
Run Claude Code plugins on [opencode](https://opencode.ai) v2, and install them from Claude Code marketplaces.
It has two parts. `c4o` is a command-line tool that adds marketplaces and installs plugins, the way `claude plugin` does. The other part is an opencode plugin that loads what `c4o` installed and registers each plugin's skills, commands, agents, MCP servers and hooks with opencode. Plugins are used as published; nothing is converted or rewritten on disk.
Whether it works is checked end to end against the real opencode binary, using unmodified plugins from the most-installed marketplaces. See [What is tested](#what-is-tested) and [COMPATIBILITY.md](COMPATIBILITY.md).
## Getting started
Requires opencode 2.x, git, and Node 22 or later. Building needs [Bun](https://bun.sh).
```sh
git clone https://github.com/Heretek-AI/claude-4-opencode
cd claude-4-opencode
bun install && bun run build
alias c4o="node $PWD/dist/cli.js"
c4o setup # adds the plugin to opencode's config
c4o marketplace add anthropics/claude-plugins-official
c4o install superpowers feature-dev commit-commands
```
Start opencode. The plugins' skills are available to the model, their commands run as `/feature-dev:feature-dev`, and their hooks are active. A running opencode picks up later installs without a restart.
`c4o inspect <plugin>` shows what a plugin contributes and what could not be carried over. Run it before installing a plugin you do not know: hooks and MCP servers run commands on your machine, exactly as they do in Claude Code.
## Commands
| Command | What it does |
| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `c4o marketplace add <source>` | Adds a marketplace: `owner/repo`, `owner/repo@ref`, a git URL, a `marketplace.json` URL, or a local path |
| `c4o marketplace list` / `update [name]` / `remove <name>` | Manages added marketplaces |
| `c4o install <plugin>[@marketplace] ...` | Installs plugins. The marketplace can be left out when only one lists the plugin |
| `c4o update [plugin ...]` | Refreshes marketplaces and reinstalls plugins at what they now point to |
| `c4o enable` / `disable` / `uninstall <plugin>` | Turns a plugin on or off, or removes it |
| `c4o list` | Shows installed plugins |
| `c4o inspect <plugin or directory>` | Reports a plugin's components, hook support, and anything not translated |
| `c4o setup` | Registers the opencode plugin in opencode's global config |
| `c4o doctor` | Checks git, opencode, registration, and that installed plugins load |
Add `--json` to any command for machine-readable output.
## What is translated
| Claude Code | In opencode | Notes |
| ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| Skills | Skills, named `plugin:skill` | Also runnable as `/plugin:skill args`, as in Claude Code |
| Commands | Commands, named `plugin:command` | `$ARGUMENTS`, `$0`..`$N`, named arguments, `` !`shell` `` and fenced `!` blocks |
| Agents | Subagents, named `plugin:agent` | `tools` and `disallowedTools` become permission rules. `model` is ignored; agents use the session's model |
| MCP servers | MCP servers, named `plugin_server` | stdio and remote. `${VAR}` and `${VAR:-default}` are expanded from the environment |
| Hooks | See the table in [COMPATIBILITY.md](COMPATIBILITY.md#hook-events) | `command` and `http` handlers run. `prompt`, `agent` and `mcp_tool` handlers do not |
| `bin/` | On `PATH` for shell tool calls and command interpolation | |
| `${CLAUDE_PLUGIN_ROOT}`, `${CLAUDE_PLUGIN_DATA}`, `${CLAUDE_PROJECT_DIR}`, `${user_config.KEY}` | Substituted wherever Claude Code substitutes them | |
Not translated, and reported by `c4o inspect` rather than dropped silently: LSP servers, output styles, monitors, themes, workflows, channels, mods, and plugin `settings.json`.
Hooks are written against Claude Code's tool names and input fields. They receive opencode tool calls in that vocabulary (`shell` arrives as `Bash` with `command`, `edit` as `Edit` with `file_path`, a plugin's MCP tool as `mcp__plugin_<plugin>_<server>__<tool>`), plus a transcript file in Claude Code's JSONL format.
### Differences worth knowing
- A `UserPromptSubmit` hook that blocks a prompt does stop it from reaching the model, but opencode reports a generic error instead of the hook's message.
- A hook that asks for user confirmation (`permissionDecision: "ask"`) blocks the tool call, because a plugin cannot open a prompt in opencode.
- A hook's `systemMessage` is passed to the model as a note. Claude Code shows it to the user instead.
- When a command is run with no arguments, `$1`-style placeholders are left untouched so that shell snippets such as `awk '{print $1}'` in a command body are not blanked. Claude Code blanks them.
- Marketplace names follow Claude Code's rules, including the names reserved for Anthropic's own marketplaces.
## Configuration
Options go in opencode's config, alongside the plugin entry:
```jsonc
{
"plugins": [
{
"package": "/path/to/claude-4-opencode/dist",
"options": {
"pluginDirs": ["./my-plugin"], // load plugin directories directly, like claude --plugin-dir
"disable": ["mcp", "hooks"], // turn off whole kinds: skills, commands, agents, mcp, hooks, bin
},
},
],
}
```
| Environment variable | Meaning |
| -------------------- | -------------------------------------------------------------------------------------------- |
| `C4O_HOME` | Where marketplaces and plugins are stored. Default: `$XDG_DATA_HOME/opencode/claude-plugins` |
| `C4O_PLUGIN_DIRS` | Extra plugin directories, separated like `PATH` |
| `C4O_DISABLE` | Comma-separated kinds to turn off |
| `C4O_LOG` | File to write diagnostics to, including each hook's command, exit code and output |
The store never touches `~/.claude`.
## What is tested
Every tier runs the real `opencode` binary in a throwaway home directory. Marketplaces are pinned to the commits in `e2e/targets.lock.json`, so a run is repeatable.
| Tier | What it shows | When it runs |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| Unit | Parsing, translation and the hook protocol | Every push and pull request |
| Conformance | Every entry of every pinned marketplace resolves and loads, and opencode lists every component | Every push and pull request |
| Golden | Component names match what real Claude Code lists after installing the same plugins from the same commits | Every push and pull request |
| Scripted | A stub plays the model with scripted tool calls: skills load, commands render, agents run restricted, MCP tools answer, hooks block and inject | Every push and pull request |
| External | Every plugin that lives outside its marketplace's repository is fetched at its pinned commit and loaded | Nightly |
| Live | A real model drives the same plugins | Nightly, when the `OPENCODE_API_KEY` secret is set |
| Drift | Pins move to current commits, goldens are recaptured, and everything runs against the newest opencode | Weekly |
```sh
bun run test # unit
bun run e2e # conformance, golden and scripted, against the opencode on PATH
bun run e2e:report # print the compatibility report from the last run
bun run e2e:oracle # recapture golden files with your installed Claude Code
OPENCODE_API_KEY=... bun test ./e2e/live # live tier
C4O_E2E_FULL=1 bun test ./e2e/conformance.test.ts # include external plugins
```
Set `OPENCODE_BIN` to test a different opencode build. Do not run a bare `bun test`: it would also pick up anything under `review/`.
The golden files come from real Claude Code, run in an empty config directory with a dummy API key, hooks disabled and plugin MCP servers ignored. It installs the plugins and prints its startup inventory; it makes no model request and runs no plugin code.
## Layout
```
src/spec/ reads Claude Code's plugin and marketplace formats
src/store/ marketplaces, installs, enabled state
src/translate/ turns a loaded plugin into opencode values, and reports what it could not
src/runtime/ the opencode plugin, including the hook engine
src/cli.ts c4o
e2e/ sandbox, stub model, pinned targets, golden files, scenarios
docs/research/ prior art and what was learned about opencode v2's plugin API
```
## Background
[docs/research/prior-art.md](docs/research/prior-art.md) covers earlier projects in this space and how this one differs. [docs/research/opencode-v2-findings.md](docs/research/opencode-v2-findings.md) records how opencode v2's plugin API behaves in the places this project depends on.
The implementation is written from Claude Code's public documentation and checked against Claude Code's observable behavior. It contains no code from Claude Code or from reimplementations of it.
docs/research/opencode-v2-findings.md
+46
View File
@@ -0,0 +1,46 @@
# opencode v2 plugin API: what this project depends on
Observed on opencode 2.0.26 with throwaway probe plugins before the design was fixed, and now held in place by the end-to-end tests. The v2 plugin API is in beta; if one of these changes, a test fails.
## Loading and identity
- A plugin is `Plugin.define({ id, setup })` from `@opencode/plugin`. opencode loads `.ts` and `.js` files under `<config>/plugins/`, and anything listed in the `plugins` config field: an npm or git package, or an absolute directory containing a `server` or `index` entry.
- Skill, command and agent IDs may contain `:`. `frontend-design:frontend-design`, `/feature-dev:feature-dev` and the subagent `feature-dev:code-explorer` all register and resolve. MCP server names cannot use it, because opencode derives tool names from them and providers restrict tool names to `[A-Za-z0-9_-]`.
- Plugins activate after a location has booted. The inventory endpoints (`/api/skill`, `/api/command`, `/api/agent`, `/api/mcp`) can answer before a plugin has contributed, so tests poll. Prompts wait for activation.
- `ctx.skill.reload()` and its siblings re-run the plugin's transforms. That is how an install made by `c4o` reaches a running opencode.
## Hook surfaces
| Surface | Behavior relied on |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ctx.tool.hook("execute.before")` | The event's `input` is mutable. Throwing rejects the call; the model receives the error message as the tool result. `execute.after` does not fire for a rejected call |
| `ctx.tool.hook("execute.after")` | Fires with `status: "completed"` or `"error"`. The completed `result` is mutable, so text can be appended to what the model sees |
| `ctx.session.hook("prompt")` | The prompt text is mutable. Throwing keeps the prompt out of the session, and the API answers HTTP 500 with an empty body. There is no way to reject with a message |
| `ctx.session.hook("context")` | Runs before every model request, with a mutable `system` array. It runs for subagent sessions too |
| `ctx.event.subscribe()` | `session.execution.succeeded` fires when a session finishes a turn, including for subagent sessions. Calling `ctx.session.prompt` from the handler starts another turn |
| `ctx.shell.hook("create.before")` | The `env` of shell tool calls is mutable, which is how `bin/` gets onto `PATH` |
Subagents run as child sessions with a `parentID`. That is how hook events meant for the main conversation are kept away from them.
## Tools
- Built-in tools are `shell`, `read`, `write`, `edit`, `glob`, `grep`, `webfetch`, `websearch`, `subagent`, `skill`, `question`, with camelCase input fields (`path`, `oldString`).
- MCP tools are not offered to the model directly. opencode exposes them through Code Mode: one `execute` tool that runs JavaScript, with each MCP tool at `tools.<server>.<tool>()`. `execute.before` still fires for the inner call, named `<server>_<tool>`.
- An agent's `permissions` are rules of `{ action, resource, effect }`, and the last matching rule wins. Tools an agent is denied are removed from the list offered to the model, not merely refused when called.
## Driving opencode from tests
- `opencode run` treats piped stdin as part of the prompt and waits for it to close. Automation must close stdin.
- `opencode run --standalone` uses a private server. With `HOME` and the `XDG_*` directories pointed at a temporary directory, a run touches nothing else.
- `opencode serve` takes its password from `OPENCODE_PASSWORD` and uses HTTP Basic with the user `opencode`. Requests name their project with `location[directory]=<path>`.
- A provider with `"package": "@ai-sdk/openai-compatible"` and `settings.baseURL` is served by a bundled adapter, so a local stub can play the model with nothing to install. Session titles are requested from the same model, in calls that carry no tools; the stub tells them apart that way.
## Gaps
These are places where a Claude Code behavior has no opencode surface today. Each is reported by `c4o inspect` and in the compatibility report.
- A plugin cannot reject a prompt with a message the user sees.
- A tool hook cannot ask the user to confirm.
- A server plugin has no channel for a notice to the user.
- There is no plugin surface for LSP servers; they are configuration only.
- Nothing distinguishes a session that was cleared or compacted from one that was started, so `SessionStart` reports only `startup` and `resume`.
docs/research/prior-art.md
+46
View File
@@ -0,0 +1,46 @@
# Prior art
Researched in October 2026, before and during the first implementation. The question was whether anyone had already made Claude Code plugins and marketplaces work on opencode v2.
**Short answer:** parts of it exist, for opencode v1 or as one-off file conversion. Nothing found loads Claude Code plugins on opencode v2, and nothing found combines marketplace management with runtime support for hooks.
## What exists
| Project | Approach | Covers | Does not cover |
| ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [oh-my-openagent](https://github.com/code-yeongyu/oh-my-openagent) (formerly oh-my-opencode), about 70k stars | Runtime compatibility layer inside a larger opencode plugin. Its `claude-code-compat-core` package has loaders for plugins, commands, agents, MCP servers, skills and hooks | Reads what Claude Code itself installed, from `~/.claude/plugins/installed_plugins.json` and `~/.claude/settings.json` | opencode v2: it depends on `@opencode-ai/plugin` 1.18.31, and v2 support is an open request ([#8485](https://github.com/code-yeongyu/oh-my-openagent/issues/8485), [#6169](https://github.com/code-yeongyu/oh-my-openagent/issues/6169)). It does not add marketplaces or install plugins; Claude Code has to do that first. Licensed under a Sustainable Use License, so it is not a base to build on |
| [gzb1128/opencode-plugin](https://github.com/gzb1128/opencode-plugin), MIT, 2 stars | Go CLI that adds Claude Code marketplaces and installs plugins. Its end-to-end test clones the official marketplace | Skills, symlinked into `~/.agents/skills` | Commands, agents, MCP servers, hooks. Its README says only `skills/` are linked. No runtime component |
| [compound-plugin](https://github.com/EveryInc/compound-engineering-plugin) by Every, MIT, about 25k stars | `compound-plugin convert <dir> --to opencode` rewrites a Claude Code plugin into another tool's file format, for about ten target tools | Agents, commands, skills and MCP servers, per its documentation | Hooks, marketplaces, anything at runtime. A converted plugin is a copy that has to be converted again when the original changes |
| opencode v2 itself | A built-in `opencode.config.compatibility` plugin | Loose skills under `.claude/skills` and `.agents/skills` | Plugins, marketplaces, commands, agents, MCP servers, hooks |
Some plugin authors ship their own opencode port next to the Claude Code plugin: [superpowers](https://github.com/obra/superpowers) carries an `.opencode/` directory, and [wshobson/agents](https://github.com/wshobson/agents) describes itself as a multi-harness marketplace. That works plugin by plugin and relies on each author.
## Relevant upstream discussion
- [anomalyco/opencode#50133](https://github.com/anomalyco/opencode/issues/50133): a plugin author maps Claude Code's hook events onto opencode's plugin API and lists seven gaps. Several match what this project found (no signal for failed tool calls beyond a status, no working directory on tool hooks, no per-agent hooks).
- [anomalyco/opencode#53402](https://github.com/anomalyco/opencode/issues/53402): v2 has no `CLAUDE.md` fallback.
- [anomalyco/opencode#47345](https://github.com/anomalyco/opencode/issues/47345): a request to expose the plugin manager as a slash command.
- [anomalyco/opencode#8386](https://github.com/anomalyco/opencode/issues/8386) (closed): a request for a skill registry and installer.
No issue or pull request was found that proposes Claude Code plugin or marketplace support in opencode.
## How this project differs
- It targets the opencode v2 plugin API (`@opencode/plugin`, `Plugin.define`), which is a hard break from v1.
- It manages marketplaces and installs itself, with the same on-disk model as Claude Code, and does not need Claude Code installed.
- It works at runtime on the unmodified plugin, so hooks, `${CLAUDE_PLUGIN_ROOT}` and enable/disable behave as plugin authors expect, and updates need no reconversion.
- Its claims are checked against real Claude Code: the names it gives components are compared with what Claude Code lists for the same plugins at the same commits.
## Sources used for the implementation
The format is implemented from Anthropic's public documentation:
- [Plugin manifest reference](https://code.claude.com/docs/en/plugins-reference)
- [Marketplace reference](https://code.claude.com/docs/en/plugins/marketplace-reference)
- [Hooks reference](https://code.claude.com/docs/en/hooks)
and exercised against Anthropic's public repositories: [claude-plugins-official](https://github.com/anthropics/claude-plugins-official), [skills](https://github.com/anthropics/skills) and [knowledge-work-plugins](https://github.com/anthropics/knowledge-work-plugins).
Popularity figures come from the install statistics Anthropic publishes on the `stats` branch of claude-plugins-official ([plugin-installs.json](https://raw.githubusercontent.com/anthropics/claude-plugins-official/refs/heads/stats/stats/plugin-installs.json)). The snapshot of 2 October 2026 lists 322 plugins and about 10.3 million unique installs. The ten most installed were frontend-design (1.29M), superpowers (1.15M), code-review (492k), context7 (458k), skill-creator (440k), code-simplifier (383k), playwright (367k), github (354k), claude-md-management (322k) and vercel (285k). The behavioral test set was chosen from that list so that every component type is covered.
A reimplementation of Claude Code was consulted only to confirm behavior the documentation leaves open, such as how skill and command names are derived. Its license notes that it derives from proprietary source, so no code was taken from it. Those behaviors are now pinned by the golden files instead, which record real Claude Code's output.