Skip to content

README.opencode.md

Latest commit

 

History

History
342 lines (225 loc) · 10.5 KB

README.opencode.md

File metadata and controls

342 lines (225 loc) · 10.5 KB

Autonomous Dev Kit for OpenCode

Complete guide for using Autonomous Dev Kit with OpenCode.ai.

Quick Install

Tell OpenCode:

Clone https://github.com/GoCodeAlone/autonomous-dev-kit to ~/.config/opencode/autodev, then create directory ~/.config/opencode/plugins, then symlink ~/.config/opencode/autodev/.opencode/plugins/autodev.js to ~/.config/opencode/plugins/autodev.js, then symlink ~/.config/opencode/autodev/skills to ~/.config/opencode/skills/autodev, then restart opencode.

Manual Installation

Prerequisites

macOS / Linux

# 1. Install Autonomous Dev Kit (or update existing)
if [ -d ~/.config/opencode/autodev ]; then
  cd ~/.config/opencode/autodev && git pull
else
  git clone https://github.com/GoCodeAlone/autonomous-dev-kit.git ~/.config/opencode/autodev
fi

# 2. Create directories
mkdir -p ~/.config/opencode/plugins ~/.config/opencode/skills

# 3. Remove old symlinks/directories if they exist
rm -f ~/.config/opencode/plugins/autodev.js
rm -rf ~/.config/opencode/skills/autodev

# 4. Create symlinks
ln -s ~/.config/opencode/autodev/.opencode/plugins/autodev.js ~/.config/opencode/plugins/autodev.js
ln -s ~/.config/opencode/autodev/skills ~/.config/opencode/skills/autodev

# 5. Restart OpenCode

Verify Installation

ls -l ~/.config/opencode/plugins/autodev.js
ls -l ~/.config/opencode/skills/autodev

Both should show symlinks pointing to the autodev directory.

Windows

Prerequisites:

  • Git installed
  • Either Developer Mode enabled OR Administrator privileges
    • Windows 10: Settings → Update & Security → For developers
    • Windows 11: Settings → System → For developers

Pick your shell below: Command Prompt | PowerShell | Git Bash

Command Prompt

Run as Administrator, or with Developer Mode enabled:

:: 1. Install Autonomous Dev Kit
git clone https://github.com/GoCodeAlone/autonomous-dev-kit.git "%USERPROFILE%\.config\opencode\autodev"

:: 2. Create directories
mkdir "%USERPROFILE%\.config\opencode\plugins" 2>nul
mkdir "%USERPROFILE%\.config\opencode\skills" 2>nul

:: 3. Remove existing links (safe for reinstalls)
del "%USERPROFILE%\.config\opencode\plugins\autodev.js" 2>nul
rmdir "%USERPROFILE%\.config\opencode\skills\autodev" 2>nul

:: 4. Create plugin symlink (requires Developer Mode or Admin)
mklink "%USERPROFILE%\.config\opencode\plugins\autodev.js" "%USERPROFILE%\.config\opencode\autodev\.opencode\plugins\autodev.js"

:: 5. Create skills junction (works without special privileges)
mklink /J "%USERPROFILE%\.config\opencode\skills\autodev" "%USERPROFILE%\.config\opencode\autodev\skills"

:: 6. Restart OpenCode

PowerShell

Run as Administrator, or with Developer Mode enabled:

# 1. Install Autonomous Dev Kit
git clone https://github.com/GoCodeAlone/autonomous-dev-kit.git "$env:USERPROFILE\.config\opencode\autodev"

# 2. Create directories
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.config\opencode\plugins"
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.config\opencode\skills"

# 3. Remove existing links (safe for reinstalls)
Remove-Item "$env:USERPROFILE\.config\opencode\plugins\autodev.js" -Force -ErrorAction SilentlyContinue
Remove-Item "$env:USERPROFILE\.config\opencode\skills\autodev" -Force -ErrorAction SilentlyContinue

# 4. Create plugin symlink (requires Developer Mode or Admin)
New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.config\opencode\plugins\autodev.js" -Target "$env:USERPROFILE\.config\opencode\autodev\.opencode\plugins\autodev.js"

# 5. Create skills junction (works without special privileges)
New-Item -ItemType Junction -Path "$env:USERPROFILE\.config\opencode\skills\autodev" -Target "$env:USERPROFILE\.config\opencode\autodev\skills"

# 6. Restart OpenCode

Git Bash

Note: Git Bash's native ln command copies files instead of creating symlinks. Use cmd //c mklink instead (the //c is Git Bash syntax for /c).

# 1. Install Autonomous Dev Kit
git clone https://github.com/GoCodeAlone/autonomous-dev-kit.git ~/.config/opencode/autodev

# 2. Create directories
mkdir -p ~/.config/opencode/plugins ~/.config/opencode/skills

# 3. Remove existing links (safe for reinstalls)
rm -f ~/.config/opencode/plugins/autodev.js 2>/dev/null
rm -rf ~/.config/opencode/skills/autodev 2>/dev/null

# 4. Create plugin symlink (requires Developer Mode or Admin)
cmd //c "mklink \"$(cygpath -w ~/.config/opencode/plugins/autodev.js)\" \"$(cygpath -w ~/.config/opencode/autodev/.opencode/plugins/autodev.js)\""

