Codex Agent Plugin

The Codex agent plugin integrates OpenAI’s Codex CLI, providing automatic metadata updates via shell wrappers, session introspection from JSONL rollout files, and native thread resumption.

Overview

Codex is OpenAI’s AI coding assistant CLI. The plugin:

Automatically resolves the Codex binary (npm global, Homebrew, Cargo)
Injects ~/.ao/bin into PATH to wrap gh and git commands
Updates metadata transparently when agents create PRs or switch branches
Streams JSONL rollout files to extract token usage and session data
Supports native thread resumption via codex resume <thread-id>

This plugin requires Codex CLI. Install from OpenAI’s repository.

Installation

# Install Codex (varies by distribution)
npm install -g codex-cli
# OR
brew install codex
# OR
cargo install codex-cli

# Verify installation
which codex
codex --version

Configuration

Configure in agent-orchestrator.yaml:

plugins:
  agent: codex

projects:
  - name: my-project
    path: ~/code/my-project
    agentConfig:
      model: o4-mini
      permissions: auto-edit
      systemPromptFile: ~/prompts/senior-engineer.txt

Configuration Options

model

string

Codex model (e.g., o4-mini, o3-mini, gpt-4-turbo)

permissions

enum

Approval policy:

skip: Bypass all approvals and sandbox (--dangerously-bypass-approvals-and-sandbox)
auto-edit: Never ask (--ask-for-approval never)
suggest: Ask for untrusted operations only (--ask-for-approval untrusted)

systemPrompt

string

Developer instructions passed via -c developer_instructions=...

systemPromptFile

string

Path to instructions file (preferred for long prompts) Uses -c model_instructions_file=...

Automatic Metadata Updates

The plugin installs shell wrappers in ~/.ao/bin/ that intercept gh and git commands:

Tracked Commands

Command	Metadata Updated
`gh pr create`	`pr` (URL), `status` (pr_open)
`git checkout -b <branch>`	`branch`
`git switch -c <branch>`	`branch`
`gh pr merge`	`status` (merged)

How PATH wrappers work

Plugin prepends ~/.ao/bin to PATH during agent launch
Wrapper scripts intercept gh/git commands
Wrapper strips ~/.ao/bin from PATH and calls the real binary
On success, wrapper parses output and updates metadata via update_ao_metadata()
All other commands pass through transparently

The wrappers are installed once in ~/.ao/bin and reused across all sessions.

Wrapper Scripts

~/.ao/bin/gh

#!/usr/bin/env bash
# Intercepts: gh pr create, gh pr merge
# All other gh commands pass through

real_gh=$(PATH="$clean_path" command -v gh)
exec "$real_gh" "$@"
# (simplified — actual script includes output parsing)

~/.ao/bin/git

#!/usr/bin/env bash
# Intercepts: git checkout -b, git switch -c
# All other git commands pass through

real_git=$(PATH="$clean_path" command -v git)
exec "$real_git" "$@"

~/.ao/bin/ao-metadata-helper.sh

# Provides: update_ao_metadata <key> <value>
# Atomically updates session metadata files

Wrappers are versioned. The plugin only rewrites them if .ao-version marker changes, minimizing disk writes.

Session Introspection

Codex stores session data in date-sharded JSONL files:

~/.codex/sessions/
  2026/
    03/
      04/
        rollout-abc123.jsonl
        rollout-def456.jsonl

Finding Session Files

The plugin:

Recursively scans ~/.codex/sessions/ (max depth 4)
Reads the first 4 KB of each .jsonl file
Matches session_meta entries where cwd equals the workspace path
Returns the most recently modified matching file

For large projects with many Codex sessions, the initial scan can take 1-2 seconds. Results are cached for 30 seconds.

Extracting Data

The plugin streams JSONL files line-by-line (never loads entire file into memory):

interface CodexSessionData {
  model: string | null;          // From session_meta
  threadId: string | null;       // For resume support
  inputTokens: number;           // Aggregated from token_count events
  outputTokens: number;
}

Cost Estimation

Token usage is aggregated from event_msg lines with type: "token_count":

{
  "type": "event_msg",
  "msg": {
    "type": "token_count",
    "input_tokens": 5000,
    "output_tokens": 1200
  }
}

Estimated cost uses GPT-4 Turbo pricing (

2.50/1M input,

10/1M output) as a baseline.

Cost estimates are approximate. For accurate billing, check OpenAI’s usage dashboard.

Usage Examples

Spawn an Agent

ao spawn my-project "Implement user authentication"

The orchestrator:

Resolves the Codex binary (cached after first call)
Creates workspace and sets up wrappers
Launches Codex with prompt included in command
Monitors session file mtime for activity

Resume a Thread

ao resume my-project agent-123

The plugin extracts the threadId from the session JSONL and builds:

codex resume abc-123-def-456 --model o4-mini --ask-for-approval never

Check Session Cost

ao list --verbose

Output:

my-project/agent-123
  Status: active
  Summary: Codex session (o4-mini)
  Cost: $0.45 (50K input, 12K output)

Advanced Features

Binary Resolution

The plugin auto-detects Codex installation on first launch:

Try which codex
Check common locations:
- /usr/local/bin/codex (Homebrew Intel)
- /opt/homebrew/bin/codex (Homebrew ARM)
- ~/.cargo/bin/codex (Cargo)
- ~/.npm/bin/codex (npm global)
Fallback to "codex" (let shell resolve)

Resolved path is cached for the lifetime of the agent instance.

Reasoning Models (o-series)

The plugin auto-detects o-series models and enables reasoning:

if (/^o[34]/i.test(model)) {
  parts.push("-c", "model_reasoning_effort=high");
}

