OpenCode Quick Start

OpenCode is an open-source terminal AI coding agent by Anomaly (opencode.ai). AIWG deploys skills and rules natively to OpenCode's discovery paths.

---

Install & Deploy

1. Install OpenCode

# macOS / Linux
brew install opencode

# npm
npm install -g opencode

# Or see https://opencode.ai/docs/ for all install options

2. Install AIWG

npm install -g aiwg

3. Deploy to your project

cd /path/to/your/project
aiwg use sdlc --provider opencode

4. Initialize config

Copy the AIWG config template to your project:

cp "$(aiwg runtime-info --aiwg-root)/agentic/code/frameworks/sdlc-complete/templates/opencode/opencode.json.aiwg-template" .opencode/opencode.json

Or create `.opencode/opencode.json` manually:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-6",
  "mcp": {
    "aiwg": {
      "type": "local",
      "command": ["npx", "aiwg", "mcp", "serve"]
    }
  },
  "instructions": [
    "AGENTS.md",
    ".aiwg/instructions.md",
    ".opencode/rule/*.md"
  ]
}

The `instructions` array is how OpenCode loads rules — the `.opencode/rule/.md` entry is required for AIWG rules to take effect. As of #1548, `aiwg use --provider opencode` wires this automatically: when it deploys rules it adds `.opencode/rule/.md` and `AGENTS.md` to `instructions[]`, creating `opencode.json` if absent and merging non-destructively (your existing keys and instruction entries are preserved and de-duplicated). The block above is shown for reference / manual setups; you no longer need to add the rule glob by hand.

5. You're ready. Run `opencode` in your project directory.

---

What Gets Created

.opencode/
├── skill/       # Skill definitions (natively discovered via SKILL.md)
└── rule/        # Context rules (loaded via instructions in opencode.json)

AGENTS.md        # Project context (auto-loaded by OpenCode)
.aiwg/           # SDLC artifacts

---

Capability Details

AIWG Artifact	Path	How OpenCode Uses It
Agent personas	Not deployed	OpenCode agents are config-only (`opencode.json` `agent` key)
Commands	Not deployed	Commands derive from skills automatically
Skills	`.opencode/skill/`	Natively discovered — `{skill,skills}/**/SKILL.md`
Rules	`.opencode/rule/`	Loaded via `instructions` array in `opencode.json`
Project context	`AGENTS.md`	Auto-loaded (same file as Claude Code)

---

Using Skills

Skills in `.opencode/skill/` are discovered when they contain a `SKILL.md` file. OpenCode loads them on demand when the agent recognizes a matching task.

Skills also serve as the source for OpenCode's command palette — you do not need separate command files.

---

Models

Configure via `.opencode/opencode.json`:

Anthropic (recommended for AIWG):

{
  "model": "anthropic/claude-sonnet-4-6",
  "small_model": "anthropic/claude-haiku-4-5-20251001"
}

Other supported providers: OpenAI, Gemini, Groq, OpenRouter, Bedrock, Azure, VertexAI, Ollama (via custom provider).

Run `opencode models` to list available models.

---

Agent Loop

aiwg ralph "Fix all tests" --completion "npm test passes" --provider opencode --model anthropic/claude-sonnet-4-6

See Al Guide for full documentation.

---

Troubleshooting

Rules not being applied? Verify `instructions` in `.opencode/opencode.json` includes `.opencode/rule/*.md`.

Skills not available? Confirm deployment:

ls .opencode/skill/

Redeploy if needed:

aiwg use sdlc --provider opencode --force

MCP not connecting? Test directly:

aiwg mcp serve

---

MCP Sidecar (Recommended for Full Access)

aiwg mcp install opencode

See the OpenCode MCP Sidecar Guide for complete setup.