README

Atlas Agent CLI (coding agent) is a streamlined Laravel wrapper around the Codex CLI. It provides a unified command and service layer for running Codex tasks with clean streaming output, ANSI sanitization, structured JSONL logging, and optional headless or interactive execution.

Overview
Features
Installation
Usage
- Artisan Command
- Service Layer
Configuration
Local Sandbox
Testing
Contributing
License

Overview

Atlas Agent CLI mirrors the native codex CLI while adding Laravel-native ergonomics. It standardizes how Codex sessions are started, streamed, logged, and resumed—making it easier to integrate code-generation workflows into Laravel applications or automated pipelines.

Features

Clean stream handling with automatic ANSI sanitization.
JSON Lines transcript logging for every run.
Transcript parsing helpers for inspecting sessions (todos, turns, full history).
Resume support for Codex threads.
Task and instruction templating.
Per-run model, reasoning, approval, and workspace overrides.
Laravel-ready command and service APIs.

Installation

composer require atlas-php/agent-cli

The package auto-discovers its service provider. If necessary, register it manually:

// bootstrap/app.php or config/app.php
Atlas\Agent\Providers\AgentCliServiceProvider::class,

Usage

Artisan Command

Run Codex through Laravel with streaming output and automatic logging:

php artisan agent:codex -- tasks:list --plan

Key options:

args* – forwarded directly to the Codex CLI.
--interactive – attach Codex to your terminal (no JSON logging).
--model= – override the Codex model.
--reasoning= – specify the reasoning effort.
--approval= – override approval policy.
--instructions= – prepend system instructions.
--template-task= / --template-instructions= – override templates.
--meta= – attach metadata recorded in the transcript.
--resume= – resume an existing Codex thread.
--workspace= – override the execution directory.

After completion, the command prints:

Codex session/thread ID.
Path to the JSONL transcript.
Exit code from the Codex process.

Service Layer

Use the service for programmatic orchestration:

use Atlas\Agent\Services\CodexCliSessionService;

$result = app(CodexCliSessionService::class)->startSession([
    'tasks:list', '--plan'
]);

The service:

Streams output to STDOUT/STDERR.
Logs all events as JSONL.
Sanitizes ANSI sequences.
Supports workspace and template overrides.
Records synthetic thread.request, thread.resumed, and thread.terminated events.

Parse a finished session transcript into actionable structures:

use Atlas\Agent\Services\SessionTranscripts\SessionTranscriptService;

/** @var SessionTranscriptService $transcripts */
$transcripts = app(SessionTranscriptService::class);

$events = $transcripts->fullTranscript('codex', 'thread-123');
$todos = $transcripts->todoList('codex', 'thread-123');
$turns = $transcripts->turns('codex', 'thread-123');
$usage = $transcripts->usageTotals('codex', 'thread-123'); // sums input/output/cached across turns

Configuration

Publish the config to customize storage paths, Codex defaults, and templates:

php artisan vendor:publish --tag=atlas-agent-cli-config

Configuration options include:

sessions.path – base directory for JSONL logs.
workspace.path – default Codex working directory.
providers.codex.* – default model, reasoning, approval values.
template.* – instruction and task templates.

Local Sandbox

The package includes a minimal Laravel sandbox for local experimentation:

php sandbox/artisan agent:codex -- tasks:list --plan

Logs are stored at sandbox/storage/app/sessions/codex.

Testing

composer lint
composer test
composer analyse

Contributing

See the Contributing Guide and Agents.

License

MIT — see LICENSE.

atlas-php / agent-cli

Maintainers

Details