This sets model_reasoning_effort=high for o3/o4 models automatically.

Session File Caching

To avoid redundant filesystem scans, the plugin caches session file paths:

const SESSION_FILE_CACHE_TTL_MS = 30_000;
const sessionFileCache = new Map<string, { path: string | null; expiry: number }>();

Cache is shared across getActivityState() and getSessionInfo() calls.

AGENTS.md Integration

The plugin appends a section to AGENTS.md in each workspace:

## Agent Orchestrator (ao) Session

You are running inside an Agent Orchestrator managed workspace.
Session metadata is updated automatically via shell wrappers.

If automatic updates fail, you can manually update metadata:
```bash
~/.ao/bin/ao-metadata-helper.sh
# Then call: update_ao_metadata <key> <value>

This serves as a secondary signal if PATH wrappers are bypassed.

Troubleshooting

Wrappers not intercepting commands

Cause: PATH not set correctly or wrappers not executableSolution:

Check if ~/.ao/bin is first in PATH:
```
echo $PATH | tr ':' '\n' | head -1
```

Verify wrappers are executable:

ls -l ~/.ao/bin/gh
chmod +x ~/.ao/bin/gh ~/.ao/bin/git

Check if real binaries exist:

which -a gh  # Should show wrapper first, then real binary

Session file not found

Cause: No Codex session created yet, or cwd mismatchSolution:

Check if Codex has created any sessions:
```
ls -lR ~/.codex/sessions/
```

Verify workspace path matches session_meta cwd:

head -5 ~/.codex/sessions/2026/03/04/rollout-*.jsonl | grep session_meta

Wait for Codex to make its first API call (session files are created lazily)

Binary resolution fails

Cause: Codex installed in non-standard locationSolution: Add Codex to PATH or create a symlink:

# Option 1: Add to PATH in shell config
export PATH="/custom/path/to/codex:$PATH"

# Option 2: Symlink to standard location
ln -s /custom/path/to/codex /usr/local/bin/codex

Metadata updates not persisting

Cause: AO_DATA_DIR or AO_SESSION environment variables not setSolution: Check agent environment:

# In agent workspace
echo $AO_DATA_DIR
echo $AO_SESSION

# Should be set by orchestrator during launch

Verify metadata file exists:

ls -l "$AO_DATA_DIR/$AO_SESSION"

Activity detection shows 'idle' when agent is working

Cause: Codex writes to session file in bursts, not continuouslySolution: This is expected. Activity detection uses file mtime, which only updates when Codex makes API calls or writes events. During long reasoning periods (o-series models), the file may not be modified. Check process status with ao status <session> for ground truth.

Comparison with Other Agents

Feature	Codex	Claude Code	Aider	OpenCode
Provider	OpenAI	Anthropic	Aider.chat	OpenCode
Auto-metadata	✅ PATH wrappers	✅ PostToolUse hooks	❌ None	❌ None
Cost Tracking	✅ Full	✅ Full	❌ None	❌ None
Resume Support	✅ Native	✅ Native	❌ None	❌ None
Binary Resolution	✅ Auto	❌ Manual (must be in PATH)	❌ Manual	❌ Manual
Session Files	JSONL (date-sharded)	JSONL (path-encoded)	Markdown	SQLite
Activity Detection	✅ File mtime	✅ JSONL events	⚠️ Git commits	❌ None

Environment Variables

The plugin sets these variables in the agent environment:

AO_SESSION_ID

string

required

Session identifier for metadata lookups

AO_PROJECT_ID

string

Project identifier (set by caller, not the plugin)

AO_ISSUE_ID

string

Issue/ticket identifier if applicable

PATH

string

required

Prepended with ~/.ao/bin to enable command interception

Do not modify PATH in workspace setup scripts (.bashrc, .zshrc) as it may interfere with wrapper priority.

Overview

Runtime Plugins

Agent Plugins

Workspace Plugins

Tracker Plugins

SCM Plugins

Notifier Plugins

Terminal Plugins

Overview

Installation

Configuration

Configuration Options

Automatic Metadata Updates

Tracked Commands

Wrapper Scripts

Session Introspection

Finding Session Files

Extracting Data

Cost Estimation

Usage Examples

Spawn an Agent

Resume a Thread

Check Session Cost

Advanced Features

Binary Resolution

Reasoning Models (o-series)

Session File Caching

AGENTS.md Integration

Troubleshooting

Comparison with Other Agents

Environment Variables

Build docs developers (and LLMs) love

Overview

Runtime Plugins

Agent Plugins

Workspace Plugins

Tracker Plugins

SCM Plugins

Notifier Plugins

Terminal Plugins

Documentation Index

​Overview

​Installation

​Configuration

​Configuration Options

​Automatic Metadata Updates

​Tracked Commands

​Wrapper Scripts

​Session Introspection

​Finding Session Files

​Extracting Data

​Cost Estimation

​Usage Examples

​Spawn an Agent

​Resume a Thread

​Check Session Cost

​Advanced Features

​Binary Resolution

​Reasoning Models (o-series)

​Session File Caching

​AGENTS.md Integration

​Troubleshooting

​Comparison with Other Agents

​Environment Variables

Build docs developers (and LLMs) love

Overview

Installation

Configuration

Configuration Options

Automatic Metadata Updates

Tracked Commands

Wrapper Scripts

Session Introspection

Finding Session Files

Extracting Data

Cost Estimation

Usage Examples

Spawn an Agent

Resume a Thread

Check Session Cost

Advanced Features

Binary Resolution

Reasoning Models (o-series)

Session File Caching

AGENTS.md Integration

Troubleshooting

Comparison with Other Agents

Environment Variables