README

Atlas Agent CLI is a Laravel-ready wrapper around the Codex coding agent CLI. It exposes an Artisan command and service layer that stream Codex output, sanitize ANSI characters, persist JSONL logs, and report a summarized transcript in real time.

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

Overview

Agent CLI mirrors the raw codex CLI while layering Laravel-native ergonomics: streaming output, ANSI sanitizing, JSON Lines logging, and command/service APIs for both interactive and headless sessions.

Installation

composer require atlas-php/agent-cli

The package registers itself automatically through Laravel's package auto-discovery. When running in Lumen or if auto-discovery is disabled, register the provider manually:

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

Usage

Artisan Command

The command mirrors the raw codex CLI but adds streaming and JSON logging:

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

Options:

args* – the exact arguments to forward to the Codex CLI.
--interactive – run Codex directly attached to your terminal (no JSON logging).
--model= – override the Codex model for the current run.
--reasoning= – set the Codex reasoning strategy (for example: medium, deep) for this run; forwarded to Codex as --config model_reasoning_effort=<value>.
--approval= – set the Codex approval policy (untrusted, on-failure, on-request, never) for this run; forwarded to Codex as --config approval_policy=<value>.
--instructions= – prepend additional system instructions ahead of the user task; stored in the JSON log as a thread.request event.
--template-task= / --template-instructions= – override the configured task/instructions templates for a single run when you want to reshape the payload without editing config.
--meta= – supply a JSON object of metadata (IDs, tags, etc.) that is recorded alongside the synthetic thread lifecycle log entry.
--resume= – continue an existing Codex thread; the wrapper preserves the thread identifier, writes a thread.resumed log entry for the new task, and still forwards only your task arguments to Codex.
--workspace= – override the working directory Codex uses for this run (falls back to the configured workspace when omitted). The command executes Codex from this path and logs it inside the workspace JSONL entry alongside the provider name.

Upon completion the command prints:

Codex session/thread identifier.
Absolute path to the JSONL log file stored at the configured sessions directory.
Exit code emitted by the Codex CLI process.

Service

Consume the Atlas\Agent\Services\CodexCliSessionService directly when you need custom orchestration:

use Atlas\Agent\Services\CodexCliSessionService;

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

// $result = [
//     'session_id' => 'thread_abc123',
//     'json_file_path' => config('atlas-agent-cli.sessions.path').'/thread_abc123.jsonl',
//     'exit_code' => 0,
// ];

The service handles both interactive and headless runs, automatically sanitizes ANSI escape sequences, streams events to STDOUT/STDERR, and records every Codex JSON event to a JSON Lines log.

When invoking the service directly you may pass a workspace override and optional task/instruction templates as the final arguments (startSession($args, $interactive, ..., $workspaceOverride, $templates)), mirroring the --workspace and --template-* console options.

Each headless log now begins with a workspace entry that captures the provider (codex), the Codex workspace path, the platform path, the JSONL log directory, the effective model, the reasoning strategy, and the approval policy for the run. This is followed by the synthetic thread.request (or thread.resumed) entry summarizing system instructions, the triggering task, and any metadata supplied via --meta, so downstream tooling can reconstruct the full prompt context. When resuming a thread via --resume, the log still records a thread.resumed entry containing the latest user task (plus metadata) without re-stating the original instructions. If you abort a headless run with a signal such as CTRL+C, the transcript includes a final thread.terminated event with the received signal so consumers can see the session ended manually.

Configuration

Publish the configuration file to customize session storage and Codex defaults:

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

php sandbox/artisan agent:codex --workspace="/Users/marois/Development/Atlasphp/Repo/agent-cli" "say hello"

The config/atlas-agent-cli.php file exposes:

sessions.path – base directory for JSONL transcripts. Atlas Agent CLI stores Codex logs inside <path>/codex. Defaults to storage/app/sessions.
workspace.path – the working directory Codex should execute within. Defaults to your Laravel application's base path but can be pointed at any detached workspace (override via the --workspace command option for per-run overrides).
providers.codex.model / providers.codex.reasoning / providers.codex.approval – default Codex runtime options applied unless overridden via --model, --reasoning, or --approval. Defaults: model gpt-5.1-codex-max, reasoning medium, approval never.
template.task / template.instructions – string templates (defaults to Task: {TASK} and Instructions: {INSTRUCTIONS}) that shape how the task and instructions are combined before forwarding them to Codex. Workspace logs record the templates, and thread request/resume entries include the rendered messages (instructions first, then task) so you can see exactly what Codex receives.

Local Sandbox

The repository ships with a minimal Laravel sandbox so you can run the agent:codex command without installing the package into a real application. The sandbox has no database and only registers the Agent CLI service provider.

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

JSON transcripts are stored inside sandbox/storage/app/sessions/codex. Pass --interactive to talk directly to Codex without log files.

Testing

Run Pint, PHPUnit, and Larastan from the package root:

composer lint
composer test
composer analyse

Contributing

See the Contributing Guide and Agents.

License

MIT — see LICENSE.

atlas-php / agent-cli

Maintainers

Details