Customizing OpenCode with Specialized Subagents

March 2, 2026

One of the most powerful features of OpenCode is its extensibility through custom subagents. While the default setup works well for general tasks, configuring specialized agents for specific workflows can dramatically improve your development experience.

In this post, I'll walk through my current OpenCode configuration, which uses a primary coding agent and two specialized subagents: one for research and another for debugging. This setup helps me stay focused by ensuring each agent has a clear role and appropriate tool access.

The Architecture: Primary Agent + Subagents

My configuration follows a hub-and-spoke model with three distinct agents, each optimized for their specific responsibilities:

Coder (Primary): The main agent for implementation and refactoring
Researcher (Subagent): Focused on analysis and information gathering
Debugger (Subagent): Specialized in fixing errors and running tests

The Configuration File

The entire setup lives in ~/.config/opencode/opencode.json. Here's the complete configuration:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "zai-anthropic": {
      "npm": "@ai-sdk/anthropic",
      "options": {
        "baseURL": "https://api.z.ai/api/anthropic/v1",
        "apiKey": "YOUR_API_KEY"
      },
      "models": {
        "glm-5": {
          "name": "glm-5"
        }
      }
    }
  },
  "model": "zai-anthropic/glm-5",
  "agent": {
    "coder": {
      "description": "Primary coding agent using GLM-5",
      "mode": "primary",
      "model": "zai-anthropic/glm-5",
      "temperature": 0.2,
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    },
    "researcher": {
      "description": "Research agent for analysis",
      "mode": "subagent",
      "model": "zai-anthropic/glm-5",
      "temperature": 0.8,
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
    },
    "debugger": {
      "description": "Debug agent to fix errors",
      "mode": "subagent",
      "model": "zai-anthropic/glm-5",
      "temperature": 0.3,
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    }
  }
}

Understanding the Provider Setup

The configuration starts by defining a custom provider that uses GLM-5 through Z.ai's API. This provider configuration allows OpenCode to connect to alternative model providers while maintaining compatibility with the standard AI SDK interface.

Provider Flexibility:

OpenCode supports multiple providers out of the box, but the custom provider setup lets you use any OpenAI-compatible API endpoint.

The Primary Coder Agent

The coder agent serves as the primary interface for day-to-day development work. Its configuration emphasizes precision and reliability:

Temperature: 0.2 - Low temperature ensures consistent, deterministic outputs for code generation
Full tool access - Can write, edit, and run bash commands to handle any coding task
Primary mode - Acts as the default agent for most interactions

This low temperature setting is crucial for coding tasks where you want predictable behavior rather than creative exploration.

The Researcher Subagent

The researcher agent is designed for exploration and analysis without the risk of unintended file modifications:

Temperature: 0.8 - Higher temperature encourages creative thinking and broader exploration
Read-only tools - Cannot write, edit, or run bash commands, ensuring safe exploration
Subagent mode - Can be invoked by the primary agent when research is needed

This separation is particularly valuable when investigating unfamiliar codebases or exploring potential solutions. The researcher can freely analyze without the risk of accidentally modifying files.

The Debugger Subagent

The debugger agent strikes a balance between precision and problem-solving flexibility:

Temperature: 0.3 - Slightly higher than the coder to allow for creative problem-solving while maintaining reliability
Full tool access - Needs to modify files and run tests to fix issues
Subagent mode - Can be invoked when errors need focused attention

The moderate temperature setting allows the debugger to explore potential solutions while still producing reliable fixes.

Why Temperature Settings Matter

The different temperature values across agents aren't arbitrary. They reflect the different needs of each task:

Coding (0.2): Code needs to be precise and syntactically correct. Low temperature minimizes hallucinations and syntax errors.
Research (0.8): Research benefits from exploring multiple perspectives and making unexpected connections. Higher temperature enables creative thinking.
Debugging (0.3): Debugging needs some creativity to identify root causes but must still produce working code. Moderate temperature balances both needs.

Tool Access and Security

One of the most important aspects of this configuration is the careful control over tool access:

Security Consideration:

The researcher agent's read-only access prevents accidental or unwanted modifications during exploratory tasks.

This is particularly useful when:

Asking an agent to analyze production code without risk
Exploring unfamiliar codebases before making changes
Reviewing security-sensitive code paths

Practical Usage Patterns

In practice, this configuration creates natural workflow boundaries:

Starting a feature: Use the researcher to understand the existing code and identify integration points
Implementation: Switch to the coder for the actual development work
When errors occur: Invoke the debugger to investigate and fix issues
Code review: Use the researcher to analyze changes without risk of modification

Benefits of This Approach

After using this configuration for several months, I've noticed several improvements in my workflow:

Clearer intent: Each agent has a specific purpose, making interactions more focused
Better outputs: Temperature tuning for each task type produces more appropriate responses
Safer exploration: The researcher can freely analyze code without risk of modification
Improved debugging: Dedicated debugger agent handles errors more systematically

Extending the Configuration

This setup is just a starting point. You could extend it with additional specialized agents:

Documentation agent: Low temperature, read-only access for generating documentation
Testing agent: Moderate temperature, full tool access for writing and running tests
Security reviewer: High temperature, read-only access for security analysis

Getting Started

To implement this configuration:

Create or edit ~/.config/opencode/opencode.json
Copy the configuration structure above
Replace the API key with your own credentials
Adjust temperature values based on your preferences
Test each agent with appropriate tasks

Have you customized your OpenCode setup with specialized agents? I'd love to hear about your configurations and what works best for your workflow. Reach out at matt@emmons.club.