OpenCode
Execute prompts via the OpenCode SDK. Supports OpenCode Zen models and 75+ LLM providers including Big Pickle (free stealth), GPT-5.2, Claude Sonnet 4.5, Gemini 3 Pro, and more.
import { OpenCode } from "smithers-orchestrator"
<OpenCode model="opencode/big-pickle">
Analyze this codebase and suggest improvements
</OpenCode>
Basic Usage
// Use Big Pickle (free stealth model)
<OpenCode model="opencode/big-pickle">
Analyze this codebase and suggest improvements
</OpenCode>
// Use GPT-5.2 via OpenCode Zen
<OpenCode model="opencode/gpt-5.2-codex" agent="coder">
Implement the feature described in the task
</OpenCode>
// Use Claude directly
<OpenCode model="anthropic/claude-sonnet-4-5">
Review this pull request
</OpenCode>
Props
Model Configuration
model
OpenCodeModel
default:"opencode default"
OpenCode model to use in format “provider/model”.<OpenCode model="opencode/big-pickle">Free stealth model</OpenCode>
<OpenCode model="opencode/gpt-5.2-codex">GPT-5.2 via Zen</OpenCode>
<OpenCode model="anthropic/claude-sonnet-4-5">Claude direct</OpenCode>
agent
'default' | 'planner' | 'coder' | string
Agent to use for this session. Corresponds to .opencode/agents/{name}.md.<OpenCode agent="coder">Implementation task</OpenCode>
<OpenCode agent="planner">Planning task</OpenCode>
Maximum number of agentic turns (tool use cycles).<OpenCode maxTurns={10}>Limited iteration task</OpenCode>
Maximum tokens for the response.<OpenCode maxTokens={4096}>Task with token limit</OpenCode>
Timeout in milliseconds.<OpenCode timeout={60000}>Task with 1 minute timeout</OpenCode>
System Prompt
Custom system prompt override.<OpenCode systemPrompt="You are a security expert. Focus on vulnerabilities.">
Review this code.
</OpenCode>
permissionMode
'auto' | 'ask' | 'deny'
default:"ask"
Permission handling for tool calls.
auto: auto-approve based on opencode.json permissionsask: prompt for permission (default)deny: deny all permission requests
<OpenCode permissionMode="auto">Auto-approve tools</OpenCode>
Tool configuration overrides. Map of tool name to enabled/disabled.<OpenCode toolConfig={{ bash: true, write: false }}>
Allow bash, disable write
</OpenCode>
Execution Configuration
Working directory for the session.<OpenCode cwd="/path/to/project">
Run in specific directory.
</OpenCode>
Continue from an existing session ID.<OpenCode resumeSession="session-abc123">Continue this session.</OpenCode>
Middleware applied to this OpenCode execution.
Provider middleware are prepended automatically.<OpenCode middleware={[loggingMiddleware, rateLimitMiddleware]}>
Task with middleware.
</OpenCode>
Number of tail log entries to display during execution.
Number of lines to show per tail log entry.
Server Configuration
hostname
string
default:"127.0.0.1"
OpenCode server hostname.
Server startup timeout in milliseconds.
Structured Output
Zod schema for structured output validation.const ResultSchema = z.object({
summary: z.string(),
issues: z.array(z.string()),
});
<OpenCode schema={ResultSchema}>
Return structured analysis.
</OpenCode>
Maximum retries for schema validation failures.
validate
(result: AgentResult) => boolean | Promise<boolean>
Custom validation function.<OpenCode validate={(result) => result.output.includes("DONE")}>
Must include completion marker.
</OpenCode>
Retry if validation fails.
Callbacks
onFinished
(result: AgentResult) => void
Called when agent finishes successfully.<OpenCode onFinished={(r) => console.log(r.output)}>Task</OpenCode>
Called when agent encounters an error.
onToolCall
(tool: string, input: any) => void
Called when agent makes a tool call.
onProgress
(message: string) => void
Called for progress updates.
Reporting
Enable database reporting for this agent.
Record stream events to the database when reporting is enabled.
Models
OpenCode supports 75+ LLM providers. Common models:
| Model | Description |
|---|
opencode/big-pickle | Free stealth model |
opencode/gpt-5.2 | GPT-5.2 via OpenCode Zen |
opencode/gpt-5.2-codex | GPT-5.2 Codex variant |
opencode/gpt-5.1-codex | GPT-5.1 Codex |
opencode/claude-sonnet-4-5 | Claude Sonnet 4.5 via Zen |
opencode/claude-opus-4-5 | Claude Opus 4.5 via Zen |
opencode/gemini-3-pro | Gemini 3 Pro via Zen |
opencode/grok-code | Grok Code |
opencode/kimi-k2 | Kimi K2 |
opencode/qwen3-coder | Qwen3 Coder |
anthropic/claude-sonnet-4-20250514 | Claude direct via Anthropic |
anthropic/claude-opus-4-20250514 | Claude Opus direct |
openai/gpt-5.2 | GPT-5.2 direct via OpenAI |
google/gemini-3-pro | Gemini 3 Pro direct |
AgentResult Type
interface AgentResult<T = any> {
output: string; // Raw text output
structured?: T; // Validated structured output
tokensUsed: {
input: number;
output: number;
};
turnsUsed: number;
stopReason: 'completed' | 'stop_condition' | 'error' | 'cancelled';
durationMs: number;
exitCode?: number;
sessionId?: string;
}
Structured Output with Zod
import { z } from 'zod';
const AnalysisSchema = z.object({
summary: z.string(),
issues: z.array(z.object({
severity: z.enum(['low', 'medium', 'high', 'critical']),
file: z.string(),
description: z.string(),
})),
});
<OpenCode
model="opencode/gpt-5.2-codex"
schema={AnalysisSchema}
onFinished={(result) => {
for (const issue of result.structured.issues) {
console.log(`[${issue.severity}] ${issue.file}: ${issue.description}`);
}
}}
>
Analyze this codebase for security issues.
</OpenCode>
Agent Types
Use different agents for specialized tasks:
// Default agent
<OpenCode model="opencode/big-pickle">
General task
</OpenCode>
// Coder agent - optimized for implementation
<OpenCode model="opencode/gpt-5.2-codex" agent="coder">
Implement the feature
</OpenCode>
// Planner agent - optimized for planning
<OpenCode model="opencode/big-pickle" agent="planner">
Create a plan for the migration
</OpenCode>
Error Handling
<OpenCode
model="opencode/big-pickle"
maxRetries={3}
retryOnValidationFailure
onError={(err) => console.error("Failed:", err.message)}
onFinished={(r) => console.log("Success:", r.output)}
>
Complete the task.
</OpenCode>
