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.

1. Go to app.honcho.dev
2. Sign up or log in
3. Copy your API key

OpenCode installs the Honcho plugin and adds it to your global OpenCode config.

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

To update an existing plugin install:

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

Existing installs keep directional observation until you choose. After updating, OpenCode prompts you to keep directional or switch to unified (also via /honcho:setup or /honcho:config). If you switch to unified, you can optionally run /honcho:import to reingest local OpenCode transcripts into the new collection.

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

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. Enter your peerName
6. Run /honcho:status to verify the runtime
7. If you are upgrading an existing install, choose directional vs unified when prompted. After switching to unified, optionally run /honcho:import to backfill local history

• Persistent Memory - OpenCode can retain durable context across sessions
• Hook-Driven Memory - Hooks inject memory into the prompt and record significant tool activity, so recall works regardless of the model
• Honcho Memory Skill - A honcho-memory skill is installed into OpenCode's skills directory so the agent knows when to pull and save memory on its own
• 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 - User and root-agent observation flags are configurable (observationMode, agentObserveMe)

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 all OpenCode projects

OpenCode Honcho configuration lives in:

• ~/.honcho/config.json

OpenCode reads and writes this shared config file directly. OpenCode-specific defaults live under hosts.opencode in that file.

{
  "apiKey": "hch-...",
  "peerName": "user",
  "baseUrl": "https://api.honcho.dev",
  "hosts": {
    "opencode": {
      "workspace": "opencode",
      "aiPeer": "opencode",
      "recallMode": "hybrid",
      "observationMode": "unified", // new installs; existing configs without this field stay directional
      "agentObserveMe": false, // true opts into self-observation on the root agent peer
      "sessionStrategy": "per-directory",
      "removeUserPrefix": true, // true uses the bare peerName; false (default on upgrade) keeps the legacy user-<peerName> peer
      "apiKey": "hch-..." // optional; overrides the root apiKey for this host
    }
  }
}

For Honcho Cloud:

• apiKey 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
• apiKey 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.

Controls which Honcho collection honcho_chat, honcho_create_conclusion, and targeted prompt recall use for the user. This is independent of agentObserveMe (whether the agent peer is modeled). Changing modes does not migrate existing conclusions — use /honcho:import to backfill local OpenCode transcripts so Honcho can derive into the new collection.

New ~/.honcho/config.json files stamp observationMode: "unified". Configs that predate the field keep directional so an upgrade does not orphan already-derived memory. After updating, OpenCode prompts you to keep directional or switch to unified (/honcho:setup, /honcho:config, or the TUI launch dialog). If you switch, optionally run /honcho:import to reingest local OpenCode transcripts:

{
  "hosts": {
    "opencode": {
      "observationMode": "unified"
    }
  }
}

The root agent peer is created with observeMe: false by default: Honcho models the user, not the assistant. Set agentObserveMe to true if you want a peer card / representation of the agent itself.

{
  "hosts": {
    "opencode": {
      "agentObserveMe": true
    }
  }
}

/honcho:import reads session history through the OpenCode SDK client that the plugin receives, maps sessions with the same sessionStrategy as live capture, and uploads user/assistant text with original timestamps.

• First call (or the TUI preview) is a dry run — it does not upload.
• Confirming sends conversation content to Honcho. Already-imported sessions are skipped (~/.honcho/opencode-import-state.json).
• After switching an existing install to observationMode: "unified", import so past transcripts can be derived into the user self-collection instead of remaining only on the old directional pair.

The plugin exposes these tools inside OpenCode:

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

• experimental.chat.system.transform always appends the Honcho memory instruction. With recallMode hybrid or context it also adds a stable memory snapshot (user profile, agent context, session summary), captured once on the first turn of a session.
• chat.message retrieves prompt-specific recall on user turns in hybrid and context mode, appending a synthetic memory part when it yields a new block. Unchanged blocks are deduplicated within the session. In tools mode nothing beyond the instruction is injected; the model reaches memory only through the honcho_* tools.
• tool.execute.after records shell commands, file edits, and delegated tasks to the session. Read-only and trivial calls are skipped. Shell arguments that may carry credentials are redacted, keeping only the executable name.
• On session start and after honcho_setup, the packaged honcho-memory skill is copied to ~/.config/opencode/skills/honcho-memory, or $OPENCODE_CONFIG_DIR/skills/honcho-memory when set. An unchanged file is left untouched.

For macOS/Linux local branch testing:

bun install
bun run build
opencode plugin "$PWD" --global --force

That command wires the current checkout into OpenCode with --force, which is the intended local branch-testing flow.