OpenAI Codex CLI setup - Aden Hive Documentation

This guide documents Codex CLI support in Hive and how to use it alongside existing Claude Code and Cursor workflows.

What This Adds

Codex support includes:

A .codex/ configuration model
MCP server connections for agent-builder and tools
Instruction files mirroring Hive build/test workflows

This aligns with the same workflow goals as existing coding-agent integrations.

Expected Project Structure

.codex/
├── config.json
├── mcp_servers.json
└── instructions/
    ├── hive.md
    ├── hive-create.md
    ├── hive-concepts.md
    ├── hive-patterns.md
    ├── hive-test.md
    └── hive-credentials.md

MCP Server Configuration

Use .codex/mcp_servers.json:

{
  "mcpServers": {
    "agent-builder": {
      "command": "python",
      "args": ["-m", "framework.mcp.agent_builder_server"],
      "cwd": "core",
      "env": {
        "PYTHONPATH": "../tools/src"
      }
    },
    "tools": {
      "command": "python",
      "args": ["mcp_server.py", "--stdio"],
      "cwd": "tools",
      "env": {
        "PYTHONPATH": "src"
      }
    }
  }
}

Instruction Files

Mirror the existing Hive skill set into Codex instruction files:

hive for full build workflow
hive-create for creation flow
hive-concepts for conceptual guidance
hive-patterns for architecture best practices
hive-test for test-generation and validation
hive-credentials for credential setup/sync guidance

Keep instruction intent consistent with Claude/Cursor variants, but adapt syntax to Codex’s instruction model.

Verification Checklist

After setup, verify:

Codex can connect to agent-builder MCP server.
Codex can connect to tools MCP server.
Hive instruction workflows are invokable from Codex.
End-to-end agent creation/testing runs successfully.

Quick Validation Steps

# From hive root
./quickstart.sh

# Then launch Codex CLI and verify MCP-backed workflows
codex

Use a small test goal first and confirm:

graph generation works
test scaffolding is created
tool calls route through MCP correctly

Troubleshooting

MCP server not visible

Confirm .codex/mcp_servers.json path and JSON validity
Validate cwd and PYTHONPATH values
Ensure dependencies are installed via ./quickstart.sh

Instructions not recognized

Confirm files exist under .codex/instructions/
Verify naming matches expected invocation names

Python command failures

Run from Hive root
Ensure Python/uv environment is healthy

​What This Adds

​Expected Project Structure

​MCP Server Configuration

​Instruction Files

​Verification Checklist

​Quick Validation Steps

​Troubleshooting

​MCP server not visible

​Instructions not recognized

​Python command failures

​Related