Agent configuration

Configure different AI agents for specialized tasks in OpenCode

OpenCode uses specialized AI agents for different tasks. Each agent can be configured with a different model, token limit, and reasoning parameters to optimize for its specific use case.

Agent types

OpenCode has three built-in agents:

Coder

Main interactive agent for coding tasks, file editing, and complex operations

Task

Background agent for file search, grep operations, and code analysis

Title

Specialized agent for generating concise session titles

Coder agent

The coder agent is the primary agent you interact with during coding sessions. It handles all user interactions, code editing, file operations, and complex reasoning tasks.

Configuration

{
  "agents": {
    "coder": {
      "model": "claude-3.7-sonnet",
      "maxTokens": 5000,
      "reasoningEffort": "medium"
    }
  }
}

Properties

model · string · required

Model ID to use for the coder agent. See provider configuration for available options.

Recommended models:

• claude-4-sonnet - Best overall coding performance
• claude-3.7-sonnet - Excellent coding with extended thinking
• gpt-4.1 - Strong reasoning and large context
• copilot.gpt-4o - Free with GitHub Copilot subscription

maxTokens · integer · default: "5000"

Maximum tokens for agent responses. Higher values allow longer responses but increase cost.

Recommendations:

• 5000-8000 - Standard coding tasks
• 10000-20000 - Complex multi-file changes
• 30000-50000 - Large-scale refactoring (reasoning models)

reasoningEffort · string

Reasoning effort level for models that support extended thinking (OpenAI o-series, Anthropic extended thinking, etc.).

Options:

• low - Faster responses, less deep analysis
• medium - Balanced performance (recommended)
• high - Deepest analysis, slower responses

Only applicable to models with reasoning capabilities. See provider configuration for which models support reasoning.

Behavior

The coder agent is designed to:

• Be concise and direct (max 4 lines of text unless user requests detail)
• Use tools proactively to gather information before answering
• Follow existing code conventions and patterns
• Run linting and typechecking after making changes
• Avoid adding unnecessary comments unless requested
• Never commit changes unless explicitly asked

System prompt

The coder agent uses a comprehensive system prompt that includes:

• Instructions for tool usage and proactive behavior
• Code style guidelines (minimal comments, follow conventions)
• Task completion workflow (search → implement → verify)
• Environment information (working directory, platform, git status)
• LSP integration details (when configured)

View default system prompt excerpt

You are OpenCode, an interactive CLI tool that helps users with software 
engineering tasks. Use the instructions below and the tools available to 
you to assist the user.

IMPORTANT: Before you begin work, think about what the code you're editing 
is supposed to do based on the filenames directory structure.

# Tone and style
You should be concise, direct, and to the point. Remember that your output 
will be displayed on a command line interface.

# Following conventions
When making changes to files, first understand the file's code conventions. 
Mimic code style, use existing libraries and utilities, and follow existing 
patterns.

- NEVER assume that a given library is available, even if it is well known.
- When you create a new component, first look at existing components to see 
  how they're written.
- Always follow security best practices. Never introduce code that exposes 
  or logs secrets and keys.

Task agent

The task agent handles background operations and specialized tasks. It’s optimized for quick, focused operations like file search, grep, and code analysis.

Configuration

{
  "agents": {
    "task": {
      "model": "gpt-4.1-mini",
      "maxTokens": 5000
    }
  }
}

Properties

model · string · required

Model ID to use for the task agent.

Recommended models:

• gpt-4.1-mini - Fast and cost-effective
• claude-3.5-haiku - Fast Claude model
• gemini-2.5-flash - Fast with large context
• copilot.gpt-4o-mini - Free with GitHub Copilot

maxTokens · integer · default: "5000"

Maximum tokens for task agent responses.

reasoningEffort · string

Reasoning effort level (same options as coder agent).

Behavior

The task agent is designed to:

• Provide concise, direct answers without elaboration
• Use absolute file paths (never relative paths)
• Share relevant file names and code snippets
• Focus on the specific query without tangential information

Use cases

• File search: Finding files by name or pattern
• Code search: Searching for specific code patterns with grep
• Analysis: Analyzing code structure and dependencies
• Quick queries: Answering specific questions about the codebase

System prompt

The task agent uses a simplified system prompt:

You are an agent for OpenCode. Given the user's prompt, you should use the 
tools available to you to answer the user's question.

Notes:
1. You should be concise, direct, and to the point. Answer the user's 
   question directly, without elaboration.
2. When relevant, share file names and code snippets relevant to the query
3. Any file paths you return MUST be absolute. DO NOT use relative paths.

