Lightweight coding agent that runs in your terminal (OpenAI Codex CLI Python version)
中文文档 | English
pip install -U codexy
Table of Contents
This project is a Python reimplementation of the original OpenAI Codex CLI, written in TypeScript. You can find the original repository here:
This Python version aims to provide similar functionality using Python tools and libraries.
Codexy (the Python implementation of Codex CLI) is an experimental project under active development. It is not yet stable, may contain bugs, incomplete features, or undergo breaking changes. We're building it in the open with the community and welcome:
- Bug reports
- Feature requests
- Pull requests
- Good vibes
Help us improve by filing issues or submitting PRs (see the Contributing section)!
Install globally using pip:
pip install -U codexyNext, set your OpenAI API key as an environment variable:
export OPENAI_API_KEY="your-api-key-here"Note: This command sets the key only for your current terminal session. To make it permanent, add the
exportline to your shell's configuration file (e.g.,~/.zshrc,~/.bashrc).Tip: You can also place your API key into a
.envfile at the root of your project:OPENAI_API_KEY=your-api-key-hereThe CLI will automatically load variables from
.envusingpython-dotenv.
Run interactively:
codexyOr, run with a prompt as input (and optionally in Full Auto mode):
codexy "explain this codebase to me"# Be cautious with auto-approval modes
codexy --approval-mode full-auto "create the fanciest todo-list app"That's it – Codexy will interact with the OpenAI API, suggest file changes or commands, and (depending on your approval mode) execute them.
Codexy aims to bring the power of the original Codex CLI to the Python ecosystem. It's built for developers who prefer Python tooling or want to integrate agentic coding capabilities into Python workflows.
- Familiar Python Stack: Uses common Python libraries like
click,textual,openai,httpx. - Terminal-Native: Designed for developers who live in the terminal.
- Agentic Capabilities: Understands prompts, interacts with code, suggests file edits, and can execute commands.
- Configurable Approvals: Control the level of autonomy the agent has.
- Open Source: Contribute to its development and see how it works.
Codexy lets you decide the level of autonomy the agent has via the --approval-mode flag (or configuration file). The modes determine what actions require your explicit confirmation:
| Mode | What the agent may do without asking | Still requires approval | Notes |
|---|---|---|---|
| Suggest (default) |
• Read files • Run known safe read-only commands¹ |
• All file edits/writes • Shell commands |
Safest mode, requires confirmation for most actions. |
| Auto Edit | • Read files • Apply file edits/writes • Safe reads¹ |
• Shell commands | Automatically modifies files, but asks before running commands. |
| Full Auto | • Read/write files • Run shell commands² • Safe reads¹ |
– | Attempts auto-approval, BUT sandboxing is NOT YET IMPLEMENTED. |
| Dangerous Auto | • Read/write files • Run shell commands |
– | UNSAFE. Auto-approves everything without sandboxing. Use with caution. |
¹ Known safe read-only commands include ls, cat, pwd, git status, etc. User-configurable via safe_commands in config.
² While full-auto aims for sandboxed execution, sandboxing is NOT YET IMPLEMENTED in this Python version. Commands will run directly.
codexy) currently lacks the platform-specific sandboxing (like macOS Seatbelt or Docker/iptables) found in the original TypeScript version. In full-auto mode, commands are executed directly on your system without network or filesystem restrictions imposed by the tool itself. The dangerous-auto mode explicitly runs everything unsandboxed. Use auto-approval modes with extreme caution, especially outside of trusted environments or version-controlled repositories.
Codexy will show a warning/confirmation if you start in auto-edit, full-auto, or dangerous-auto while the directory is not tracked by Git, so you have a safety net via version control.
| Requirement | Details |
|---|---|
| Operating Sys | Linux, macOS, Windows (cross-platform) |
| Python | 3.10 or newer (see pyproject.toml) |
| Pip | For installation |
| Git (optional) | Recommended for safety |
| Dependencies | click, textual, openai, etc. |
Usage: codexy [OPTIONS] [PROMPT]
Interactive REPL for Codex agent.
codexy Interactive REPL
codexy "..." Initial prompt for interactive REPL
Options:
--model, -m TEXT Model to use (e.g., o4-mini).
--image, -i PATH Path(s) to image files. (Not fully implemented)
--view, -v PATH Inspect a saved rollout. (Not implemented)
--quiet, -q Non-interactive mode. (Not implemented)
--config, -c Open instructions file in editor.
--writable-root, -w PATH Writable folder (for future sandboxing).
--approval-mode, -a [suggest|auto-edit|full-auto|dangerous-auto]
Override approval policy.
--auto-edit Alias for --approval-mode=auto-edit.
--full-auto Alias for --approval-mode=full-auto.
--no-project-doc Do not include codex.md.
--project-doc PATH Include additional markdown file.
--full-stdout Do not truncate command output.
--notify Enable desktop notifications. (Not implemented)
--flex-mode Enable "flex-mode" tier. (Not implemented)
--dangerously-auto-approve-everything
Alias for --approval-mode=dangerous-auto.
--full-context, -f Full-context mode. (Not implemented)
--version Show the version and exit.
-h, --help Show this message and exit.
Commands:
completion Generate shell completion script.
In-App Commands (within the TUI):
| Command | Description |
|---|---|
/help |
Show commands and shortcuts |
/model |
Switch LLM model (if before first response) |
/approval |
Switch auto-approval mode |
/history |
Show command history overlay |
/clear |
Clear screen and current conversation context |
/clearhistory |
Clear command history file |
/bug |
Open browser to file a bug report (Not Implemented) |
/compact |
Condense context summary (Not Implemented) |
q / exit |
Quit the application |
Codexy looks for configuration files in ~/.codexy/ (note the codexy directory name).
~/.codexy/config.yaml(or.yml,.json): Main configuration.~/.codexy/instructions.md: Global custom instructions for the agent.~/.codexy/history.json: Stores command history.
Example config.yaml:
# ~/.codexy/config.yaml
model: o4-mini # Default model to use
approval_mode: suggest # suggest | auto-edit | full-auto | dangerous-auto
full_auto_error_mode: ask-user # ask-user | ignore-and-continue
notify: false # Enable desktop notifications (Not fully implemented)
history:
max_size: 1000
save_history: true
safe_commands: # Commands safe to auto-approve in 'suggest' mode
- git status
- ls -laExample instructions.md:
- Always use snake_case for Python variables.
- Add type hints to all function definitions.
- Prefer f-strings for formatting.Similar to the original Codex CLI, Codexy can load project-specific context from a codex.md (or .codex.md, CODEX.md) file.
It searches the current directory first, then walks up to the Git root (.git directory). If found, its content is appended to your global instructions.md.
Disable this behavior with --no-project-doc or by setting the environment variable CODEXY_DISABLE_PROJECT_DOC=1.
Contributions are welcome! Please refer to the main project CONTRIBUTING guidelines.
For Python-specific development:
- This project uses PDM for dependency management.
- Install dependencies:
pdm install -G:dev - Run tests:
pdm run pytest - Format code:
pdm run ruff format . - Lint code:
pdm run ruff check .
This project is licensed under the Apache-2.0 License. See the LICENSE file.
Note: Codexy (Python) currently inherits the same limitation as the original Codex CLI and does not support OpenAI organizations with Zero Data Retention (ZDR) enabled due to its reliance on API features incompatible with ZDR. You may encounter 400 errors if your organization uses ZDR.