codex
Send tasks to an autonomous agent that handles complex software engineering work, including file operations, shell commands, codebase searches, and end-to-end project execution.
Instructions
Send a task to an autonomous Codex agent. It reads/writes files, runs shell commands, searches codebases, and handles complex software engineering tasks end-to-end. Returns the result text plus a thread_id for follow-ups via codex_reply.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | Yes | Task or question for Codex | |
| cwd | No | Working directory (overrides CODEX_CWD) | |
| model | No | Model override (e.g. "gpt-5-codex", "o3", "codex-1") | |
| additionalDirs | No | Extra directories the agent can access for this invocation | |
| effort | No | Reasoning effort override | |
| sandboxMode | No | Sandbox mode override (can only tighten, never loosen) | |
| approvalPolicy | No | Approval policy override (can only tighten, never loosen) | |
| networkAccess | No | Enable network access from sandbox | |
| webSearchMode | No | Web search mode | |
| instructions | No | Additional instructions (prepended to prompt) |
Implementation Reference
- src/tools/query.ts:151-174 (handler)The tool named "codex" (by default) is registered here. The tool handler calls `runQuery`, which uses the `Codex` SDK to manage the interaction.
server.registerTool(toolName, { description: toolDescription, inputSchema: z.object({ prompt: z.string().describe("Task or question for Codex"), cwd: z.string().optional().describe("Working directory (overrides CODEX_CWD)"), model: z.string().optional().describe('Model override (e.g. "gpt-5-codex", "o3", "codex-1")'), additionalDirs: z.array(z.string()).optional().describe("Extra directories the agent can access for this invocation"), effort: z.enum(["minimal", "low", "medium", "high", "xhigh"]).optional().describe("Reasoning effort override"), sandboxMode: z.enum(["read-only", "workspace-write"]).optional().describe("Sandbox mode override (can only tighten, never loosen)"), approvalPolicy: z.enum(["on-failure", "on-request", "untrusted"]).optional().describe("Approval policy override (can only tighten, never loosen)"), networkAccess: z.boolean().optional().describe("Enable network access from sandbox"), webSearchMode: z.enum(["disabled", "cached", "live"]).optional().describe("Web search mode"), instructions: z.string().optional().describe("Additional instructions (prepended to prompt)"), }), }, async ({ prompt, cwd, model, additionalDirs, effort, sandboxMode, approvalPolicy, networkAccess, webSearchMode, instructions }) => { try { const result = await runQuery(prompt, { cwd, model, additionalDirs, effort, sandboxMode, approvalPolicy, networkAccess, webSearchMode, instructions, }, baseConfig, apiKey); return formatResult(result); } catch (error) { return formatError(error); } });