Skip to content

codex-agent.md

Latest commit

 

History

History
96 lines (78 loc) · 5.02 KB

codex-agent.md

File metadata and controls

96 lines (78 loc) · 5.02 KB

Codex Agent Tool

The codex-agent tool provides integration with the Codex CLI through MCP. It enables AI agents to leverage Codex's capabilities for code analysis, generation, and assistance. The tool exclusively uses the codex exec command for non-interactive execution.

Requires the Codex CLI to be installed and authenticated.

Parameters

  • prompt (string, required): A clear, concise prompt to send to Codex CLI to instruct the AI Agent to perform a specific task. Supports @file, @directory/ syntax for file references.
  • override-model (string, optional): Model to override the default. No default model is provided, allowing Codex to use user's configured default.
  • sandbox (string, optional): Sandbox policy for execution security. Options: read-only, workspace-write, danger-full-access. WARNING: Controls execution security context.
  • full-auto (boolean, optional): Enable low-friction sandboxed automatic execution. In exec mode, implies --sandbox workspace-write. Defaults to false.
  • yolo-mode (boolean, optional): DANGER: Bypass all approvals and sandbox restrictions (maps to --dangerously-bypass-approvals-and-sandbox). Use with extreme caution. Defaults to false.
  • resume (boolean, optional): Continue the most recent session using --last flag. Defaults to false.
  • session-id (string, optional): Specify a session identifier for resuming specific sessions.
  • profile (string, optional): Configuration profile to use from config.toml.
  • config (array of strings, optional): Configuration overrides in key=value format. Supports dotted path notation for nested values with JSON parsing.
  • images (array of strings, optional): Image files to attach to the prompt. Multiple files supported.
  • cd (string, optional): Working directory for Codex execution. Directory must exist.
  • skip-git-repo-check (boolean, optional): Skip git repository validation checks. Defaults to false.

Environment Variables

  • ENABLE_ADDITIONAL_TOOLS: A comma-separated list of additional tools to enable. Must include codex-agent to use this tool.
  • AGENT_TIMEOUT: (optional) The timeout in seconds for the codex command. Defaults to 300.
  • AGENT_MAX_RESPONSE_SIZE: (optional) Maximum response size in bytes. Defaults to 2097152 (2MB).
  • AGENT_PERMISSIONS_MODE: (optional) Controls whether yolo-mode parameter is exposed and its default behaviour. Options: yolo (force yolo-mode on, hide parameter), disabled/false (force yolo-mode off, hide parameter). If unset, agent can control yolo-mode via parameter. This controls the --dangerously-bypass-approvals-and-sandbox flag.

Security Features

  • Response Size Limits: Configurable maximum response size prevents excessive memory usage and potential DoS conditions
  • Input Validation: Comprehensive parameter validation and type checking
  • Process Isolation: Agent execution runs in isolated subprocess with proper timeout controls
  • Timeout Controls: Configurable timeout limits prevent runaway processes
  • Error Handling: Secure error handling that doesn't expose sensitive system information
  • Sandbox Support: Full support for Codex's sandbox policies for execution security
  • Directory Validation: Validates working directory exists before execution

Examples

Basic Code Analysis

{
  "prompt": "Please review this function for efficiency and suggest optimizations: @myfile.py"
}

Secure Code Generation

{
  "prompt": "Generate a Python function to validate email addresses",
  "sandbox": "read-only"
}

Session Continuation

{
  "prompt": "Thanks for the previous suggestions. Can you now help me implement the caching layer you mentioned?",
  "resume": true
}

Full Auto Mode

{
  "prompt": "Create a REST API endpoint for user authentication with proper error handling",
  "full-auto": true
}

Custom Model and Directory

{
  "prompt": "Analyse the project structure and suggest architectural improvements",
  "override-model": "claude-3.5-sonnet",
  "cd": "/path/to/project"
}

Common Patterns

  • Use resume: true to continue conversations in the same context
  • Set sandbox: "read-only" for safe code analysis without execution
  • Use full-auto: true for streamlined development with automatic permissions
  • Specify override-model to use different Claude models for specific tasks
  • Use @file syntax in prompts to reference specific files
  • Set cd parameter to change working directory for project analysis

Troubleshooting

  • Codex CLI not found error: Install Codex CLI and ensure it's available in your PATH
  • Authentication errors: Ensure you are authenticated and Codex is properly configured
  • Tool is not enabled: Set ENABLE_ADDITIONAL_TOOLS environment variable to include 'codex-agent'
  • Permission denied errors: Check your sandbox settings. Use 'sandbox: workspace-write' or 'full-auto: true' for write operations
  • Session not found errors: Verify the session-id exists or use 'resume: true' without session-id to resume the last session