Title agent

The title agent generates concise session titles based on the first user message. This helps organize and identify sessions in the session history.

Configuration

{
  "agents": {
    "title": {
      "model": "gpt-4.1-mini"
    }
  }
}

Properties

model · string · required

Model ID to use for the title agent.

Recommended models:

• gpt-4.1-mini - Fast and cost-effective
• claude-3.5-haiku - Fast Claude model
• gemini-2.5-flash - Fast Gemini model
• copilot.gpt-4o-mini - Free with GitHub Copilot

The maxTokens parameter is automatically set to 80 for the title agent and cannot be configured. The reasoningEffort parameter is not used.

Behavior

The title agent is designed to:

• Generate titles under 50 characters
• Create one-line summaries without quotes or colons
• Capture the essence of the user’s query
• Return only the title text (no additional commentary)

System prompt

You will generate a short title based on the first message a user begins 
a conversation with:
- Ensure it is not more than 50 characters long
- The title should be a summary of the user's message
- It should be one line long
- Do not use quotes or colons
- The entire text you return will be used as the title
- Never return anything that is more than one sentence long

Model selection guide

Choose models based on your priorities:

For performance

Best overall

{
  "agents": {
    "coder": {"model": "claude-4-sonnet"},
    "task": {"model": "claude-3.5-haiku"},
    "title": {"model": "claude-3.5-haiku"}
  }
}

For cost

Free (GitHub Copilot)

{
  "agents": {
    "coder": {"model": "copilot.claude-3.7-sonnet"},
    "task": {"model": "copilot.gpt-4o-mini"},
    "title": {"model": "copilot.gpt-4o-mini"}
  }
}

For speed

Fast inference

{
  "agents": {
    "coder": {"model": "llama-3.3-70b-versatile"},
    "task": {"model": "llama-3.3-70b-versatile"},
    "title": {"model": "llama-3.3-70b-versatile"}
  }
}

For context window

Large context

{
  "agents": {
    "coder": {
      "model": "gpt-4.1",
      "maxTokens": 20000
    },
    "task": {"model": "gemini-2.5-flash"},
    "title": {"model": "gpt-4.1-mini"}
  }
}

Validation

OpenCode automatically validates your agent configuration:

• Model existence: Checks if the specified model is supported
• Provider availability: Verifies the provider is configured with valid credentials
• Token limits: Ensures maxTokens doesn’t exceed half the context window
• Reasoning support: Validates reasoningEffort is only used with compatible models
• Fallback: Automatically uses default models if configuration is invalid

If a configured model is unavailable, OpenCode will warn you and fall back to a default model based on your available providers. Check logs if you see unexpected model usage.

Advanced configuration

Using different providers for different agents

Mix providers to optimize for cost and performance:

{
  "agents": {
    "coder": {
      "model": "claude-3.7-sonnet",
      "maxTokens": 8000,
      "reasoningEffort": "medium"
    },
    "task": {
      "model": "openrouter.gemini-2.5-flash",
      "maxTokens": 5000
    },
    "title": {
      "model": "copilot.gpt-4o-mini"
    }
  }
}

High-performance reasoning setup

For maximum reasoning capability:

{
  "agents": {
    "coder": {
      "model": "o1",
      "maxTokens": 50000,
      "reasoningEffort": "high"
    },
    "task": {
      "model": "o1-mini",
      "maxTokens": 20000,
      "reasoningEffort": "medium"
    },
    "title": {
      "model": "gpt-4.1-mini"
    }
  }
}

Budget-conscious configuration

Minimize costs while maintaining quality:

{
  "agents": {
    "coder": {
      "model": "gemini-2.5-flash",
      "maxTokens": 5000
    },
    "task": {
      "model": "gemini-2.0-flash-lite",
      "maxTokens": 3000
    },
    "title": {
      "model": "gemini-2.0-flash-lite"
    }
  }
}

Testing your configuration

After modifying your agent configuration, test it:

# Start OpenCode and check which models are loaded
opencode

# Use Ctrl+P to see active models
# Or check the status bar in the UI

OpenCode displays active models and token usage in the interface.

Environment-specific configuration

Use local configuration files to customize agents per project:

# Global config: ~/.opencode.json
{
  "agents": {
    "coder": {"model": "claude-3.7-sonnet"}
  }
}

# Project config: ./my-project/.opencode.json
{
  "agents": {
    "coder": {
      "model": "gpt-4.1",
      "maxTokens": 20000
    }
  }
}

Local configuration overrides global settings for that directory.