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

Go to app.honcho.dev
Sign up or log in
Copy your API key (starts with hch-)

Step 2: Install the Plugin

This plugin requires the OpenCode CLI. If opencode isn’t on your PATH, install it first, then restart your shell.

Install the plugin:

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

To update an existing plugin install:

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

Start OpenCode
Run /honcho:setup
Keep the default Honcho Cloud option unless you want a self-hosted or local endpoint
Paste your Honcho API key
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.

{
  "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

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.

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):

{
  "apiKey": "hch-team-key...",
  "peerName": "alice",
  "hosts": {
    "opencode": { "workspace": "team-acme", "aiPeer": "opencode" }
  }
}

Bob (~/.honcho/config.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.

Overview

Integrations

Tutorials

Community Integrations

Migrations

Quick Start

Step 1: Get Your Honcho API Key

Step 2: Install the Plugin

Step 3: Run Setup in OpenCode

What You Get

Configuration

Cloud vs Local

Recall Modes

Session Strategies

Operator Commands

Agent Tools

Plugin Surfaces

Building with Teammates

Next Steps

GitHub Repository

Honcho Architecture

​Quick Start

​Step 1: Get Your Honcho API Key

​Step 2: Install the Plugin

​Step 3: Run Setup in OpenCode

​What You Get

​Configuration

​Cloud vs Local

​Recall Modes

​Session Strategies

​Operator Commands

​Agent Tools

​Plugin Surfaces

​Building with Teammates

​Next Steps

GitHub Repository

Honcho Architecture

Quick Start

Step 1: Get Your Honcho API Key

Step 2: Install the Plugin

Step 3: Run Setup in OpenCode

What You Get

Configuration

Cloud vs Local

Recall Modes

Session Strategies

Operator Commands

Agent Tools

Plugin Surfaces

Building with Teammates

Next Steps