# opencode Integration

llm-wiki-kit supports [opencode](https://opencode.ai) as a capture provider (alongside Codex and Claude Code).

## How it differs from Codex / Claude Code

Codex and Claude Code run an **external shell command** per hook event and deliver JSON over stdin. opencode uses an **in-process JavaScript plugin** model — there is no `hooks` JSON section in `opencode.json`. To bridge the two models, llm-wiki-kit installs a tiny plugin at:

- global: `~/.config/opencode/plugins/llm-wiki-kit.js`
- project: `<workspace>/.opencode/plugins/llm-wiki-kit.js` (if you prefer project-scoped)

The plugin spawns `llm-wiki hook opencode <EventName>` and pipes JSON over stdin, so the **same** capture pipeline (session envelope, turn-state, live Q&A, opt-in full-qa, redaction) is reused. Context returned by the hook is injected into opencode's `output.system` (SessionStart) or `output.parts` (UserPromptSubmit).

## Event mapping

opencode native hook → Claude-compatible event name used by llm-wiki-kit:

| opencode hook | llm-wiki event | Notes |
|---|---|---|
| `experimental.chat.system.transform` | `SessionStart` | Experimental; may change between opencode versions. Best equivalent for session-start context injection. |
| `chat.message` | `UserPromptSubmit` | Prompt text is read from `output.parts` text segments. |
| `tool.execute.before` | `PreToolUse` | `tool` name + `args` forwarded. |
| `tool.execute.after` | `PostToolUse` | `tool` name + `args` + `output` forwarded. |
| `experimental.session.compacting` | `PreCompact` | Experimental. |
| `event` (`session.idle`) | `Stop` | opencode has no dedicated Stop hook; the generic `event` hook is filtered to `session.idle` and treated as the Stop-equivalent so full-qa capture fires. |

opencode has no direct equivalent for Claude Code's `InstructionsLoaded`, `SubagentStop`, `PostToolBatch`, or `SessionEnd`, so those events are not captured for opencode sessions.

## Install

```
llm-wiki install --workspace /apps
```

This writes the bridge plugin to `~/.config/opencode/plugins/llm-wiki-kit.js`. To skip opencode (and codex/claude), use `--no-opencode` (parity with `--no-codex` / `--no-claude`). Restart any active opencode session after install so the plugin loads.

## Limitations

- **Experimental hooks.** `experimental.chat.system.transform` and `experimental.session.compacting` are marked experimental in the opencode plugin types and may change or be removed without notice across opencode versions.
- **No `InstructionsLoaded`/`SubagentStop`/`PostToolBatch`/`SessionEnd`.** opencode does not emit these, so the corresponding recovery/archive flows do not fire for opencode sessions.
- **Response capture gap under opt-in full-qa.** When `LLM_WIKI_KIT_FULL_QA=1` is on, opencode's `## Response` section may be empty/`(not captured)` because the `session.idle` event does not expose the last assistant text; Question and Tool capture are unaffected.
- **Bridge is kit-managed.** `llm-wiki install` overwrites `llm-wiki-kit.js`; keep custom plugin edits in a separate file.

## See also

- `llm-wiki/wiki/decisions/2026-08-07-full-qa-capture-channel.md` — full Q&A capture channel + opencode provider decision.
- `docs/integrations/codex.md`, `docs/integrations/claude-code.md` — the other two providers.