Codex Tool
Relevant source files
The following files were used as context for generating this wiki page:
The Codex Tool is a core component of the SuperAgent MCP server, designed to interface with the Codex CLI agent. It enables parallel execution of multiple tasks, ranging from code analysis and modification to system exploration and documentation. As an MCP-invoked agent, it operates with full system access and elevated permissions to automate complex development workflows.
Sources: README.md:3-5, src/server.ts:60-61, src/codexAgent.ts:133-145
Architecture and Invocation
The Codex Tool functions as a wrapper around the codex command-line interface. It utilizes Node.js spawn to execute the CLI in a separate process, managing input via stdin and capturing output through stdout and stderr.
Invocation Logic
When a user invokes the tool through an MCP client, the server builds a command with specific flags to ensure autonomous operation.
The diagram shows the sequential flow from an MCP request to the final result return.
Sources: src/codexAgent.ts:148-161, src/server.ts:98-105
Default CLI Flags
The tool always includes the following flags during execution:
--json: Enables structured output for event parsing.--skip-git-repo-check: Allows execution outside of initialized git repositories.--dangerously-bypass-approvals-and-sandbox: Grants full permissions for unrestricted system access.
Sources: src/codexAgent.ts:47-52
Data Models and Schemas
The interaction with the Codex Tool is governed by Zod-based schemas that define required inputs and expected outputs.
Input Parameters
The tool accepts a batch of inputs, allowing for concurrent task processing.
| Parameter | Type | Description |
|---|---|---|
inputs | Array | A list of AgentPromptSchema objects containing the prompt and configuration. |
concurrency | number | Number of tasks to run in parallel (1-10, default: 1). |
workingDirectory | string | Optional path where the agent should execute. |
agent | string | Name of a specialized agent (e.g., 'python-expert'). |
timeoutMs | number | Maximum execution time (default: 30 minutes). |
Sources: src/types.ts:5-15, src/types.ts:18-25, src/server.ts:60-64
Result Structure
Successful execution returns an AgentInvocationSuccess object containing metadata and the agent's textual response.
Sources: src/types.ts:45-56
Process Management and Execution
The tool includes robust mechanisms for handling long-running tasks and system resource cleanup.
Event Parsing
Codex produces output as a stream of JSON lines. The parseAssistantReply function iterates through these events to reconstruct the final message from agent_message or assistant_message types.
The sequence diagram illustrates how the server communicates with the CLI and extracts relevant textual data from the JSON stream.
Sources: src/codexAgent.ts:68-118, src/codexAgent.ts:199-200
Lifecycle and Safety
- Signal Handling: Child processes are registered with a
processManagerto ensure they are killed if the MCP server shuts down. - Timeouts: A default timeout of 30 minutes is enforced, after which the
SIGKILLsignal is sent to the process. - Meta Instructions: Every prompt is prepended with a system instruction defining the agent as "MCP-invoked" and emphasizing conciseness and restraint.
Sources: src/codexAgent.ts:44, src/codexAgent.ts:124-132, src/codexAgent.ts:172-180
Specialized Agents
While Codex is a general-purpose agent, the tool supports specialization through the agent parameter. These agents are defined in Markdown files within ~/.superagent/agents.
General-Purpose Capabilities
By default, the Codex agent follows a "General-Purpose" mindset:
- Code Search: Systematic exploration across large codebases.
- Precision: Does exactly what is asked, nothing more.
- File Management: Prefers editing existing files over creating new ones.
Sources: agents/general-purpose.md:14-25, src/agentLoader.ts:11-13
Summary
The Codex Tool provides a high-performance, parallelized interface for the Codex CLI within the SuperAgent MCP ecosystem. It leverages structured JSON event parsing and strict process management to deliver reliable code analysis and system manipulation capabilities to MCP clients.
Sources: README.md:3-8, src/server.ts:241-245