> ## Documentation Index
> Fetch the complete documentation index at: https://docs.instructorphp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 1 overview

## Introduction

Agent-Ctrl is a PHP package that gives your application a single entry point for running CLI-based code agents. Instead of writing separate integration code for each agent's command-line interface, JSON output format, and streaming protocol, you configure one fluent builder and receive one normalized response -- regardless of which agent performed the work.

The package ships as part of the Instructor-PHP monorepo and can be installed standalone via Composer:

```bash theme={null}
composer require cognesy/agent-ctrl
# @doctest id="d72f"
```

## Entry Point

All interactions start with the `AgentCtrl` facade. It exposes dedicated factory methods for each supported agent, as well as a generic `make()` method that accepts an `AgentType` enum for runtime switching:

```php theme={null}
use Cognesy\AgentCtrl\AgentCtrl;
use Cognesy\AgentCtrl\Enum\AgentType;

// Dedicated factory methods
AgentCtrl::claudeCode();   // Returns ClaudeCodeBridgeBuilder
AgentCtrl::codex();        // Returns CodexBridgeBuilder
AgentCtrl::openCode();     // Returns OpenCodeBridgeBuilder
AgentCtrl::pi();           // Returns PiBridgeBuilder
AgentCtrl::gemini();       // Returns GeminiBridgeBuilder

// Runtime selection via enum
AgentCtrl::make(AgentType::from('codex'));
// @doctest id="ff8b"
```

Each factory method returns a bridge builder -- a fluent configuration object that lets you set the model, timeout, working directory, streaming callbacks, and agent-specific options before calling `execute()` or `executeStreaming()`.

## Execution Flow

Every agent interaction follows the same three-step lifecycle:

1. **Configure** -- Use the builder's fluent methods to set the model, working directory, timeout, sandbox driver, streaming callbacks, and any agent-specific options (system prompts, permission modes, sandbox modes, etc.).

2. **Execute** -- Call `execute()` for a blocking request that returns the final result, or `executeStreaming()` when you need real-time text and tool activity delivered through callbacks while the agent is still running.

3. **Read the response** -- Both execution methods return an `AgentResponse` object with a normalized shape: the agent's text output, exit code, session ID, token usage (when available), cost (when available), tool calls, parse diagnostics, and the raw bridge-specific response for advanced inspection.

```php theme={null}
use Cognesy\AgentCtrl\AgentCtrl;

$response = AgentCtrl::claudeCode()
    ->withModel('claude-sonnet-4-5')
    ->withTimeout(300)
    ->inDirectory('/projects/my-app')
    ->execute('Summarize the architecture of this project.');

if ($response->isSuccess()) {
    echo $response->text();
}
// @doctest id="91fa"
```

## Core Capabilities

**Unified API across agents.** Switch between Claude Code, Codex, OpenCode, Pi, and Gemini without changing your application's control flow or response handling. The same `execute()` call and `AgentResponse` shape work with every bridge.

**Real-time streaming.** Register `onText()`, `onToolUse()`, `onComplete()`, and `onError()` callbacks to receive incremental updates while the agent works. Streaming and final-result access are not mutually exclusive -- `executeStreaming()` returns the complete `AgentResponse` when the agent finishes.

**Session continuity.** Continue the most recent session or resume a specific session by ID. Session identifiers are extracted from each agent's native output format and normalized into `AgentSessionId` value objects.

**Configurable execution environment.** Set the working directory, execution timeout, and sandbox driver (Host, Docker, Podman, Firejail, or Bubblewrap). The sandbox integration runs through the Instructor-PHP `Sandbox` package, providing consistent process isolation across all agents.

**Normalized tool call tracking.** Every tool invocation -- whether it is a Claude Code tool use, a Codex command execution or file change, an OpenCode tool call, or a Pi tool execution -- is normalized into a `ToolCall` DTO with a tool name, input parameters, optional output, call ID, and error flag.

**Observable execution pipeline.** The builder emits granular events at every stage of the execution lifecycle: request building, command spec creation, sandbox initialization, process start/completion, stream chunk processing, response parsing, and data extraction. Connect the built-in `AgentCtrlConsoleLogger` via `wiretap()` for color-coded console output during development.

**Binary preflight checks.** Before every execution, `CliBinaryGuard` verifies that the required CLI binary (`claude`, `codex`, `opencode`, or `pi`) is available in the system `PATH`. If the binary is missing, a clear exception is thrown immediately -- before any prompt is sent.

## Supported Agents

### Claude Code

Anthropic's `claude` CLI. A strong default choice for general coding workflows, tool-heavy tasks, and scenarios where you want fine-grained control over the agent's system prompt and permission behavior. Supports system prompt replacement and appending, permission modes (default, plan, accept-edits, bypass), turn limits, additional directory access, session management, and verbose streaming output.

### OpenAI Codex

OpenAI's `codex` CLI. Best suited when you want Codex-specific sandbox controls (read-only, workspace-write, or full-access modes), full-auto or dangerous-bypass approval settings, image input support, and Codex thread-based session management. Returns token usage data when available.

### OpenCode

The `opencode` CLI. Best suited when you want flexible model selection using provider-prefixed model IDs (e.g., `anthropic/claude-sonnet-4-5`), named agent selection, file attachments, session sharing, and session titles. Returns both token usage and cost data when available.

### Pi

The `pi` CLI (from pi-mono). A minimal, aggressively extensible terminal coding harness. Best suited when you want thinking level control (6 levels from off to xhigh), multi-provider model selection, TypeScript extensions, skills, fine-grained tool selection, system prompt control, and ephemeral sessions. Returns both token usage and cost data.

### Gemini

The `gemini` CLI (from @google/gemini-cli). Google's terminal coding agent with a free tier. Best suited when you want model aliases (pro, flash, flash-lite), approval modes (default, auto\_edit, yolo, plan), sandbox isolation (Seatbelt, Docker, Podman, gVisor), extensions, MCP server integration, policy-based tool approval, and include directories. Returns token usage data.

## Documentation

* [Getting Started](/packages/agent-ctrl/2-getting-started) -- Installation, first request, and basic configuration
* [Streaming](/packages/agent-ctrl/3-streaming) -- Real-time text, tool activity, completion, and error callbacks
* [Session Management](/packages/agent-ctrl/4-session-management) -- Continuing and resuming agent sessions
* [Agent Options](/packages/agent-ctrl/5-agent-options) -- Shared and provider-specific builder configuration
* [Response Object](/packages/agent-ctrl/6-response-object) -- Reading text, session, usage, cost, and tool data from AgentResponse
* [Troubleshooting](/packages/agent-ctrl/7-troubleshooting) -- Diagnosing binary, directory, timeout, streaming, and parse issues
* [Claude Code Bridge](/packages/agent-ctrl/8-claude-code-bridge) -- System prompts, permissions, turns, and Claude Code-specific features
* [Codex Bridge](/packages/agent-ctrl/9-codex-bridge) -- Sandbox modes, auto-approval, images, and Codex-specific features
* [OpenCode Bridge](/packages/agent-ctrl/10-opencode-bridge) -- Model flexibility, agents, files, sharing, and OpenCode-specific features
* [Pi Bridge](/packages/agent-ctrl/11-pi-bridge) -- Thinking levels, extensions, skills, tool control, and Pi-specific features
* [Gemini Bridge](/packages/agent-ctrl/12-gemini-bridge) -- Approval modes, sandbox, extensions, MCP servers, and Gemini-specific features