10 opencode bridge

Overview

The OpenCode bridge wraps the opencode CLI, providing access to a multi-provider code agent through Agent-Ctrl’s unified API. OpenCode is the most flexible bridge in terms of model selection — it supports provider-prefixed model IDs that let you use models from Anthropic, OpenAI, Google, and other providers through a single CLI tool. It exposes both token usage and cost data (as does the Pi bridge). The bridge is implemented by OpenCodeBridge and configured through OpenCodeBridgeBuilder. Access the builder through the AgentCtrl facade:

use Cognesy\AgentCtrl\AgentCtrl;
use Cognesy\AgentCtrl\Enum\AgentType;

// Dedicated factory method
$builder = AgentCtrl::openCode();

// Or via the generic factory
$builder = AgentCtrl::make(AgentType::OpenCode);
// @doctest id="7e77"

Basic Usage

use Cognesy\AgentCtrl\AgentCtrl;

$response = AgentCtrl::openCode()
    ->execute('Explain the architecture of this project in short paragraphs.');

echo $response->text();
// @doctest id="0f12"

With model selection:

$response = AgentCtrl::openCode()
    ->withModel('anthropic/claude-sonnet-4-5')
    ->execute('Review the test suite.');

echo $response->text();
// @doctest id="e0ae"

Model Selection

OpenCode uses provider-prefixed model IDs, giving you access to models from multiple providers through a single CLI. The format is provider/model-name:

// Anthropic models
AgentCtrl::openCode()->withModel('anthropic/claude-sonnet-4-5');
AgentCtrl::openCode()->withModel('anthropic/claude-opus-4');

// OpenAI models
AgentCtrl::openCode()->withModel('openai/gpt-4o');
AgentCtrl::openCode()->withModel('openai/o4-mini');

// Google models
AgentCtrl::openCode()->withModel('google/gemini-2.5-pro');
// @doctest id="9036"

The exact set of available providers and models depends on your OpenCode installation and configuration. If no model is specified, OpenCode uses its configured default. Check OpenCode’s documentation for the full list of supported providers and models.

Named Agents

OpenCode supports named agents — preconfigured agent profiles that define specific behaviors, tools, and system prompts. Use withAgent() to select one:

$response = AgentCtrl::openCode()
    ->withAgent('coder')
    ->execute('Refactor the authentication module.');
// @doctest id="29b6"

$response = AgentCtrl::openCode()
    ->withAgent('task')
    ->execute('Create a detailed implementation plan.');
// @doctest id="c297"

The available agent names depend on your OpenCode configuration. Common agents include coder (for code-focused tasks) and task (for planning and general tasks).

File Attachments

Use withFiles() to attach specific files to the prompt. The agent will have direct access to these files as context, without needing to discover and read them:

$response = AgentCtrl::openCode()
    ->withFiles([
        '/projects/my-app/src/Services/PaymentService.php',
        '/projects/my-app/src/Models/Payment.php',
    ])
    ->execute('Refactor the PaymentService to handle partial refunds.');
// @doctest id="12bb"

Unlike inDirectory() which sets the working directory, withFiles() explicitly includes specific files in the prompt context. This is useful when you want the agent to focus on particular files rather than browsing the project directory.

Session Title

Use withTitle() to set a descriptive title for the session. The title appears in OpenCode’s session listing and makes it easier to identify sessions later:

$response = AgentCtrl::openCode()
    ->withTitle('Payment module refactoring')
    ->execute('Plan the payment module refactoring.');
// @doctest id="c0a3"

Titles are especially useful when you manage multiple sessions and need to identify them by purpose rather than by opaque session IDs. Use shareSession() to mark the session for sharing after completion. Shared sessions can be accessed by other users or tools, enabling collaborative workflows where multiple team members can review or continue an agent’s work:

$response = AgentCtrl::openCode()
    ->shareSession()
    ->withTitle('Architecture review for team')
    ->execute('Create a comprehensive architecture review.');

// The session ID can be shared with others
$sessionId = $response->sessionId();
if ($sessionId !== null) {
    echo "Share this session ID with your team: {$sessionId}\n";
}
// @doctest id="d88a"

