Skip to main content

Documentation Index

Fetch the complete documentation index at: https://honcho.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

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
  2. Sign up or log in
  3. 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

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

ModeBehaviorBest for
hybrid (default)Context injection and tool accessMost users — balanced memory coverage
contextOnly inject memory into system promptsPredictable prompts, no tool calls
toolsOnly expose memory as toolsExplicit, on-demand retrieval

​
Session Strategies

StrategyBehaviorBest for
per-directory (default)One session per working directoryMost projects
per-repoOne session per repositoryRepos with multiple entry directories
git-branchSession follows the current git branchBranch-specific workflows
per-sessionNew session per OpenCode session idShort-lived isolated work
chat-instanceSession tied to the current chat instanceHighly ephemeral usage
globalOne session for everythingShared memory across all work

​
Operator Commands

CommandDescription
/honcho:setupFirst-time setup for cloud or local Honcho
/honcho:statusShow effective Honcho status for the current OpenCode project
/honcho:settingsShow effective config values and config paths
/honcho:configChange recallMode

​
Agent Tools

The plugin exposes these tools inside OpenCode:
ToolDescription
honcho_setupValidate setup and persist shared credentials or endpoint settings
honcho_statusShow effective runtime status
honcho_get_configRead effective and persisted settings
honcho_set_configUpdate a persisted shared setting
honcho_searchSearch Honcho session messages
honcho_chatQuery Honcho for reasoning-backed context
honcho_create_conclusionSave 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.

​
Next Steps

GitHub Repository

Source code, issues, and README.

Honcho Architecture

Learn about peers, sessions, and dialectic reasoning.