# 5. Create skills junction (works without special privileges)
cmd //c "mklink /J \"$(cygpath -w ~/.config/opencode/skills/autodev)\" \"$(cygpath -w ~/.config/opencode/autodev/skills)\""

# 6. Restart OpenCode

WSL Users

If running OpenCode inside WSL, use the macOS / Linux instructions instead.

Verify Installation

Command Prompt:

dir /AL "%USERPROFILE%\.config\opencode\plugins"
dir /AL "%USERPROFILE%\.config\opencode\skills"

PowerShell:

Get-ChildItem "$env:USERPROFILE\.config\opencode\plugins" | Where-Object { $_.LinkType }
Get-ChildItem "$env:USERPROFILE\.config\opencode\skills" | Where-Object { $_.LinkType }

Look for <SYMLINK> or <JUNCTION> in the output.

Troubleshooting Windows

"You do not have sufficient privilege" error:

  • Enable Developer Mode in Windows Settings, OR
  • Right-click your terminal → "Run as Administrator"

"Cannot create a file when that file already exists":

  • Run the removal commands (step 3) first, then retry

Symlinks not working after git clone:

  • Run git config --global core.symlinks true and re-clone

Usage

Finding Skills

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

use skill tool to list skills

Loading a Skill

Use OpenCode's native skill tool to load a specific skill:

use skill tool to load autodev/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 your OpenCode project:

# In your OpenCode project
mkdir -p .opencode/skills/my-project-skill

Create .opencode/skills/my-project-skill/SKILL.md:

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

# My Project Skill

[Your skill content here]

Skill Locations

OpenCode discovers skills from these locations:

  1. Project skills (.opencode/skills/) - Highest priority
  2. Personal skills (~/.config/opencode/skills/)
  3. Autonomous Dev Kit skills (~/.config/opencode/skills/autodev/) - via symlink

Features

Automatic Context Injection

The plugin automatically injects autodev context via the experimental.chat.system.transform hook. This adds the "using-autodev" skill content to the system prompt on every request.

Native Skills Integration

Autonomous Dev Kit uses OpenCode's native skill tool for skill discovery and loading. Skills are symlinked into ~/.config/opencode/skills/autodev/ so they appear alongside your personal and project skills.

Tool Mapping

Skills written for Claude Code are automatically adapted for OpenCode. The bootstrap provides mapping instructions:

  • TodoWrite → update_plan
  • Task with subagents → OpenCode's @mention system
  • Skill tool → OpenCode's native skill tool
  • File operations → Native OpenCode tools

Architecture

Plugin Structure

Location: ~/.config/opencode/autodev/.opencode/plugins/autodev.js

Components:

  • experimental.chat.system.transform hook for bootstrap injection
  • Reads and injects the "using-autodev" skill content

Skills

Location: ~/.config/opencode/skills/autodev/ (symlink to ~/.config/opencode/autodev/skills/)

Skills are discovered by OpenCode's native skill system. Each skill has a SKILL.md file with YAML frontmatter.

Updating

cd ~/.config/opencode/autodev
git pull

Restart OpenCode to load the updates.

Troubleshooting

Plugin not loading

  1. Check plugin exists: ls ~/.config/opencode/autodev/.opencode/plugins/autodev.js
  2. Check symlink/junction: ls -l ~/.config/opencode/plugins/ (macOS/Linux) or dir /AL %USERPROFILE%\.config\opencode\plugins (Windows)
  3. Check OpenCode logs: opencode run "test" --print-logs --log-level DEBUG
  4. Look for plugin loading message in logs

Skills not found

  1. Verify skills symlink: ls -l ~/.config/opencode/skills/autodev (should point to autodev/skills/)
  2. Use OpenCode's skill tool to list available skills
  3. Check skill structure: each skill needs a SKILL.md file with valid frontmatter

Windows: Module not found error

If you see Cannot find module errors on Windows:

  • Cause: Git Bash ln -sf copies files instead of creating symlinks
  • Fix: Use mklink /J directory junctions instead (see Windows installation steps)

Bootstrap not appearing

  1. Verify using-autodev skill exists: ls ~/.config/opencode/autodev/skills/using-autodev/SKILL.md
  2. Check OpenCode version supports experimental.chat.system.transform hook
  3. Restart OpenCode after plugin changes

Cross-LLM Behavior

Autonomous Dev Kit skills use <host: claude-code> blocks to gate content that only applies to Claude Code (Agent Teams, specific tool names, etc.). On OpenCode, those blocks are skipped — the rest of the skill runs as-is.

To let skills detect that they are running on OpenCode, add a host declaration to your ~/.config/opencode/AGENTS.md:

Host: opencode

This single line enables host-conditional skill logic. See .opencode/INSTALL.md for the full declaration snippet.

Getting Help

Testing

Verify your installation:

# Check plugin loads
opencode run --print-logs "hello" 2>&1 | grep -i autodev

# Check skills are discoverable
opencode run "use skill tool to list all skills" 2>&1 | grep -i autodev

# Check bootstrap injection
opencode run "what autodev do you have?"

The agent should mention having autodev and be able to list skills from autodev/.