Streaming with OpenCode

OpenCode streams output as JSON Lines containing text events, tool use events, step events, and error events. The bridge normalizes these into the standard callback API:

use Cognesy\AgentCtrl\AgentCtrl;
use Cognesy\AgentCtrl\Dto\AgentResponse;

$response = AgentCtrl::openCode()
    ->onText(fn(string $text) => print($text))
    ->onToolUse(fn(string $tool, array $input, ?string $output) => print("\n> [{$tool}]\n"))
    ->onError(fn(string $message, ?string $code) => print("\nError [{$code}]: {$message}\n"))
    ->executeStreaming('Analyze the error handling in this codebase.');
// @doctest id="bcf7"

Event Normalization

During streaming, OpenCode emits several event types that are normalized:

TextEvent — Text content is delivered through onText() with the text string.
ToolUseEvent — Tool invocations are delivered through onToolUse() with the tool name, input parameters, optional output, and call ID. The isError flag is set based on whether the tool completed successfully.
ErrorEvent — Error events are delivered through onError() with the message, optional code, and raw data.
StepStartEvent / StepFinishEvent — Step lifecycle events are processed internally and available through the wiretap() event system but not directly exposed through user callbacks.

Session Management

OpenCode maintains its own session system with session IDs. Agent-Ctrl extracts and normalizes these into AgentSessionId value objects. Internally, OpenCode uses OpenCodeSessionId which is mapped to the unified AgentSessionId:

// First execution
$first = AgentCtrl::openCode()->execute('Create an implementation plan.');
$sessionId = $first->sessionId();

// Continue the most recent session (no ID needed)
$next = AgentCtrl::openCode()
    ->continueSession()
    ->execute('Begin implementing the plan.');

// Resume a specific session by ID
if ($sessionId !== null) {
    $next = AgentCtrl::openCode()
        ->resumeSession((string) $sessionId)
        ->execute('Continue with the next step.');
}
// @doctest id="fff5"

Usage and Cost Data

OpenCode provides comprehensive usage and cost reporting. Both token usage and cost data are available after execution.

Token Usage

OpenCode’s TokenUsage includes all five token categories — input, output, cache read, cache write, and reasoning:

$response = AgentCtrl::openCode()
    ->withModel('anthropic/claude-sonnet-4-5')
    ->execute('Analyze the project dependencies.');

$usage = $response->usage();
if ($usage !== null) {
    echo "Input tokens:    {$usage->input}\n";
    echo "Output tokens:   {$usage->output}\n";
    echo "Total tokens:    {$usage->total()}\n";

    if ($usage->cacheRead !== null) {
        echo "Cache read:      {$usage->cacheRead}\n";
    }
    if ($usage->cacheWrite !== null) {
        echo "Cache write:     {$usage->cacheWrite}\n";
    }
    if ($usage->reasoning !== null) {
        echo "Reasoning:       {$usage->reasoning}\n";
    }
}
// @doctest id="0244"

Cost Tracking

OpenCode exposes cost data (as does Pi). The cost is returned in USD:

$cost = $response->cost();
if ($cost !== null) {
    echo sprintf("This execution cost $%.4f\n", $cost);
}
// @doctest id="2669"

This makes OpenCode a good choice when you need to track and report on the cost of agent executions, build usage dashboards, or enforce cost budgets.

Data Availability

Data Point	Available	Notes
Text output	Yes	Extracted from `TextEvent` stream events
Tool calls	Yes	Normalized from `ToolUseEvent` with call IDs and completion status
Session ID	Yes	Extracted from OpenCode session data
Token usage	Yes	Input, output, cache read, cache write, reasoning tokens
Cost	Yes	Cost in USD
Parse diagnostics	Yes	Malformed JSON line counts and samples

Complete Example

use Cognesy\AgentCtrl\AgentCtrl;
use Cognesy\AgentCtrl\Dto\AgentResponse;
use Cognesy\AgentCtrl\Broadcasting\AgentCtrlConsoleLogger;

