codexy 0.0.3

A Python implementation of the Codex CLI tool.

Codexy

Lightweight coding agent that runs in your terminal (OpenAI Codex CLI Python version)

中文文档 | English

pip install -U codexy

---

Table of Contents

• Original TypeScript Version
• Experimental Technology Disclaimer
• Quickstart
• Why Codexy?
• Security Model & Permissions
• System Requirements
• CLI Reference
• Configuration
• Project Docs
• Contributing
• License
• Zero Data Retention (ZDR) Organization Limitation

---

Original TypeScript Version

This project is a Python reimplementation of the original OpenAI Codex CLI, written in TypeScript. You can find the original repository here:

openai/codex (TypeScript)

This Python version aims to provide similar functionality using Python tools and libraries.

Experimental Technology Disclaimer

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)!

Quickstart

Install globally using pip:

pip install -U codexy

Next, 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 export line to your shell's configuration file (e.g., ~/.zshrc, ~/.bashrc).

Tip: You can also place your API key into a .env file at the root of your project:

OPENAI_API_KEY=your-api-key-here

The CLI will automatically load variables from .env using python-dotenv.

Run interactively:

codexy

Or, 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.

---

Why Codexy?

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.

---

Security Model & Permissions

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.

⚠️ Important: The Python version (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.

---

System Requirements

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.

---

CLI Reference

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

---

Configuration

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 -la

Example instructions.md:

- Always use snake_case for Python variables.
- Add type hints to all function definitions.
- Prefer f-strings for formatting.

---

Project Docs

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.

---

Contributing

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 .

---

License

This project is licensed under the Apache-2.0 License. See the LICENSE file.

---

Zero Data Retention (ZDR) Organization Limitation

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.