README

A common abstraction layer for CLI-based code agents (Claude Code, OpenAI Codex, OpenCode).

Overview

The Unified Agent Bridge provides:

• Fluent Builder API - Configure agents with typed, IDE-friendly methods
• Runtime Switching - Change agents without code changes
• Common Response Format - Normalized AgentResponse across all agents
• Streaming Support - Real-time callbacks for text and tool events

Quick Start

Basic Usage

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

// Execute a prompt
$response = AgentCtrl::make(AgentType::ClaudeCode)
    ->execute('Fix the bug in AuthController');

echo $response->text();

With Configuration

// Claude Code with full configuration
$response = AgentCtrl::claudeCode()
    ->withModel('claude-opus-4-5')
    ->withSystemPrompt('You are a senior PHP developer')
    ->withMaxTurns(10)
    ->withPermissionMode(PermissionMode::BypassPermissions)
    ->execute('Refactor the User model');

// OpenCode with provider/model format
$response = AgentCtrl::openCode()
    ->withModel('anthropic/claude-sonnet-4-5')
    ->withAgent('coder')
    ->withFiles(['src/User.php'])
    ->execute('Add validation');

// Codex with sandbox control
$response = AgentCtrl::codex()
    ->withModel('codex')
    ->withSandbox(SandboxMode::NetworkOnly)
    ->fullAuto()
    ->execute('Write tests for the API');

Streaming

$response = AgentCtrl::openCode()
    ->withModel('anthropic/claude-sonnet-4-5')
    ->onText(fn($text) => print($text))
    ->onToolUse(fn($tool, $input, $output) => print("[Tool: $tool]\n"))
    ->onComplete(fn($response) => print("\nDone!\n"))
    ->executeStreaming('Explain this codebase');

Runtime Switching

// Select agent from configuration
$agentType = AgentType::from($config['agent']); // 'claude-code', 'codex', 'opencode'

$response = AgentCtrl::make($agentType)
    ->withModel($config['model'])
    ->execute($prompt);

Builder Methods

Common (All Agents)

Claude Code Specific

Codex Specific

OpenCode Specific

Response

All agents return AgentResponse:

$response->agentType;   // AgentType enum
$response->text;        // Response text
$response->exitCode;    // Process exit code
$response->sessionId;   // Session ID (if available)
$response->usage;       // TokenUsage (input/output tokens)
$response->cost;        // Cost in USD (if available)
$response->toolCalls;   // Array of ToolCall objects
$response->rawResponse; // Original bridge response

$response->isSuccess(); // true if exitCode === 0
$response->text();      // Alias for $response->text
$response->usage();     // Alias for $response->usage
$response->cost();      // Alias for $response->cost

Architecture

AgentCtrl::make(AgentType)
    ↓
AgentBridgeBuilder (ClaudeCode|Codex|OpenCode)
    ↓ .build()
AgentBridge (wraps native components)
    ↓ .execute() or .executeStreaming()
AgentResponse (normalized output)

See Also

• ClaudeCode Bridge
• OpenAICodex Bridge
• OpenCode Bridge
• Common Components