> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/opencode-ai/opencode/llms.txt
> Use this file to discover all available pages before exploring further.
# 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:
Main interactive agent for coding tasks, file editing, and complex operations
Background agent for file search, grep operations, and code analysis
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
```json theme={null}
{
"agents": {
"coder": {
"model": "claude-3.7-sonnet",
"maxTokens": 5000,
"reasoningEffort": "medium"
}
}
}
```
### Properties
Model ID to use for the coder agent. See [provider configuration](/reference/provider-config) 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
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)
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](/reference/provider-config) 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)
```text theme={null}
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
```json theme={null}
{
"agents": {
"task": {
"model": "gpt-4.1-mini",
"maxTokens": 5000
}
}
}
```
### Properties
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
Maximum tokens for task agent responses.
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:
```text theme={null}
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
```json theme={null}
{
"agents": {
"title": {
"model": "gpt-4.1-mini"
}
}
}
```
### Properties
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
```text theme={null}
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
```json Best overall theme={null}
{
"agents": {
"coder": {"model": "claude-4-sonnet"},
"task": {"model": "claude-3.5-haiku"},
"title": {"model": "claude-3.5-haiku"}
}
}
```
```json With reasoning theme={null}
{
"agents": {
"coder": {
"model": "claude-3.7-sonnet",
"reasoningEffort": "medium"
},
"task": {"model": "gpt-4.1-mini"},
"title": {"model": "gpt-4.1-mini"}
}
}
```
### For cost
```json Free (GitHub Copilot) theme={null}
{
"agents": {
"coder": {"model": "copilot.claude-3.7-sonnet"},
"task": {"model": "copilot.gpt-4o-mini"},
"title": {"model": "copilot.gpt-4o-mini"}
}
}
```
```json Low cost theme={null}
{
"agents": {
"coder": {"model": "gemini-2.5-flash"},
"task": {"model": "gemini-2.5-flash"},
"title": {"model": "gemini-2.5-flash"}
}
}
```
### For speed
```json Fast inference theme={null}
{
"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
```json Large context theme={null}
{
"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:
```json theme={null}
{
"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:
```json theme={null}
{
"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:
```json theme={null}
{
"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:
```bash theme={null}
# 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:
```bash theme={null}
# 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.