Skip to content

README.opencode.md

Latest commit

 

History

History
163 lines (109 loc) · 4.53 KB

README.opencode.md

File metadata and controls

163 lines (109 loc) · 4.53 KB
Raw

Augment for OpenCode

Complete guide for using Augment with OpenCode.ai.

Installation

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

{
  "plugin": ["augment@git+https://github.com/fhmio/augment.git"]
}

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

Verify by asking: "Tell me about your augment skills"

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

Migrating from the old symlink-based install

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

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

# Optionally remove the cloned repo
rm -rf ~/.config/opencode/superpowers ~/.config/opencode/augment

# Remove skills.paths from opencode.json if you added one for augment

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 > Augment skills

Updating

OpenCode installs Augment 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 Augment 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": ["augment@git+https://github.com/fhmio/augment.git#v0.1.0"]
}

How It Works

The plugin does two things:

  1. Injects bootstrap context via the experimental.chat.messages.transform hook, loading the using-augment bootstrap and adding augment awareness to every conversation.
  2. Registers the skills directory via the config hook, so OpenCode discovers all augment 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 augment
  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 augment@git+https://github.com/fhmio/augment.git --prefix "$HOME\.config\opencode"

Then use the installed package path in opencode.json:

{
  "plugin": ["~/.config/opencode/node_modules/augment"]
}

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