OpenAI Codex Integration

OpenAI Codex can leverage supyagent tools through the CLI execution mode. While Codex has its own agent loop and file system access, supyagent extends its capabilities with custom tools and cloud integrations.

Execution Mode Integration

The primary integration point is supyagent run, which provides a stateless input-to-output interface that any external agent can call:

supyagent run myagent "Search the codebase for all TODO comments and categorize them"

Codex can invoke this command to delegate complex tasks to a supyagent that has access to specialized tools.

JSON Output

For machine-parseable output, use the --output json flag:

supyagent run myagent "List all open GitHub issues" --output json

This returns structured JSON that Codex can parse and incorporate into its reasoning.

Tool Invocation via CLI

Codex can also call supypowers tools directly, without going through a supyagent agent:

# Search files
supypowers run search:search '{"pattern": "TODO", "glob": "*.py"}'

# Read a file
supypowers run files:read_file '{"path": "src/main.py"}'

# Make an HTTP request
supypowers run web:http_request '{"method": "GET", "url": "https://api.example.com/data"}'

Every call returns structured JSON:

{"ok": true, "data": {"matches": [...]}}

Codex Configuration

To make supyagent tools available in a Codex session, add the relevant commands to your Codex instructions or system prompt:

You have access to supyagent tools via the CLI. To use them:

1. Run a specific tool:
   supypowers run <script>:<function> '<json_input>'

2. List available tools:
   supypowers docs --format md

3. Delegate a complex task to an agent:
   supyagent run <agent_name> "<task description>"

All tool outputs are JSON: {"ok": true, "data": ...} or {"ok": false, "error": "..."}

Cloud Tools in Codex

If you have Supyagent Cloud integrations connected, Codex can access them through a supyagent agent:

# Send an email via the agent
supyagent run assistant "Send an email to alice@company.com about the deployment status"

# Check Slack messages
supyagent run assistant "What are the latest messages in the #engineering channel?"

Example Workflow

A typical Codex + supyagent workflow:

1. Codex identifies it needs to check deployment status
2. Codex runs: supypowers run web:http_request '{"url": "https://api.myapp.com/health"}'
3. Codex parses the JSON response
4. Codex runs: supyagent run notifier "Post to Slack #ops: deployment health check passed"
5. Codex continues with its task

MCP Support (Roadmap)

Future versions of supyagent will include a native MCP (Model Context Protocol) server. This will allow Codex and other MCP-compatible clients to discover and call supypowers tools through the standardized MCP interface, without needing CLI invocation.

See MCP Protocol for details on the roadmap.

What's Next

• Execution Mode -- Deep dive into supyagent run for automation
• Claude Code -- SKILL.md integration for Claude Code
• MCP Protocol -- Future MCP server support