The CodexAgent implements the Agent interface for the Codex CLI, a tool designed for AI-assisted coding tasks. It manages the lifecycle of the agent within a Runtime, including Node.js bootstrapping, npm-based installation, provider synthesis for OpenAI-compatible endpoints, and sophisticated session recovery from JSONL event streams.
The CodexAgent allows skill-up to execute evaluations using the Codex engine. It specializes in:
@openai/codex package..jsonl session files to extract high-fidelity transcripts and token usage data.Sources: internal/agent/codex.go24-50
The installation process follows a "probe-merge-exec" lifecycle. The agent first ensures a compatible Node.js runtime exists before installing the Codex CLI.
Before Codex can be installed, ensureNodeRuntime is called to verify that node and npm are available. If missing, it executes a bootstrap script that installs nvm and Node.js version 22.
NVM_NODEJS_ORG_MIRROR and NPM_CONFIG_REGISTRY for environments with restricted internet access internal/agent/node_install.go26-34nvm installer using a hardcoded SHA256 checksum internal/agent/node_install.go20 internal/agent/node_install.go58Once Node is ready, the agent installs the Codex package globally under $HOME/.local.
0.80.0 internal/agent/codex.go30$HOME/.local/bin and $HOME/.nvm/current/bin (for the node shebang) and merges them into the execution environment via codexExecPathProbeCmd internal/agent/codex.go50-53Sources: internal/agent/codex.go75-94 internal/agent/node_install.go79-98 internal/agent/node_install.go37-71
Codex requires a provider configuration to communicate with LLMs. skill-up simplifies this by synthesizing a provider named skill-up-openai when a custom BaseURL is provided. This is necessary because the literal openai key in Codex is a built-in config that does not reliably merge user overrides internal/agent/codex.go34-40
| Parameter | Logic | Resulting Codex Flag |
|---|---|---|
| Model Name | From Config.ModelName | -m <model> |
| Base URL | If set, triggers synthetic provider | model_providers.skill-up-openai.base_url |
| API Key | Resolved from OPENAI_API_KEY | model_providers.skill-up-openai.env_key |
| Wire API | Forced to chat for compatibility | model_providers.skill-up-openai.wire_api="chat" |
Sources: internal/agent/codex.go182-221 internal/agent/codex_test.go146-170
The execution flow involves streaming JSON events from the Codex CLI and subsequently recovering a detailed session file for the final report.
This diagram maps the natural language concepts of "Running an Agent" to the specific code entities in internal/agent/codex.go.
Sources: internal/agent/codex.go250-320 internal/agent/session_lookup.go89-107
For large prompts exceeding SKILL_UP_PROMPT_INLINE_MAX_BYTES (default 32KB), CodexAgent uses deliverPrompt to upload the instruction as a file to .skill-up/prompts/prompt.txt in the runtime workspace instead of passing it as a command-line argument internal/agent/prompt_delivery.go15-16 internal/agent/prompt_delivery.go54-57
Codex writes a detailed execution trace to ~/.codex/projects/<workspace-key>/*.jsonl. After the process exits, CodexAgent performs the following:
findAgentSessionJSONL to find the most recently modified .jsonl file associated with the workspace internal/agent/session_lookup.go89-107Runtime to the local artifactDir internal/agent/session_lookup.go48parseSessionFile iterates through the JSONL lines, extracting:
agent_message: The final response text internal/agent/codex.go44function_call / function_call_output: Tool interactions for the transcript internal/agent/codex.go45-46token_count: High-water mark for input and output tokens internal/agent/codex.go47By default, Codex runs in a restricted mode using --sandbox workspace-write internal/agent/codex.go31 If the bypass_sandbox kwarg is set to true, the agent appends the codexBypassSandbox flag (--dangerously-bypass-approvals-and-sandbox) to the command line internal/agent/codex.go32 internal/agent/codex.go237-239
Codex supports the Model Context Protocol (MCP). The CodexAgent facilitates server installation via codex mcp add.
If an MCP server requires custom HTTP headers (e.g., for authentication), CodexAgent generates a bridge script using npx mcp-remote.
buildCodexMCPRemoteBridgeScript that executes exec npx mcp-remote "$1" with --header arguments internal/agent/codex.go187-210stdio transport command within Codex via buildCodexMCPRemoteInstallCmd, allowing it to proxy requests to the remote endpoint while managing secrets via environment variables internal/agent/codex.go176-184This diagram bridges the MCP configuration to the bridge script implementation.
Sources: internal/agent/codex.go152-185 internal/agent/codex.go187-223
| Symbol | Location | Description |
|---|---|---|
codexBypassSandbox | internal/agent/codex.go32 | Flag to disable Codex's internal sandbox. |
codexOpenAIOverrideProvider | internal/agent/codex.go40 | The synthetic provider ID skill-up-openai. |
buildCodexRunCmd | internal/agent/codex.go330 | Constructs the full codex exec command string. |
parseSessionFile | internal/agent/codex.go400 | Parses the JSONL trace into a transcript.Transcript. |
ensureNodeRuntime | internal/agent/node_install.go79 | Bootstraps Node.js environment in the runtime. |
deliverPrompt | internal/agent/prompt_delivery.go33 | Orchestrates prompt delivery via CLI args or workspace files. |
Sources: internal/agent/codex.go28-50 internal/agent/node_install.go14-35 internal/agent/prompt_delivery.go1-67
Refresh this wiki