codex-agentapi

coder/agentapi compatible HTTP API server using @openai/codex-sdk

Features

• ✅ Full coder/agentapi compatibility - Implements the standard agent API specification
• 🤖 OpenAI Codex SDK integration - Powered by @openai/codex-sdk
• 🔌 MCP servers support - Full Model Context Protocol server configuration
• 🎨 Claude Code Skills - Integrates with Claude Code plugin system
• 📡 Real-time updates - Server-Sent Events (SSE) for streaming responses
• 📄 Message pagination - Multiple pagination strategies (limit, around, cursor-based)
• 🎯 TypeScript - Strict type checking throughout
• 🧪 Well-tested - Comprehensive test coverage with Vitest

Installation

npm install -g @takutakahashi/codex-agentapi

Or with Bun:

bun install -g @takutakahashi/codex-agentapi

Quick Start

1. Set up environment variables

Create a .env file:

OPENAI_API_KEY=your-api-key-here
PORT=9000
HOST=localhost
LOG_LEVEL=info

2. (Optional) Configure MCP servers and Skills

Create .claude/config.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"],
      "env": {}
    }
  },
  "plugins": {
    "example-skill": {
      "enabled": true,
      "config": {}
    }
  }
}

3. Start the server

codex-agentapi

Or for development:

bun run dev

The server will start at http://localhost:9000.

API Endpoints

Health Check

GET /health

Returns server health status.

Agent Status

GET /status

Returns the current agent status (running or stable).

Send Message

POST /message
Content-Type: application/json

{
  "content": "Fix the bug in main.ts",
  "type": "user"
}

Sends a message to the agent. Returns immediately while processing continues asynchronously.

Get Messages

GET /messages?limit=10&direction=tail

Retrieves conversation messages with pagination support, including tool result messages.

Pagination options:

• limit + direction (head/tail): Get first/last N messages
• around + context: Get messages around a specific ID
• after / before: Cursor-based pagination

Tool Status

GET /tool_status

Returns currently active tool executions.

Server-Sent Events

GET /events

Subscribe to real-time updates via SSE.

Event types:

• message: New user/assistant message
• tool_start: Tool execution started
• tool_end: Tool execution completed
• status_change: Agent status changed
• turn_completed: Turn finished with usage info
• error: Error occurred

Actions

GET /action

Get pending actions (questions, plans).

POST /action
Content-Type: application/json

{
  "type": "stop_agent"
}

Send action response (answer question, approve plan, stop agent).

Configuration

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | OPENAI_API_KEY | - | OpenAI API key (required) | | PORT | 9000 | Server port | | HOST | localhost | Server host | | WORKING_DIRECTORY | . | Agent working directory | | LOG_LEVEL | info | Log level (debug/info/warn/error) |

Claude Config

The server reads .claude/config.json from:

1. Current working directory: ./.claude/config.json
2. Home directory: ~/.claude/config.json

Development

Prerequisites

• Node.js 18+
• Bun (recommended) or npm

Install dependencies

bun install

Run in development mode

bun run dev

Build

bun run build

Run tests

bun test

Run tests with coverage

bun run test:coverage

Lint

bun run lint

Architecture

codex-agentapi/
├── src/
│   ├── app/               # App wiring (server + main)
│   ├── http/              # HTTP layer (routes + validation)
│   ├── application/       # Use cases / domain services
│   ├── infrastructure/    # Adapters (MCP/skills/Codex config)
│   ├── shared/            # Cross-cutting concerns
│   └── types/             # TypeScript types
└── bin/
    └── cli.js             # CLI entry point

Differences from claude-agentapi

| Feature | claude-agentapi | codex-agentapi | |---------|----------------|----------------| | Agent SDK | @anthropic-ai/claude-agent-sdk | @openai/codex-sdk | | Provider | AWS Bedrock / Anthropic API | OpenAI Codex | | Runtime | Node.js/Bun | Bun (recommended) |

Publishing

This package is automatically published to npm when a new release is created on GitHub.

Steps to publish a new version:

1. Create and push a tag:

   git tag v1.0.0
   git push origin v1.0.0

2. Create a GitHub Release:

   gh release create v1.0.0 --title "v1.0.0" --notes "Release notes here"

3. Automated workflow:

   • GitHub Actions will automatically:
     • Update package.json version
     • Run tests and build
     • Publish to npm
     • Update release notes

Manual publish (if needed):

npm login
npm publish --access public

License

MIT

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Links

• OpenAPI Specification
• Design Document
• Original Implementation