Self-improving AI Employees for everyone
Codex (codex_agent)
| Field | Value |
|---|---|
| Category | specialized_agents |
| Plugin | server/nodes/agent/codex_agent/__init__.py::CodexAgentNode.execute_op (dispatch via BaseNode.execute()) |
| Backend service | server/services/cli_agent/service.py::AICliService.run_batch (provider "codex") |
| Connection collection | server/services/plugin/edge_walker.py::collect_agent_connections |
| Tests | server/tests/nodes/test_specialized_agents.py |
| Dual-purpose tool | no |
Purpose
Runs N parallel OpenAI Codex CLI sessions over a list of CodexTaskSpec
tasks via AICliService.run_batch("codex", ...). Sandbox-first companion to
claude_code_agent: the sandbox is enforced by Codex itself (not OpenCompany),
and each task runs in its own git worktree. Codex exposes no
session/resume/budget/turns surface — only sandbox + ask_for_approval are
task-level overrides. The common case is a single prompt that synthesises a
one-task batch.
Inputs (handles)
Standard std_agent_handles() topology.
| Handle | Connection type | Required | Purpose |
|---|---|---|---|
input-main |
input/main | no | Prompt fallback: _infer_prompt_from_inputs reads outputs[source].message/text/content/prompt/str |
input-skill |
input/skill | no | Connected skill names collected and passed to run_batch |
input-memory |
input/memory | no | Collected by edge-walker but unused (Codex has no resume surface) |
input-tools |
input/tools | no | Collected by edge-walker (5-tuple) but discarded here |
input-task |
input/task | no | Collected but discarded |
Parameters
CodexAgentParams (extra="ignore"):
| Name | Type | Default | Required | displayOptions.show | Description |
|---|---|---|---|---|---|
tasks |
CodexTaskSpec[] |
[] |
no | - | List of Codex tasks (max 5 concurrent) |
prompt |
string | "" |
no | - | Single-prompt fallback used only when tasks is empty (4 rows) |
model |
string | gpt-5.2-codex |
no | - | Default model for tasks that don't override |
sandbox |
string | workspace-write |
no | - | read-only / workspace-write / danger-full-access |
ask_for_approval |
string | never |
no | - | untrusted / on-request / never |
system_prompt |
string|null | None |
no | - | System prompt (3 rows) |
working_directory |
string|null | None |
no | - | Git repo root; defaults to workflow workspace dir |
max_parallel |
int | 5 |
no | - | 1-20 concurrency cap |
allowed_credentials |
string[] | [] |
no | - | Credential names the CLI may fetch via MCP |
Outputs (handles)
Output = CodexAgentOutput (extra="allow") — aggregated batch shape.
| Handle | Shape | Description |
|---|---|---|
output-main / output-top |
object | Batch result (see payload below) |
Output payload
{
success: boolean; // result.n_failed == 0
n_tasks: number;
n_succeeded: number;
n_failed: number;
total_cost_usd: null; // always None for Codex
wall_clock_ms: number;
tasks: SessionResultModel[];
provider: "codex";
timestamp: string;
response: string | null; // populated when len(tasks) == 1
}
Note: codex_agent is not registered in
server/services/node_output_schemas.py::_AGENT_TYPES, so the frontend Input
Data panel has no declared output schema for it (falls back to live execution
data or empty state).
Logic Flow
flowchart TD
A[CodexAgentNode.execute_op] --> B[broadcast executing]
B --> C{params.tasks empty?}
C -- yes --> D[prompt = params.prompt<br/>else _infer_prompt_from_inputs]
D --> E{prompt empty?}
E -- yes --> F[raise RuntimeError<br/>provide tasks or prompt]
E -- no --> G[Build single CodexTaskSpec]
C -- no --> H[Apply node defaults<br/>model/system_prompt per task]
G --> I[collect_agent_connections<br/>skill names]
H --> I
I --> J[Resolve workspace_dir + repo_root]
J --> K[AICliService.run_batch codex]
K --> L[Aggregate result -> dict payload]
L --> M[broadcast success/warning]
Decision Logic
- Prompt resolution:
params.promptwins; otherwise_infer_prompt_from_inputsscansinput-main(or untagged) edges and readsoutputs[source].message/text/content/prompt/str. Empty ->RuntimeError. - Single-task synthesis: empty
tasksbuilds oneCodexTaskSpecfromprompt+model+sandbox+ask_for_approval+system_prompt. - Batch defaulting: non-empty
tasksget node-levelmodel/system_promptfilled where the task didn't override. - No memory/resume/budget/turns: Codex has no session surface; memory / tools / task data are collected by the edge-walker but discarded.
Side Effects
- Subprocess spawn:
AICliService.run_batch("codex", ...)spawns the Codex CLI per task (per-task git worktree isolation; sandbox enforced by Codex). - Broadcasts:
StatusBroadcaster.update_node_status-- executing ("Starting Codex batch..."), thensuccess/warningon completion. - File I/O: per-task git worktrees under the workflow workspace dir.
- External API: indirect -- the Codex CLI calls OpenAI internally.
External Dependencies
- Binaries: the OpenAI Codex CLI (provider
"codex"in the cli_agent framework). - Python packages: the
services/cli_agent/framework. - Credentials: Codex handles its own authentication; OpenCompany does not
inject an API key here.
allowed_credentialsgates what the CLI may fetch via the OpenCompany MCP bridge.
Edge cases & known limits
- No prompt / tasks ->
RuntimeError: whentasksis empty AND no input yields a prompt,execute_opraisesRuntimeError(full traceback path — notNodeUserErrorlikeclaude_code_agent). total_cost_usdis alwaysNone: Codex does not surface per-run cost.- No output schema registration: see Outputs note above.
Related
- Dedicated-path siblings:
claudeCodeAgent,rlmAgent - Generic pattern:
_pattern.md - Architecture: CLI Agent Framework