OpenCode Integration

Table of contents

• Overview
• Quick Start
  • 1. Install the FORGE Skill
  • 2. Configure the MCP Server (Optional)
  • 3. Project Instructions
• Compatibility Matrix
• FORGE Agents as OpenCode Agents
  • Phase-Agent Mapping
• Phase Guard: Replacing Hooks
  • Option A: Permission-Based Guards
  • Option B: Phase-Specific Primary Agents
  • Option C: Methodology Discipline
• Command Safety
• Skill-Only Setup (No MCP)
• Full Configuration Example
• Key Differences from Claude Code
• Disabling Claude Code Compatibility
• OpenCode Advantages for FORGE

Overview

FORGE works on OpenCode with minimal configuration. OpenCode reads CLAUDE.md and .claude/skills/ natively, so most of FORGE’s integration works out of the box.

This guide covers setup, what works immediately, and how to translate Claude Code-specific features like hooks and agent invocation into OpenCode equivalents.

Quick Start

1. Install the FORGE Skill

OpenCode reads .claude/skills/ natively. Install the skill locally in your project or globally:

# Option A: Local install (per-project)
cp -r forge-skill/.claude/skills/forge/ .claude/skills/forge/

# Option B: Global install (shared across projects)
ln -s /path/to/forge-skill/.claude/skills/forge ~/.claude/skills/forge

# OpenCode also searches these paths:
# .opencode/skills/forge/SKILL.md
# .agents/skills/forge/SKILL.md

The skill’s tool commands automatically resolve the install location at runtime — local project installs take priority over global installs.

2. Configure the MCP Server (Optional)

The MCP server (scottfeltham/forge-mcp) is in maintenance mode — fixes only, no new capability. Skip it unless you need MCP tool calls; see Choosing an implementation. If using it, add it to opencode.json in your project root:

{
  "mcp": {
    "forge": {
      "type": "local",
      "command": ["node", "/path/to/forge-mcp/server.js"],
      "timeout": 10000
    }
  }
}

OpenCode MCP tool names use a single underscore separator (forge_forge_new_cycle) vs Claude Code’s double underscore (mcp__forge__forge_new_cycle).

3. Project Instructions

OpenCode reads CLAUDE.md as a fallback. No changes needed if you already have one:

# Option A: Keep using CLAUDE.md (works as-is)
# Option B: Copy to AGENTS.md for OpenCode-native naming
cp CLAUDE.md AGENTS.md

You can also reference multiple instruction files in opencode.json:

{
  "instructions": [
    "CLAUDE.md",
    "rules/rules.md"
  ]
}

Compatibility Matrix

FORGE Agents as OpenCode Agents

OpenCode has a built-in multi-agent system. Instead of invoking FORGE agents through the MCP tool (forge_invoke_agent), you can define them as native OpenCode agents with per-agent model selection and tool restrictions.

Add to opencode.json:

{
  "agent": {
    "forge-architect": {
      "description": "C4 architecture, interfaces, dependency mapping",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are the Architect Agent for FORGE. Design system architecture using C4 diagrams, map dependencies, define interfaces. No implementation code.",
      "tools": { "write": true, "edit": true, "bash": false }
    },
    "forge-developer": {
      "description": "TDD implementation (RED-GREEN-REFACTOR)",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are the Developer Agent. Follow strict TDD: RED-GREEN-REFACTOR. One task per session. 80% minimum coverage.",
      "tools": { "write": true, "edit": true, "bash": true }
    },
    "forge-tester": {
      "description": "Acceptance criteria, edge cases, test execution",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are the Tester Agent. Write Given-When-Then criteria, enumerate edge cases, verify against acceptance criteria.",
      "tools": { "write": true, "edit": true, "bash": true }
    },
    "forge-security": {
      "description": "Threat modeling, security constraints, adversarial review",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are the Security Agent. Threat modeling, OWASP checks, adversarial review. Check for injection, auth bypasses, data exposure.",
      "tools": { "edit": false, "write": true, "bash": true }
    },
    "forge-reviewer": {
      "description": "Code quality, criteria compliance",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are the Code Reviewer Agent. Review for quality, acceptance criteria adherence, and best practices. Provide specific, actionable feedback.",
      "tools": { "write": false, "edit": false, "bash": true }
    }
  }
}

Invoke agents in OpenCode with @forge-architect, @forge-developer, etc.

Phase-Agent Mapping

Phase Guard: Replacing Hooks

Claude Code uses a PreToolUse hook (forge-phase-guard.sh) to block code writes during Focus, Orchestrate, and Refine phases. OpenCode does not have lifecycle hooks. There are three alternatives.

Option A: Permission-Based Guards

Use OpenCode’s permission system to gate code edits with an approval prompt:

{
  "permission": {
    "edit": {
      "docs/**": "allow",
      ".forge/**": "allow",
      "*test*": "allow",
      "*spec*": "allow",
      "*.md": "allow",
      "src/**": "ask",
      "lib/**": "ask"
    },
    "bash": {
      "git *": "allow",
      "npm test *": "allow",
      "uv run *": "allow",
      "rm -rf *": "deny",
      "git push --force *": "deny"
    }
  }
}

