Skip to content

README.md

Latest commit

 

History

History
75 lines (51 loc) · 2.61 KB

README.md

File metadata and controls

75 lines (51 loc) · 2.61 KB

ACP adapter for Codex CLI

npm version

Use OpenAI Codex from Agent Client Protocol clients.

codex-acp is a stdio ACP agent server. It starts the Codex App Server, translates ACP requests into Codex operations, and maps Codex events back into the client.

Features

  • ChatGPT, API key, and client-provided custom gateway authentication.
  • Model, reasoning effort, fast mode, approval, and sandbox mode configuration.
  • Text prompts, embedded context, images, resource links, and additional workspace directories.
  • Shell command, file change, permission request, MCP tool call, terminal output, reasoning, plan, web search, image generation, image view, token usage, and review events.
  • Client-provided MCP servers over command-based stdio config and HTTP transport.
  • Slash commands: /status, /mcp, /skills, /review, /review-branch, /review-commit, /compact, and /logout, as well as configured skills.

Installation

Run the published package directly:

npx -y @agentclientprotocol/codex-acp

Or install it globally:

npm install -g @agentclientprotocol/codex-acp
codex-acp --version

The npm package includes a compatible @openai/codex dependency. Set CODEX_PATH only when you want the adapter to run a different Codex binary:

CODEX_PATH=/path/to/codex npx -y @agentclientprotocol/codex-acp

Authentication

The adapter advertises ACP auth methods during initialization. Clients can authenticate with:

  • ChatGPT login.
  • OpenAI API key.
  • A custom OpenAI-compatible gateway, when the client opts in to the gateway auth capability.

Runtime options

  • CODEX_PATH - run a specific Codex executable instead of the bundled package dependency.
  • CODEX_CONFIG - JSON object merged into the Codex session config.
  • MODEL_PROVIDER - model provider to pass to Codex for new sessions.
  • DEFAULT_AUTH_REQUEST - ACP auth request JSON used when Codex requires authentication.
  • INITIAL_AGENT_MODE - initial mode id: read-only, agent, or agent-full-access.
  • APP_SERVER_LOGS - directory for adapter logs.

Development

npm install
npm run start
npm run typecheck
npm test

Build standalone binaries in dist/bin with:

npm run bundle:all

See readme-dev.md for local client configuration, binary packaging, and Codex type regeneration.

License

By contributing, you agree that your contributions will be licensed under the Apache 2.0 License.