$logger = new AgentCtrlConsoleLogger(
    showStreaming: true,
    showPipeline: true,
);

$response = AgentCtrl::openCode()
    ->withModel('anthropic/claude-sonnet-4-5')
    ->withAgent('coder')
    ->withTitle('Comprehensive architecture review')
    ->withFiles([
        '/projects/my-app/src/Kernel.php',
        '/projects/my-app/src/routes.php',
    ])
    ->shareSession()
    ->withTimeout(300)
    ->inDirectory('/projects/my-app')
    ->wiretap($logger->wiretap())
    ->onText(fn(string $text) => print($text))
    ->onToolUse(fn(string $tool, array $input, ?string $output) => print("\n> [{$tool}]\n"))
    ->onComplete(fn(AgentResponse $r) => print("\n--- Complete ---\n"))
    ->executeStreaming('Review the application architecture and suggest improvements.');

if ($response->isSuccess()) {
    echo "\nReview completed successfully.\n";
    echo "Tools used: " . count($response->toolCalls) . "\n";

    $usage = $response->usage();
    if ($usage !== null) {
        echo "Tokens: {$usage->total()} (in: {$usage->input}, out: {$usage->output})\n";
    }

    $cost = $response->cost();
    if ($cost !== null) {
        echo sprintf("Cost: $%.4f\n", $cost);
    }

    $sessionId = $response->sessionId();
    if ($sessionId !== null) {
        echo "Session: {$sessionId}\n";
        echo "Use this ID with resumeSession() to continue later.\n";
    }
} else {
    echo "\nReview failed with exit code: {$response->exitCode}\n";
    echo "Partial output: " . substr($response->text(), 0, 500) . "\n";
}
// @doctest id="02d2"

Comparison with Other Bridges

Feature	Claude Code	Codex	OpenCode	Pi	Gemini
System prompts	Yes (replace + append)	No	No	Yes (replace + append)	Yes (GEMINI.md file)
Permission modes	Yes (4 levels)	No	No	No	Yes (4 modes)
Turn limits	Yes	No	No	No	Yes (via settings)
Sandbox modes	No	Yes (3 levels)	No	No	Yes (Seatbelt/Docker/Podman/gVisor)
Image input	No	Yes	No	No	No
Thinking levels	No	No	No	Yes (6 levels)	No
Named agents	No	No	Yes	No	No
File attachments	No	No	Yes	Yes (@-prefix)	No
Extensions	No	No	No	Yes (TypeScript)	Yes
Skills	No	No	No	Yes	No
Tool control	No	No	No	Yes (select/disable)	Yes (allowlist)
MCP servers	No	No	No	No	Yes
Policy engine	No	No	No	No	Yes
Session sharing	No	No	Yes	No	No
Session titles	No	No	Yes	No	No
Ephemeral mode	No	No	No	Yes	No
API key override	No	No	No	Yes	No
Token usage	No	Yes (partial)	Yes (full)	Yes	Yes (with cache)
Cost tracking	No	No	Yes	Yes	No
Multi-provider models	No	No	Yes	Yes	No

Packages

Instructor

Polyglot

Agents

Agent-ctrl

Telemetry

Sandbox

HTTP Client

Laravel

Symfony

Xprompt

Overview

Basic Usage

Model Selection

Named Agents

File Attachments

Session Title

Streaming with OpenCode

Event Normalization

Session Management

Usage and Cost Data

Token Usage

Cost Tracking

Data Availability

Complete Example

Comparison with Other Bridges

​Overview

​Basic Usage

​Model Selection

​Named Agents

​File Attachments

​Session Title

​Session Sharing

​Streaming with OpenCode

​Event Normalization

​Session Management

​Usage and Cost Data

​Token Usage

​Cost Tracking

​Data Availability

​Complete Example

​Comparison with Other Bridges

Overview

Basic Usage

Model Selection

Named Agents

File Attachments

Session Title

Session Sharing

Streaming with OpenCode

Event Normalization

Session Management

Usage and Cost Data

Token Usage

Cost Tracking

Data Availability

Complete Example

Comparison with Other Bridges