9 codex bridge

Overview

The Codex bridge wraps OpenAI’s codex CLI, providing access to Codex’s code-generation capabilities through Agent-Ctrl’s unified API. Codex is particularly well-suited when you need fine-grained sandbox controls over filesystem and network access, image-based prompts, and automatic approval workflows. The bridge is implemented by CodexBridge and configured through CodexBridgeBuilder. Access the builder through the AgentCtrl facade:

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

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

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

Basic Usage

use Cognesy\AgentCtrl\AgentCtrl;

$response = AgentCtrl::codex()
    ->execute('Summarize the test suite in this repository.');

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

With model and sandbox configuration:

use Cognesy\AgentCtrl\AgentCtrl;
use Cognesy\AgentCtrl\OpenAICodex\Domain\Enum\SandboxMode;

$response = AgentCtrl::codex()
    ->withModel('o4-mini')
    ->withSandbox(SandboxMode::WorkspaceWrite)
    ->execute('Write tests for the UserService class.');

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

Sandbox Modes

Codex provides three sandbox modes that control what filesystem and network access the agent has during execution. These are managed through the SandboxMode enum:

use Cognesy\AgentCtrl\OpenAICodex\Domain\Enum\SandboxMode;
// @doctest id="7a3a"

Mode	Filesystem	Network	CLI Value	Use Case
`SandboxMode::ReadOnly`	Read-only	No	`read-only`	Safe analysis, code review, reading files without modification
`SandboxMode::WorkspaceWrite`	Write access to workspace	No	`workspace-write`	Code generation, refactoring, test writing
`SandboxMode::DangerFullAccess`	Full access	Yes	`danger-full-access`	Tasks requiring network access or system-wide file operations

// Read-only: safe for analysis tasks
$response = AgentCtrl::codex()
    ->withSandbox(SandboxMode::ReadOnly)
    ->execute('Analyze the code structure and identify issues.');

// Workspace write: for code modifications
$response = AgentCtrl::codex()
    ->withSandbox(SandboxMode::WorkspaceWrite)
    ->execute('Refactor the database layer to use the repository pattern.');

// Full access: for tasks needing network or system access
$response = AgentCtrl::codex()
    ->withSandbox(SandboxMode::DangerFullAccess)
    ->execute('Install a dependency and update the code to use it.');
// @doctest id="811d"

Disabling the Sandbox

The disableSandbox() method is a shorthand for withSandbox(SandboxMode::DangerFullAccess):

$response = AgentCtrl::codex()
    ->disableSandbox()
    ->execute('Run the full test suite and report results.');
// @doctest id="77cb"

Approval Modes

Codex supports two approval configuration methods that control how the agent handles permission requests.

Full Auto Mode

fullAuto() enables automatic approval with workspace-write sandbox access. This is the default configuration (true), making it suitable for headless execution:

$response = AgentCtrl::codex()
    ->fullAuto()
    ->execute('Implement the feature described in SPEC.md.');
// @doctest id="aacb"

When full-auto is enabled, the agent automatically approves tool executions that would normally require user confirmation, and on-failure actions are also auto-approved. Disable it when you want more conservative behavior:

$response = AgentCtrl::codex()
    ->fullAuto(false)
    ->execute('Analyze the codebase structure.');
// @doctest id="2077"

Dangerous Bypass

dangerouslyBypass() skips all approval prompts and all sandbox restrictions. This is the most permissive mode and should be used only when you fully trust the agent and the execution environment:

$response = AgentCtrl::codex()
    ->dangerouslyBypass()
    ->execute('Deploy the application to staging.');
// @doctest id="0baf"

Warning: This mode disables all safety guardrails. The agent can execute arbitrary commands, modify any file, and access the network without restriction.

Git Repository Check

By default, Codex requires the working directory to be inside a Git repository. Use skipGitRepoCheck() to bypass this requirement when working with non-Git directories:

$response = AgentCtrl::codex()
    ->skipGitRepoCheck()
    ->inDirectory('/tmp/workspace')
    ->execute('Create a new project skeleton.');
// @doctest id="5dfe"

Image Input

Codex supports image attachments, allowing the agent to analyze visual content alongside text prompts. Use withImages() to attach one or more image files:

$response = AgentCtrl::codex()
    ->withImages(['/tmp/mockup.png'])
    ->execute('Implement the UI component shown in the mockup.');
// @doctest id="7ea9"

Multiple images can be attached:

$response = AgentCtrl::codex()
    ->withImages([
        '/tmp/current-ui.png',
        '/tmp/target-design.png',
    ])
    ->execute('Compare the current UI with the target design and list the differences.');
// @doctest id="9811"

Each path must point to an existing image file on the local filesystem.

Additional Directories

Use withAdditionalDirs() to grant the agent write access to directories beyond the working directory:

$response = AgentCtrl::codex()
    ->inDirectory('/projects/my-app')
    ->withAdditionalDirs(['/shared/assets', '/configs'])
    ->execute('Update the shared configuration files.');
// @doctest id="6dd9"

Streaming with Codex

Codex streams output as JSON Lines containing item events (started, completed), turn events, thread events, and error events. The bridge normalizes these into the standard callback API:

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

$response = AgentCtrl::codex()
    ->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('Explain the test framework used in this project.');
