OpenCode¶

Terminal-based AI coding assistant. Config managed with stow across multiple packages.

Installation¶

cd ~/dotfiles
stow opencode  # Base config (permissions, MCP, skills, commands)
stow iron      # Work: GitHub Copilot models (requires subscription)
stow home      # Home: OpenCode Zen free models (no subscription needed)

Symlinks ~/.config/opencode/ to dotfiles. The iron and home packages overlay agent configs on the base opencode package.

Structure¶

opencode/.config/opencode/
├── opencode.jsonc     # Config (models, permissions, MCP)
├── skill/             # Reusable skills
└── command/           # Slash commands

iron/.config/opencode/agent/    # Work agents (GitHub Copilot)
home/.config/opencode/agent/    # Home agents (OpenCode Zen free)

Model Providers¶

GitHub Copilot (iron package)¶

For work environments with GitHub Copilot subscription. Premium models, no per-token cost.

OpenCode Zen (home package)¶

For personal environments without paid subscriptions. All models are free (cost: $0).

OpenCode Zen Models Reference¶

All available models via opencode/ provider (API: https://opencode.ai/zen/v1):

Note: Invalid model identifiers like glm-4.7-free do not exist in the OpenCode Zen catalog. Always use the format opencode/<model-id> with valid model IDs listed above.

Agents¶

Primary Agents (User-Facing)¶

Subagents (Delegated via Task)¶

opencode                            # Default agent
opencode --agent task-orchestrator  # Specific agent
# Tab to switch during session

Model Strategy¶

The model choice per agent follows this philosophy:

• Coding agents (builder, tester): Use code-optimized models with large context
• Speed agents (quick-fix): Use fast, lightweight models for focused work
• Reasoning agents (researcher, reviewer, ideation): Use models with strong reasoning/analysis
• Orchestration agents (task-orchestrator): Use reasoning models for coordination

Permissions¶

Defined in opencode.jsonc. Example:

permission:
  bash:
    "*": "allow"
    "rm -rf /*": "deny"
    "sudo *": "deny"
    "tofu apply*": "ask"
    "kubectl delete*": "ask"
    "git push*": "ask"
  edit:
    "**/*.env*": "ask"
    "**/*.key": "deny"

Permission Levels¶

Skills¶

Reusable knowledge modules loaded by agents:

Nexus Skills¶

The nexus-orchestrator and nexus-worker skills enable multi-agent task coordination via a local nexus server (port 7001).

nexus-orchestrator (for task-orchestrator agent): 1. Claim high-level issues (epics/features) 2. Explore scope with explore agent 3. Decompose into subtasks: nexus issue create --parent <id> --title "..." 4. Delegate subtasks to builder with NEXUS SUBTASK: <id> in prompt 5. Verify each subtask, then complete parent

nexus-worker (for builder/subagents): 1. Claim assigned subtask: nexus issue claim <id> 2. Implement focused changes 3. Complete when done: nexus issue update <id> --status completed

Key commands:

nexus status                                    # Check server/claims
nexus next --claim --format json               # Get next issue
nexus issue create --title "..." --parent <id> # Create subtask
nexus issue update <id> --status completed     # Complete issue
nexus issue renew <id>                         # Extend claim (20 min)

MCP Servers¶

Disabled by default. Enable per-project in opencode.jsonc:

{
  "mcp": {
    "steampipe": { "enabled": true },
    "PieGPT": { "enabled": true }
  }
}

Slash Commands¶

Tips¶

1. Use @quick-fix for small edits, @builder for complex work
2. Use @task-orchestrator for multi-step features requiring coordination
3. Check justfile first for project commands
4. Use git worktrees for parallel work
5. Prefer Steampipe for AWS resource queries
6. Load skills explicitly when needed (e.g., "load python-uv skill")
7. Use drawio skill for architecture diagrams (start container first: cd ~/dotfiles/ai && docker compose up -d)
8. Switch environments: stow -D iron && stow home (or vice versa) to swap agent configs

Customization¶

Add agents: Create .md files in agent/

Add skills: Create directories in skill/ with SKILL.md

Add commands: Create .md files in command/

See Also¶

• Copilot - GitHub Copilot (agent/skill parity for VS Code Copilot Chat)
• VS Code - VS Code setup