honcho/docs/v3/guides/integrations/opencode.mdx

---
title: "OpenCode"
icon: 'code'
description: "Add AI-native memory to OpenCode"
sidebarTitle: 'OpenCode'
---

Give OpenCode long-term memory that survives context wipes, session restarts, and fresh chats. OpenCode remembers what you're working on, your durable preferences, and prior context across every project you touch.

## Quick Start

### Step 1: Get Your Honcho API Key

1. Go to **[app.honcho.dev](https://app.honcho.dev)**
2. Sign up or log in
3. Copy your API key (starts with `hch-`)

### Step 2: Install the Plugin

<Note>
This plugin requires the [OpenCode CLI](https://opencode.ai). If `opencode` isn't on your `PATH`, install it first, then restart your shell.
</Note>

Install the plugin:

```bash
opencode plugin "@honcho-ai/opencode-honcho" --global
```

To update an existing plugin install:

```bash
opencode plugin "@honcho-ai/opencode-honcho" --force
```

OpenCode:

- registers `@honcho-ai/opencode-honcho` with OpenCode
- resolves the package's native server and TUI plugin targets
- updates plugin entries in your global OpenCode config
- activates the plugin globally for every OpenCode project

### Step 3: Run Setup in OpenCode

1. Start OpenCode
2. Run `/honcho:setup`
3. Keep the default **Honcho Cloud** option unless you want a self-hosted or local endpoint
4. Paste your Honcho API key
5. Run `/honcho:status` to verify the runtime

## What You Get

- **Persistent Memory** — OpenCode retains durable context across sessions
- **Cloud or Local Deployments** — Point at Honcho Cloud or a self-hosted / local instance
- **Workspace Mapping** — OpenCode projects map cleanly to Honcho workspaces
- **Flexible Session Mapping** — Scope sessions per directory, repo, branch, chat instance, or globally
- **Durable Writes** — Save stable conclusions and retain session context across OpenCode runs
- **Memory Retrieval** — Search session messages, query Honcho's reasoning, and inject relevant context into prompts
- **Agent Tools** — First-class tools for search, chat, and conclusion-writing inside OpenCode

## Configuration

Configuration lives in a single shared file at `~/.honcho/config.json`, shared with other Honcho hosts (Claude Code, Cursor, etc.). OpenCode reads and writes this file directly, and OpenCode-specific defaults live under `hosts.opencode`. Edit the file direct or use `/honcho:config` to change it via OpenCode's chat, or call the `honcho_set_config` tool for other settings.

```jsonc
{
  "apiKey": "hch-...",
  "peerName": "alice",
  "baseUrl": "https://api.honcho.dev",
  "hosts": {
    "opencode": {
      "workspace": "opencode",
      "aiPeer": "opencode",
      "recallMode": "hybrid",
      "observationMode": "directional",
      "sessionStrategy": "per-directory"
    }
  }
}
```

Top-level shared fields are `apiKey`, `peerName`, and `baseUrl`. OpenCode's host-scoped settings live under `hosts.opencode`: `workspace`, `aiPeer`, `recallMode`, `observationMode`, and `sessionStrategy`.

### Cloud vs Local

For **Honcho Cloud**:

- `apiKey` is required
- `baseUrl` should stay at `https://api.honcho.dev`

For **self-hosted or local Honcho**:

- `baseUrl` should point to your deployment (e.g. `http://127.0.0.1:8000`)
- `apiKey` is only required if the deployment is authenticated

<Warning>
If OpenCode is running inside Docker or another remote environment, `localhost` won't refer to your host machine. The `baseUrl` must be reachable from the OpenCode runtime.
</Warning>

### Recall Modes

| Mode | Behavior | Best for |
| --- | --- | --- |
| `hybrid` (default) | Context injection **and** tool access | Most users — balanced memory coverage |
| `context` | Only inject memory into system prompts | Predictable prompts, no tool calls |
| `tools` | Only expose memory as tools | Explicit, on-demand retrieval |

### Session Strategies

| Strategy | Behavior | Best for |
| --- | --- | --- |
| `per-directory` (default) | One session per working directory | Most projects |
| `per-repo` | One session per repository | Repos with multiple entry directories |
| `git-branch` | Session follows the current git branch | Branch-specific workflows |
| `per-session` | New session per OpenCode session id | Short-lived isolated work |
| `chat-instance` | Session tied to the current chat instance | Highly ephemeral usage |
| `global` | One session for everything | Shared memory across all work |

## Operator Commands

| Command | Description |
| --- | --- |
| `/honcho:setup` | First-time setup for cloud or local Honcho |
| `/honcho:status` | Show effective Honcho status for the current OpenCode project |
| `/honcho:settings` | Show effective config values and config paths |
| `/honcho:config` | Change `recallMode` |

## Agent Tools

The plugin exposes these tools inside OpenCode:

| Tool | Description |
| --- | --- |
| `honcho_setup` | Validate setup and persist shared credentials or endpoint settings |
| `honcho_status` | Show effective runtime status |
| `honcho_get_config` | Read effective and persisted settings |
| `honcho_set_config` | Update a persisted shared setting |
| `honcho_search` | Search Honcho session messages |
| `honcho_chat` | Query Honcho for reasoning-backed context |
| `honcho_create_conclusion` | Save a durable memory conclusion |

## Plugin Surfaces

The plugin hooks into these OpenCode plugin capabilities:

- `event`
- `chat.message`
- `tool.execute.after`
- `command.execute.before`
- `experimental.chat.system.transform`
- `experimental.session.compacting`
- `shell.env`
- `tool`

## Building with Teammates

Because `~/.honcho/config.json` is shared across Honcho hosts, teammates can collaborate by pointing at the same workspace while keeping their own identities. Sessions are automatically prefixed by `peerName` to avoid collisions.

**Alice** (`~/.honcho/config.json`):
```json
{
  "apiKey": "hch-team-key...",
  "peerName": "alice",
  "hosts": {
    "opencode": { "workspace": "team-acme", "aiPeer": "opencode" }
  }
}
```

**Bob** (`~/.honcho/config.json`):
```json
{
  "apiKey": "hch-team-key...",
  "peerName": "bob",
  "hosts": {
    "opencode": { "workspace": "team-acme", "aiPeer": "opencode" }
  }
}
```

Both write to `team-acme`; Honcho's dialectic reasoning draws on context from both peers.

## Next Steps

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/plastic-labs/opencode-honcho">
    Source code, issues, and README.
  </Card>

  <Card title="Honcho Architecture" icon="sitemap" href="../../documentation/core-concepts/architecture">
    Learn about peers, sessions, and dialectic reasoning.
  </Card>
</CardGroup>