Honcho Plugin for Opencode

Add AI-native memory to OpenCode

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

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

Step 2: Install the Plugin

This package installs the Honcho plugin into OpenCode and writes the Honcho command templates into your global OpenCode config.

npx @honcho-ai/opencode-honcho install

This installer expects the opencode CLI to already be installed and available on your PATH. If the installer cannot find opencode, restart your shell or source your shell config and run the command again.

Step 3: Run Setup in OpenCode

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

Step 4: (Optional) Kickstart with an Interview

/honcho:interview

This captures durable preferences or stable project context into Honcho memory.

What You Get

• Persistent Memory - OpenCode can retain durable context across sessions
• Cloud or Local Deployments - Use Honcho Cloud or point at a self-hosted or local Honcho instance
• Workspace Mapping - OpenCode projects map to Honcho workspaces
• Session Mapping - Sessions can be scoped per directory, repo, branch, chat instance, or globally
• Durable Writes - Honcho can retain stable conclusions and session context
• Memory Retrieval - Search memory, query Honcho knowledge, and inject relevant context into prompts
• Peer Modeling - Supports the default classic peer model and optional hierarchical modeling for delegated agent flows

Installation Output

The installer:

• registers @honcho-ai/opencode-honcho with OpenCode
• enables both native server and TUI plugin targets
• writes Honcho command templates into global OpenCode config
• activates the plugin globally for all OpenCode projects

Configuration

OpenCode Honcho configuration lives in:

• global config: ~/.config/opencode/honcho.json
• optional project override: .opencode/honcho.json

The global config is the normal place to start. Project config is only needed when a specific repo should behave differently.

{
  "enabled": true,
  "honchoApiKey": "hch-...",
  "baseUrl": "https://api.honcho.dev",
  "peerName": "",
  "aiPeer": "",
  "workspace": "",
  "globalOverride": false,
  "linkedHosts": [],
  "recallMode": "hybrid",
  "observation": "directional",
  "peerModel": "classic",
  "writeFrequency": "async",
  "sessionStrategy": "per-directory",
  "dialecticReasoningLevel": "low",
  "dialecticDynamic": true,
  "dialecticMaxChars": 600,
  "messageMaxChars": 25000,
  "saveMessages": true,
  "contextRefresh": {
    "messageThreshold": 30,
    "ttlSeconds": 300,
    "skipTrivialPrompts": true,
    "useSessionStartDialectic": true
  },
  "hosts": {
    "opencode": {
      "workspace": "opencode",
      "aiPeer": "opencode",
      "linkedHosts": []
    }
  }
}

Cloud vs Local

For Honcho Cloud:

• honchoApiKey is required
• baseUrl should remain https://api.honcho.dev

For self-hosted or local Honcho:

• baseUrl should point to your deployment, for example http://127.0.0.1:8000
• honchoApiKey is required only if that deployment requires authentication

If OpenCode is running in Docker or another remote environment, localhost may not refer to your machine. The configured baseUrl must be reachable from the OpenCode host runtime.

Session Strategies

Strategy	Behavior	Best for
per-directory	One session per working directory	Default project memory
per-repo	One session per repository	Repos with multiple entry directories
git-branch	Session changes with the current branch	Branch-specific workflows
per-session	New session for each OpenCode session id	Short-lived isolated work
chat-instance	Session follows 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:set	Persist a config field in .opencode/honcho.json
/honcho:unset	Reset a project config field back to its default
/honcho:mode	Change recallMode
/honcho:write	Change writeFrequency only. This does not create memory
/honcho:interview	Capture durable memory or preferences into Honcho

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 project setting
honcho_search	Search Honcho session memory
honcho_chat	Query Honcho for reasoning-backed context
honcho_create_conclusion	Save a durable memory conclusion

Plugin Surfaces

The plugin uses these OpenCode plugin capabilities:

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

Development

npm install
npm run build
npm test
npm run check