Annex — OpenCode

This guide covers integrating KaKeKiKoKu with OpenCode, an open-source coding agent available as a terminal interface, desktop app, and IDE extension.

OpenCode is model-agnostic. You can connect it to commercial, open-source, cloud, or local providers and switch models without changing the KaKeKiKoKu integration.

This guide covers native Windows and Linux. The npm proxy route was validated on 22 July 2026 with OpenCode Desktop 1.18.4, KaKeKiKoKu 1.15.1, @wuniq/mcp 1.0.1, and Windows 11 Home build 26200. Linux remains Not tested.

OpenCode does not support KaKeKiKoKu channels today. KaKeKiKoKu therefore works in Precise mode: the model can use KaKeKiKoKu MCP tools, while KaKeKiKoKu UI actions that would push messages to the AI copy text to the clipboard for you to paste.

Requirements

Before you start the KaKeKiKoKu integration flow, you need:

• KaKeKiKoKu installed — Windows and Linux instructions are on the Download page. Linux installs from the Snap Store.
• OpenCode installed — use the current instructions in the official OpenCode documentation.
• A model provider configured in OpenCode. KaKeKiKoKu works through whichever model OpenCode orchestrates; it does not consume that provider's API directly.

Windows and WSL are different environments. The Windows instructions below assume OpenCode and the KaKeKiKoKu npm proxy run natively on Windows. If OpenCode runs inside WSL, do not point it at the Windows alias wuniq-mcp.exe or assume the environments are interchangeable. That cross-environment combination is not covered by this guide.

Install or update OpenCode

OpenCode publishes several installation methods. Two common choices are:

npm install -g opencode-ai

curl -fsSL https://opencode.ai/install | bash

After installation, open your project directory and run:

opencode

If OpenCode is new to you, connect a provider and complete a small task before adding KaKeKiKoKu. This separates model or account setup problems from MCP setup problems.

1. Register KaKeKiKoKu as a local MCP server

OpenCode reads MCP servers from its regular configuration under the mcp key. A project configuration is the clearest option because it travels with the workspace and keeps KaKeKiKoKu scoped to that project.

Option A: Project configuration (recommended)

1. In the root of the project you open with OpenCode, create or edit opencode.json.
2. If the file already contains providers, models, permissions, or other MCP servers, keep them. Add the wuniq entry inside the existing mcp object.
3. Use the configuration for your operating system:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "wuniq": {
      "type": "local",
      "command": ["npx", "-y", "@wuniq/mcp@1.0.1"],
      "enabled": true,
      "timeout": 30000
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "wuniq": {
      "type": "local",
      "command": ["/snap/bin/wuniq.wuniq-mcp"],
      "enabled": true,
      "timeout": 30000
    }
  }
}

The Windows example uses the public KaKeKiKoKu npm proxy and is the route covered by the measured validation above. It requires Node.js and npm. If you prefer the direct Microsoft Store alias, replace the command array with ["wuniq-mcp.exe"]. The longer timeout gives KaKeKiKoKu enough time to start and expose its tools on machines where the first launch takes more than OpenCode's short default discovery window.

Option B: Global configuration

If you want KaKeKiKoKu available in every OpenCode workspace, put the same mcp entry in OpenCode's global configuration instead:

%USERPROFILE%\.config\opencode\opencode.json

~/.config/opencode/opencode.json

Project configuration overrides global configuration when both define the same setting.

Windows path note. The validated npm route avoids protected Microsoft Store paths. If you use the direct alias, use wuniq-mcp.exe; do not point OpenCode at an absolute path under C:\Program Files\WindowsApps\..., where external MCP clients can hit Permission denied or EPERM.

Check registration

Close any existing OpenCode process, open a new terminal in the project, and run:

opencode mcp list

KaKeKiKoKu should appear as a configured local server. If it does not, check which opencode.json OpenCode is loading and validate the JSON.

For the current schema and configuration precedence, see OpenCode's official MCP servers and configuration pages.

2. Startup instructions (the second piece of the integration)

MCP registration gives OpenCode the KaKeKiKoKu tools. Startup instructions tell its model to use them at the beginning of every session.

1. In the project root, create AGENTS.md if it does not already exist.
2. Keep any existing project instructions and add this block:

   # KaKeKiKoKu Studio (Knowledge Engine)
   
   At the start of every session, run `open list` using the KaKeKiKoKu MCP tool. If it returns projects, `open` each one. If the list is empty, proceed normally — the user may open projects later from the KaKeKiKoKu UI. Never assume the working directory is a KaKeKiKoKu project; the working directory may be a container folder holding multiple projects. Only open paths that `open list` explicitly returns.
   
   Before working on any code file, `read` its KaKeKiKoKu sidecar for context. After changing code, run `sync`.

3. Save the file and start a new OpenCode session.

OpenCode also supports a global instructions file at ~/.config/opencode/AGENTS.md. The project file is recommended for KaKeKiKoKu because it keeps the workflow visible to everyone working in that repository.

If you already use CLAUDE.md. OpenCode can read it as a fallback, but AGENTS.md takes precedence when both exist. Put the KaKeKiKoKu block in the file OpenCode actually loads; do not maintain conflicting copies.

3. Apply the changes

1. Save opencode.json and AGENTS.md.
2. Close the current OpenCode terminal interface or desktop workspace completely.
3. Start OpenCode again from the project directory.
4. Start a fresh session so the model receives the updated instructions.

Use opencode mcp list before opening the interface if you want to confirm that the MCP configuration is visible independently of the model.

4. Start a session and verify

