Skip to content

README.opencode.md

Latest commit

 

History

History
163 lines (109 loc) · 4.52 KB

README.opencode.md

File metadata and controls

163 lines (109 loc) · 4.52 KB
Raw

Wukong Code for OpenCode

Complete guide for using Wukong Code with OpenCode.ai.

Installation

Add wukong-code to the plugin array in your opencode.json (global or project-level):

{
  "plugin": ["wukong-code@git+https://github.com/wukongnotnull/wukong-code.git"]
}

Restart OpenCode. The plugin installs through OpenCode's plugin manager and registers all skills.

Verify by asking: "Tell me about your wukong-code"

OpenCode uses its own plugin install. If you also use Claude Code, Codex, or another harness, install Wukong Code separately for each one.

Migrating from the old symlink-based install

If you previously installed wukong-code using git clone and symlinks, remove the old setup:

# Remove old symlinks
rm -f ~/.config/opencode/plugins/wukong-code.js
rm -rf ~/.config/opencode/skills/wukong-code

# Optionally remove the cloned repo
rm -rf ~/.config/opencode/wukong-code

# Remove skills.paths from opencode.json if you added one for wukong-code

Then follow the installation steps above.

Usage

Finding Skills

Use OpenCode's native skill tool to list all available skills:

use skill tool to list skills

Loading a Skill

use skill tool to load brainstorming

Personal Skills

Create your own skills in ~/.config/opencode/skills/:

mkdir -p ~/.config/opencode/skills/my-skill

Create ~/.config/opencode/skills/my-skill/SKILL.md:

---
name: my-skill
description: Use when [condition] - [what it does]
---

# My Skill

[Your skill content here]

Project Skills

Create project-specific skills in .opencode/skills/ within your project.

Skill Priority: Project skills > Personal skills > Wukong Code skills

Updating

OpenCode installs Wukong Code through a git-backed package spec. Some OpenCode and Bun versions pin that resolved git dependency in a lockfile or cache, so a restart may not pick up the newest Wukong Code commit. If updates do not appear, clear OpenCode's package cache or reinstall the plugin.

To pin a specific version, use a branch or tag:

{
  "plugin": ["wukong-code@git+https://github.com/wukongnotnull/wukong-code.git#v5.0.3"]
}

How It Works

The plugin does two things:

  1. Injects bootstrap context via the experimental.chat.messages.transform hook, adding wukong-code awareness to every conversation.
  2. Registers the skills directory via the config hook, so OpenCode discovers all wukong-code skills without symlinks or manual config.

Tool Mapping

Skills speak in actions rather than naming any one runtime's tools. On OpenCode these resolve to:

  • "Create a todo" / "mark complete in todo list" → todowrite
  • Subagent (general-purpose): template → OpenCode's task tool with subagent_type: "general" (or "explore" for codebase exploration)
  • "Invoke a skill" → OpenCode's native skill tool
  • "Read a file" → read
  • "Create a file" / "edit a file" / "delete a file" → apply_patch
  • "Run a shell command" → bash
  • "Search file contents" / "find files by name" → grep, glob
  • "Fetch a URL" → webfetch

(Verified against the installed OpenCode CLI's tool inventory.)

Troubleshooting

Plugin not loading

  1. Check OpenCode logs: opencode run --print-logs "hello" 2>&1 | grep -i wukong-code
  2. Verify the plugin line in your opencode.json is correct
  3. Make sure you're running a recent version of OpenCode

Windows install issues

Some Windows OpenCode builds have upstream installer issues with git-backed plugin specs, including cache paths for git+https URLs and Bun not finding git.exe even when it works in a normal terminal. If OpenCode cannot install the plugin, try installing with system npm and pointing OpenCode at the local package:

npm install wukong-code@git+https://github.com/wukongnotnull/wukong-code.git --prefix "$HOME\.config\opencode"

Then use the installed package path in opencode.json:

{
  "plugin": ["~/.config/opencode/node_modules/wukong-code"]
}

Skills not found

  1. Use OpenCode's skill tool to list available skills
  2. Check that the plugin is loading (see above)
  3. Each skill needs a SKILL.md file with valid YAML frontmatter

Bootstrap not appearing

  1. Check OpenCode version supports experimental.chat.messages.transform hook
  2. Restart OpenCode after config changes

Getting Help