With "ask", OpenCode prompts before each code edit - serving as a manual gate during planning phases.

Option B: Phase-Specific Primary Agents

Define separate primary agents for planning and building:

{
  "agent": {
    "forge-plan": {
      "description": "FORGE planning mode (Focus/Orchestrate/Refine)",
      "mode": "primary",
      "tools": { "edit": false, "write": false, "bash": false },
      "prompt": "You are in FORGE planning mode. Write documentation and specifications to docs/ only. Do NOT write implementation code."
    },
    "forge-build": {
      "description": "FORGE build mode (Generate/Evaluate)",
      "mode": "primary",
      "tools": { "edit": true, "write": true, "bash": true },
      "prompt": "You are in FORGE build mode. Follow TDD: write failing tests first, then implement, then refactor."
    }
  }
}

Switch between agents with Tab in OpenCode’s TUI when advancing phases.

Option C: Methodology Discipline

The simplest approach: trust the FORGE methodology and instructions in CLAUDE.md/AGENTS.md. The phase rules are documented, and the AI follows them. This is how the skill-based approach works in Claude Code without hooks - clear instructions rather than enforcement.

Command Safety

OpenCode’s permission system provides built-in command safety that supplements FORGE’s command-safety.js:

{
  "permission": {
    "bash": {
      "rm -rf *": "deny",
      "git push --force *": "deny",
      "git reset --hard *": "deny",
      "chmod 777 *": "deny",
      "git clean *": "deny"
    }
  }
}

This stacks with the MCP server’s command safety checks if you’re using forge-mcp.

Skill-Only Setup (No MCP)

The simplest integration - just the FORGE skill with Python tools:

1. Install the skill locally or globally (see Quick Start above)
2. OpenCode discovers and loads the skill automatically
3. Tool commands resolve the install path at runtime

# Local install layout
your-project/
  .claude/skills/forge/     # OpenCode reads this
    SKILL.md
    tools/
      forge_init.py
      forge_cycle.py
      forge_phase.py
      forge_status.py
      forge_learn.py
  CLAUDE.md                  # OpenCode reads this as fallback

# Global install layout
~/.claude/skills/forge/     # Shared across all projects
  SKILL.md
  tools/
    forge_init.py
    ...

No opencode.json needed for this approach.

Full Configuration Example

A complete opencode.json using FORGE with MCP and native agents:

{
  "instructions": ["CLAUDE.md"],
  "mcp": {
    "forge": {
      "type": "local",
      "command": ["node", "./forge-mcp/server.js"],
      "timeout": 10000
    }
  },
  "agent": {
    "forge-architect": {
      "description": "Architecture, C4 diagrams, interfaces",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are the FORGE Architect Agent. Design system architecture using C4 diagrams, map dependencies, define interfaces. No implementation code.",
      "tools": { "edit": true, "write": true, "bash": false }
    },
    "forge-developer": {
      "description": "TDD implementation",
      "mode": "subagent",
      "prompt": "You are the FORGE Developer Agent. Follow strict TDD: RED-GREEN-REFACTOR. One task per session.",
      "tools": { "edit": true, "write": true, "bash": true }
    },
    "forge-tester": {
      "description": "Testing and verification",
      "mode": "subagent",
      "prompt": "You are the FORGE Tester Agent. Write Given-When-Then criteria, enumerate edge cases, verify against acceptance criteria.",
      "tools": { "edit": true, "write": true, "bash": true }
    },
    "forge-security": {
      "description": "Security review and threat modeling",
      "mode": "subagent",
      "prompt": "You are the FORGE Security Agent. Threat modeling, OWASP checks, adversarial review.",
      "tools": { "edit": false, "write": true, "bash": true }
    }
  },
  "permission": {
    "bash": {
      "git status *": "allow",
      "git diff *": "allow",
      "git add *": "allow",
      "git commit *": "allow",
      "npm test *": "allow",
      "uv run *": "allow",
      "rm -rf *": "deny",
      "git push --force *": "deny",
      "git reset --hard *": "deny",
      "chmod 777 *": "deny"
    }
  }
}

Key Differences from Claude Code

Disabling Claude Code Compatibility

If you’ve fully migrated to OpenCode-native paths and want to stop reading Claude Code files:

OPENCODE_DISABLE_CLAUDE_CODE=1 opencode

This stops OpenCode from reading CLAUDE.md and .claude/skills/. Only use this after migrating to AGENTS.md and .opencode/skills/.

OpenCode Advantages for FORGE

OpenCode brings features that enhance FORGE workflows:

• Multi-session: Run architect and developer agents in parallel sessions on the same project
• Granular permissions: allow/ask/deny with glob patterns provides finer control than Claude Code’s hooks
• Native agent system: FORGE agents become first-class citizens instead of MCP tool invocations
• Model flexibility: 75+ LLM providers, including local models via Ollama
• Session sharing: Share FORGE cycle progress with team members via links