1. Start OpenCode in the directory that contains your AGENTS.md.
2. If the startup instructions are loaded, the model should call KaKeKiKoKu automatically. If it does not, ask:

   Run open list with the KaKeKiKoKu tool.

3. If everything is connected, OpenCode will show a KaKeKiKoKu tool call and list the projects KaKeKiKoKu knows about.
4. Let the startup instruction open every returned project, or ask the model to open the one you want.
5. In the KaKeKiKoKu UI, the AI-connected indicator should turn green when OpenCode uses the tool.

Quick test

Read the project index with KaKeKiKoKu.

The model should call a tool whose name starts with the configured KaKeKiKoKu server name. If it answers from general memory, ask explicitly to use the KaKeKiKoKu MCP and re-check AGENTS.md.

5. Working in Precise mode

In Precise mode, KaKeKiKoKu cannot push messages into OpenCode. The daily flow is:

• Starting a session. The instructions in AGENTS.md should make the model open KaKeKiKoKu projects automatically. If not, ask it to run open list with the KaKeKiKoKu tool.
• Sync. When code changes, KaKeKiKoKu detects drift in its panel. Ask OpenCode to run sync when you want it to reconcile code and context.
• "Talk to AI" buttons. In Precise mode, these copy a prompt to the clipboard. Paste it into OpenCode when you want the model to act on it.
• Drift alerts. They appear in KaKeKiKoKu's UI, not as push notifications in OpenCode.

Recommended KaKeKiKoKu configuration. Go to KaKeKiKoKu > Settings > Application > AI Sync and choose Precise mode.

6. Models and providers

KaKeKiKoKu connects to OpenCode, not to a particular model provider. Changing models does not require changing the KaKeKiKoKu MCP entry or the startup instructions.

OpenCode supports a broad range of commercial, open-source, cloud, and local models. The provider and model are the user's choice; KaKeKiKoKu does not prefer, require, endorse, or depend on any of them.

Instruction following matters. A working MCP connection does not guarantee that every model will act on AGENTS.md without prompting. During the Windows validation, two free preview models received and understood the startup instructions and used open, read, and sync correctly when asked, but did not reliably run open list on their own at session start. If you want a seamless KaKeKiKoKu workflow, choose a model with strong instruction-following and tool-use behavior. Otherwise, prompt it explicitly to run open list.

Check OpenCode's official provider documentation and current OpenCode Go model list before choosing a plan.

A large context window can help long agentic sessions, but KaKeKiKoKu does not require the whole repository to be injected at once. Its search and read tools load project knowledge progressively.

7. Troubleshooting

opencode mcp list does not show KaKeKiKoKu

1. Make sure the file is named opencode.json or opencode.jsonc.
2. For project configuration, place it in the project root and start OpenCode from that project or a child directory.
3. For global configuration, verify the path under ~/.config/opencode/.
4. Validate the JSON and make sure wuniq is inside the top-level mcp object.
5. If you already had an mcp object, merge the entry instead of creating a duplicate JSON key.

KaKeKiKoKu appears but tool discovery times out

Keep "timeout": 30000 in the KaKeKiKoKu MCP entry. Then close OpenCode completely and retry. The setting controls how long OpenCode waits for the local server to expose its tools.

OpenCode is running inside WSL

The Windows setup in this guide was validated with OpenCode and npx running natively on Windows. A client inside WSL runs in a Linux environment with different paths, process behavior, and permissions; the Windows alias wuniq-mcp.exe does not make those environments interchangeable. Run OpenCode natively for the Windows setup above. A cross-environment WSL-to-Windows KaKeKiKoKu bridge is not validated or documented here.

"Permission denied", "Access denied" or "EPERM" on Windows

Usually the configuration points into C:\Program Files\WindowsApps\.... Replace the absolute path with:

"command": ["wuniq-mcp.exe"]

where.exe wuniq-mcp.exe returns nothing

Windows cannot find the KaKeKiKoKu alias. Check that KaKeKiKoKu is installed, that it opens from the Start menu, and that %LOCALAPPDATA%\Microsoft\WindowsApps is in your PATH. Close and reopen the terminal after installing KaKeKiKoKu.

Linux command is not found

Check that the KaKeKiKoKu Snap is installed and that this command exists:

/snap/bin/wuniq.wuniq-mcp

OpenCode and KaKeKiKoKu must run under the same Linux user account.

KaKeKiKoKu cannot see projects outside your home folder on Linux

If projects live under /mnt/, /media/, a USB drive, or a VM shared folder such as /mnt/hgfs/, grant the KaKeKiKoKu Snap access:

sudo snap connect wuniq:removable-media

Then reload the KaKeKiKoKu web UI and open the project again.

The MCP is connected, but the model ignores KaKeKiKoKu

1. Confirm AGENTS.md is in the project root OpenCode is using.
2. Start a fresh session; existing sessions do not retroactively receive new startup instructions.
3. Ask whether the model can see the KaKeKiKoKu block in AGENTS.md. If it can quote or summarize the block, the instructions were loaded and the remaining issue is instruction-following behavior rather than MCP registration.
4. Ask explicitly: "Use the KaKeKiKoKu MCP tool to run open list."
5. Check that your OpenCode agent permissions do not deny the KaKeKiKoKu tool prefix.

The model fails, but KaKeKiKoKu tools are connected

Provider authentication, quotas, overloaded endpoints, and model-specific tool-use quality are separate from the MCP connection. Run opencode mcp list and a direct open list test before changing the KaKeKiKoKu configuration.

Still stuck?

Email support@kakekikoku.com with your operating system, OpenCode version, the relevant opencode.json MCP entry, and the output of opencode mcp list. KaKeKiKoKu can also generate a diagnostic report from the Support function in the app.