// @doctest id="048d"

Tool Call Normalization

Codex produces several item types that are normalized into ToolCall objects:

Codex Item Type	Normalized Tool Name	Input Structure
`CommandExecution`	`'bash'`	`['command' => '...']`
`FileChange`	`'file_change'`	`['path' => '...', 'action' => '...']`
`McpToolCall`	Original tool name	Original arguments
`WebSearch`	`'web_search'`	`['query' => '...']`
`PlanUpdate`	`'plan_update'`	`[]`
`Reasoning`	`'reasoning'`	`[]`
`UnknownItem`	Original item type	`[]`

The isError flag is set when the item has an error status (error, failed, cancelled) or when a CommandExecution has a non-zero exit code.

Working with Tool Calls

foreach ($response->toolCalls as $tc) {
    if ($tc->tool === 'bash') {
        echo "Command: {$tc->input['command']}\n";
        echo "Output: {$tc->output}\n";
    }

    if ($tc->tool === 'file_change') {
        echo "Changed: {$tc->input['path']} ({$tc->input['action']})\n";
    }

    if ($tc->tool === 'web_search') {
        echo "Searched: {$tc->input['query']}\n";
    }
}
// @doctest id="0cab"

Session Management

Codex uses thread-based conversations. Agent-Ctrl normalizes the thread ID into an AgentSessionId:

// First execution
$first = AgentCtrl::codex()->execute('Create a plan for the refactoring.');
$sessionId = $first->sessionId();

// Continue the most recent session
$next = AgentCtrl::codex()
    ->continueSession()
    ->execute('Proceed with step 1.');

// Resume a specific thread
if ($sessionId !== null) {
    $next = AgentCtrl::codex()
        ->resumeSession((string) $sessionId)
        ->execute('Continue from where we left off.');
}
// @doctest id="c29b"

Data Availability

Data Point	Available	Notes
Text output	Yes	Extracted from `AgentMessage` items
Tool calls	Yes	Normalized from all item types (see table above)
Session ID	Yes	Normalized from Codex thread ID
Token usage	Yes	Input tokens, output tokens, cached input tokens
Cost	No	Codex CLI does not expose cost data
Parse diagnostics	Yes	Malformed JSON line counts and samples

Token Usage

When Codex exposes usage statistics, they are converted into the unified TokenUsage DTO:

$response = AgentCtrl::codex()->execute('Analyze the codebase.');

$usage = $response->usage();
if ($usage !== null) {
    echo "Input tokens: {$usage->input}\n";
    echo "Output tokens: {$usage->output}\n";
    echo "Cache read: " . ($usage->cacheRead ?? 'N/A') . "\n";
    echo "Total: {$usage->total()}\n";
}
// @doctest id="5a83"

Complete Example

use Cognesy\AgentCtrl\AgentCtrl;
use Cognesy\AgentCtrl\OpenAICodex\Domain\Enum\SandboxMode;
use Cognesy\AgentCtrl\Broadcasting\AgentCtrlConsoleLogger;

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

$response = AgentCtrl::codex()
    ->withModel('o4-mini')
    ->withSandbox(SandboxMode::WorkspaceWrite)
    ->fullAuto()
    ->withTimeout(300)
    ->inDirectory('/projects/my-app')
    ->withAdditionalDirs(['/shared/test-fixtures'])
    ->withImages(['/tmp/design-spec.png'])
    ->wiretap($logger->wiretap())
    ->onText(fn(string $text) => print($text))
    ->onToolUse(fn(string $tool, array $input, ?string $output) => print("\n> [{$tool}]\n"))
    ->executeStreaming('Implement the component shown in the design spec and write tests.');

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

    // Summarize file changes
    $fileChanges = array_filter($response->toolCalls, fn($tc) => $tc->tool === 'file_change');
    echo "Files changed: " . count($fileChanges) . "\n";

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

    $sessionId = $response->sessionId();
    if ($sessionId !== null) {
        echo "Thread: {$sessionId}\n";
    }
} else {
    echo "\n\nTask failed with exit code: {$response->exitCode}\n";
}
// @doctest id="73e3"

Packages

Instructor

Polyglot

Agents

Agent-ctrl

Telemetry

Sandbox

HTTP Client

Laravel

Symfony

Xprompt

Overview

Basic Usage

Sandbox Modes

Disabling the Sandbox

Approval Modes

Full Auto Mode

Dangerous Bypass

Git Repository Check

Image Input

Additional Directories

Streaming with Codex

Tool Call Normalization

Working with Tool Calls

Session Management

Data Availability

Token Usage

Complete Example

​Overview

​Basic Usage

​Sandbox Modes

​Disabling the Sandbox

​Approval Modes

​Full Auto Mode

​Dangerous Bypass

​Git Repository Check

​Image Input

​Additional Directories

​Streaming with Codex

​Tool Call Normalization

​Working with Tool Calls

​Session Management

​Data Availability

​Token Usage

​Complete Example

Overview

Basic Usage

Sandbox Modes

Disabling the Sandbox

Approval Modes

Full Auto Mode

Dangerous Bypass

Git Repository Check

Image Input

Additional Directories

Streaming with Codex

Tool Call Normalization

Working with Tool Calls

Session Management

Data Availability

Token Usage

Complete Example