# 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: `${XDG_CONFIG_HOME:-~/.config}/opencode/plugins/llm-wiki-kit.js`
- project: `<workspace>/.opencode/plugins/llm-wiki-kit.js` (if you prefer project-scoped)

The plugin launches the installer-supplied Node executable and `bin/llm-wiki.js` as separate argv entries, then pipes event JSON over stdin. This reuses the **same** capture pipeline (session envelope, turn-state, live Q&A, opt-in full-qa, redaction). 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 nonsynthetic, nonignored `output.parts` text segments and joined with newlines. Quote characters are preserved. A valid user message ID is forwarded as `turn_id`. |
| `tool.execute.before` | `PreToolUse` | `tool` name + `args` forwarded with the current `turn_id`. |
| `tool.execute.after` | `PostToolUse` | Matched by the native session and call IDs from the before event. For `bash`, only the output string and safe integer `metadata.exit` are forwarded as `tool_response.output` and canonical `tool_response.exit_code`; missing or invalid exit status is `null`. Other tool types keep the existing output payload. |
| `experimental.session.compacting` | `PreCompact` | Experimental. |
| `experimental.text.complete` + `message.updated` + `message.part.updated` | bounded in-memory answer data | Completed part IDs establish part order; only final text-part updates with valid `time.start` and `time.end` are retained. Message identity and completion metadata must match the current user turn. |
| `event` (`session.idle`) | `Stop` | opencode has no dedicated Stop hook. The plugin binds the idle hint to an already observed assistant message for the current user turn and sends its eligible completed text as `last_assistant_message`. |

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 `${XDG_CONFIG_HOME:-~/.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.
- **Bounded live answer capture.** The plugin keeps only live message identity, completion flags, and up to 4,000 text units per assistant message in memory. It does not read OpenCode history or transcript files. More than 4 assistant message candidates makes the whole current turn answer-unavailable: both idle `Stop` and answer-bearing `PreCompact` are suppressed until the next genuine user message. More than 8 text parts or an answer over 4,000 units omits the answer text, while a verified normal terminal stop can still send `Stop` without answer text so the existing missing-result path can handle it. Uncertain part order, unsupported final-part timestamps, or incomplete message metadata do not qualify as a completed answer; a normal stop waits for enough evidence, while a terminal error, length limit, or content filter can still send `Stop` without answer text.
- **Serialized hook bridge.** Node hook calls run in per-session FIFO order with a 5-second absolute deadline, including queue time. Saturated or expired work returns no context and does not claim capture. If child exit cannot be confirmed after a timeout, that session's bridge remains unavailable until exit is observed.
- **OpenCode CLI positional quoting.** OpenCode 1.18.11's CLI quotes positional text containing spaces before delivering it to the plugin. The bridge preserves the received characters and does not strip quotes or decode JSON-looking text. For exact raw prompt text, use OpenCode's stdin-only CLI input or direct SDK text input; see the [OpenCode v1.18.11 CLI source](https://github.com/anomalyco/opencode/blob/v1.18.11/packages/opencode/src/cli/cmd/run.ts) and [text-part processing](https://github.com/anomalyco/opencode/blob/v1.18.11/packages/opencode/src/session/processor.ts#L481-L499).
- **Bridge ownership.** Install and post-update refresh an absent or proven unchanged managed plugin. They preserve user-edited and unmanaged plugin bytes and report incomplete setup. `--replace-hooks` may replace only a proven owned plugin after backup; 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.
