agent-codex

agent-codex Plugin

A Claude Code plugin that integrates with OpenAI Codex CLI for delegation, review, and research workflows.

What This Plugin Provides

• Commands for Codex delegation and configuration
• Agents for delegation, background work, and research
• Skills for Codex integration and MCP setup
• Hook prompts for safer Codex usage
• Bootstrap templates under .codex/

Prerequisites

1. Install Codex CLI:

npm install -g @openai/codex

2. Authenticate:

codex login

3. Node.js is required for npx-based MCP servers.

Installation

Install from GitHub (recommended)

git clone https://github.com/mustafaakben/codex-agent-plugin.git
cd codex-agent-plugin
claude --plugin-dir .

Plugin Cloud / Marketplace install

Add the marketplace source:

claude plugin marketplace add https://github.com/mustafaakben/codex-agent-plugin
claude plugin marketplace list

Install from this marketplace:

claude plugin install agent-codex@mustafaakben-marketplace

Update/uninstall:

claude plugin marketplace update mustafaakben-marketplace
claude plugin update agent-codex
claude plugin uninstall agent-codex

This repo includes .claude-plugin/marketplace.json, so marketplace install works directly from GitHub.

Manual project layout (fallback)

If you manually place plugin files in a project, keep this structure:

<plugin-root>/
  .claude-plugin/plugin.json
  commands/
  agents/
  skills/
  hooks/
  scripts/
  .mcp.json

Commands

Installed plugins commonly expose namespaced commands. Use:

• /agent-codex:codex <task>
• /agent-codex:codex-config [action]
• /agent-codex:codex-review [target] [focus]
• /agent-codex:codex-mcp-search <query>
• /agent-codex:codex-mcp-add <server>

Configuration Model

Files shipped by this plugin repo

• .codex/config.template.toml
• .codex/recommended-mcps.toml

File generated in target projects

• .codex/config.toml

config.toml is created when users explicitly initialize/approve bootstrap.

Defaults

model = "gpt-5.4"
model_reasoning_effort = "xhigh"
sandbox_mode = "workspace-write"
approval_policy = "on-request"

Curated MCP Servers

The curated, verified set used in templates/docs:

• context7
• playwright
• postgres
• filesystem
• github

All are disabled by default in template config.

Safety Behavior

• Do not auto-create .codex/config.toml at plugin activation.
• Ask for confirmation before creating or modifying project config files.
• Ask before enabling MCP blocks in config.

Validation

Validate plugin manifest:

claude plugin validate .

License

MIT (see LICENSE)