> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clideck.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenCode

> Using OpenCode with CliDeck — run any local or cloud model

[OpenCode](https://github.com/opencode-ai/opencode) is a terminal-based AI coding agent that supports a wide range of models — both local (Ollama, LM Studio) and cloud (OpenAI, Anthropic, Google, etc). This makes it a great choice if you want to use models that aren't available through the other agents.

OpenCode uses a **plugin bridge** instead of OTLP telemetry. A small JavaScript plugin runs inside OpenCode and sends real-time events to CliDeck over HTTP.

## Setup

<Steps>
  <Step title="Launch an OpenCode session">
    Click **OpenCode** in the session launcher. The session starts normally.
  </Step>

  <Step title="Install the bridge plugin">
    On first launch, CliDeck shows a setup toast: **"OpenCode — Bridge Plugin"**. Click **Install plugin**.

    CliDeck automatically copies the bridge plugin to `~/.config/opencode/plugins/clideck-bridge.js`.
  </Step>

  <Step title="Restart the session">
    After installation, click **Restart Session** on the toast. The new session will have the bridge active.
  </Step>
</Steps>

This is a one-time setup. The plugin stays in place across OpenCode and CliDeck updates. CliDeck also detects the plugin on startup — if it's already installed, the integration is enabled automatically.

<Tip>
  You can also install the plugin manually if you prefer:

  ```bash theme={null}
  mkdir -p ~/.config/opencode/plugins
  cp "$(npm root -g)/clideck/opencode-plugin/clideck-bridge.js" ~/.config/opencode/plugins/
  ```
</Tip>

## What the Plugin Does

The CliDeck bridge plugin sends events to `http://localhost:4000/opencode-events` when:

| Event                        | What CliDeck Gets               |
| ---------------------------- | ------------------------------- |
| `session.status` (busy/idle) | Working/idle status indicator   |
| `message.part.updated`       | Live message preview in sidebar |
| `session.updated`            | Session title and ID for resume |
| `session.created`            | Initial session connection      |

The plugin doesn't modify OpenCode's behavior or read your prompts. It only observes status changes and output text.

## Session Resume

OpenCode supports session resume. CliDeck captures the session ID from plugin events and uses `opencode --session <sessionId>` to reconnect to previous sessions.

Session IDs in OpenCode look like `ses_` followed by alphanumeric characters (e.g., `ses_abc123xyz`).

## How It Differs from OTLP Agents

| Aspect             | OTLP (Claude/Codex/Gemini)     | Plugin (OpenCode)                     |
| ------------------ | ------------------------------ | ------------------------------------- |
| Status detection   | I/O heuristics (byte rates)    | Explicit busy/idle events from plugin |
| Message preview    | Terminal output buffer parsing | Direct text from plugin events        |
| Session ID capture | OTLP log attributes            | Plugin event payload                  |
| Setup              | Env vars or config file        | Copy plugin file                      |

The plugin approach gives more accurate status information since OpenCode explicitly reports when it's busy or idle, rather than CliDeck having to guess from output patterns.

<Warning>
  If OpenCode releases a major update that changes its plugin API, the bridge plugin may need updating. Check for the latest CliDeck version with `npm update -g clideck`.
</Warning>