What's different in Codexel?

Codexel is a fork of upstream Codex CLI with extra UX and workflow improvements. Recent highlights include:

• Plan Mode: /plan with plan approval, plan variants, and automatic execution after approval.
• ask_user_question: a tool to ask structured multiple-choice clarifying questions.
• spawn_subagent: a read-only parallel research tool surfaced in the TUI (with live activity and token usage).
• TUI improvements for streaming status, tool visibility, and long-running work.
• Isolated state by default in ~/.codexel (separate from the legacy ~/.codex).
• Packaging and update-check fixes for Codexel's release channels.

For the full list of Codexel-only changes, see CHANGELOG.md.

Quickstart

Install

Install globally with your preferred package manager. If you use npm:

npm install -g @ixe1/codexel

Alternatively, if you use Homebrew:

brew install --cask codexel

Then run codexel:

codexel

If you're running into upgrade issues with Homebrew, see the FAQ entry on brew upgrade codexel.

Each GitHub Release contains many executables, but in practice, you likely want one of these:

• macOS
  • Apple Silicon/arm64: codexel-aarch64-apple-darwin.tar.gz
  • x86_64 (older Mac hardware): codexel-x86_64-apple-darwin.tar.gz
• Linux
  • x86_64: codexel-x86_64-unknown-linux-musl.tar.gz
  • arm64: codexel-aarch64-unknown-linux-musl.tar.gz

Each archive contains a single entry with the platform baked into the name (e.g., codexel-x86_64-unknown-linux-musl), so you likely want to rename it to codexel after extracting it.

Authenticate

Run codexel and select Sign in with ChatGPT, or use an OpenAI API key. If you're not sure which one to use, start with ChatGPT sign-in and see the authentication guide.

If you previously used a usage-based billing API key with older versions, see the migration steps.

Configure (optional)

Codexel stores preferences in ~/.codexel/config.toml by default (override with CODEXEL_HOME). For full options, see Configuration.

Common next steps:

• Sandbox & approvals
• Execpolicy quickstart
• Model Context Protocol (MCP)

Docs

• Getting started (usage, tips, /plan, session resume)
• Authentication
• Configuration and Example config
• Sandbox & approvals (security posture and safe defaults)
• Execpolicy (command execution rules)
• Slash commands and Custom prompts
• Non-interactive runs (codexel exec) and TypeScript SDK
• GitHub Action (upstream): https://github.com/openai/codex-action
• Install & build from source
• FAQ

Releases & support

• Codexel releases: GitHub Releases
• Codexel-only changes: CHANGELOG.md.
• Upstream release notes: https://github.com/openai/codex/releases

If you hit a bug in Codexel, please open an issue in this repository: Issues. If you can reproduce the same issue in upstream Codex CLI, linking the upstream report is helpful.

License

This repository is licensed under the Apache-2.0 License.