Use Codex for Python Development

Codex is OpenAI’s coding agent. It reads project files, edits code, runs tools, and uses their output to continue a task. For Python development, its usefulness depends on whether it runs the same dependency, lint, and test commands that developers use.

Start with a local project, uv for the environment, and explicit checks for the result. Add cloud execution or reusable skills when the workflow needs them.

Choose where Codex works

Codex is available through several interfaces. Choose one based on how the work will be reviewed:

The interface and execution environment are separate choices. In the app, Local works in the current project directory; Worktree creates a separate Git checkout on the same computer; Cloud uses a remote environment. A worktree isolates file changes, but still uses the local machine’s tools and permissions.

Cloud tasks need their own Python setup. Publish an environment with the repository, uv, dependencies, and required access before delegating work. A local .venv or shell variable does not automatically appear there. See Codex environments.

Start a local session

Follow the official installation instructions for the operating system, then open a terminal in the project directory and run:

codex

The CLI opens an interactive session and offers sign-in when needed. Authentication supports ChatGPT sign-in for subscription access and API-key sign-in for usage-based access. Cloud work requires ChatGPT sign-in; available features and usage depend on the account and workspace.

Use the model picker or /model in the CLI to see the models available to that account. Consult current pricing for access and limits rather than building a workflow around a fixed model or message allowance.

Set permissions before delegating

Codex separates two controls:

• Sandbox: the technical boundary around commands, including writable directories and network access.
• Approval policy: when Codex must request permission to perform an action.

For an interactive development session, explicitly allow project edits with approvals when needed:

codex --sandbox workspace-write --ask-for-approval on-request

The session can edit project files and run commands within the configured boundary. Network access is off by default for this sandbox; installing uncached dependencies may require approval. Managed workspace policy can impose additional restrictions.

Use /permissions to inspect or change permissions during a CLI session. For investigation without project edits, select read-only. danger-full-access removes the sandbox boundary and is unnecessary for routine project work. See agent approvals and security.

The sandbox applies to package managers and test runners too. It does not check whether generated code is correct, and permitted edits can still overwrite project files. Keep a Git checkpoint before a task and review its diff afterward. Platform-specific sandbox setup, including Linux prerequisites, is in the sandbox documentation.

Give Python tasks a reproducible environment

Codex should use the project’s declared dependencies and lockfileA file that records the exact version of every installed package, so everyone working on the project gets identical installs. . With an existing uv project, prepare the environment from the project directory:

uv sync --locked

uv creates or updates the project’s virtual environmentAn isolated folder where Python installs packages for one project, keeping them separate from other projects and your system Python. Learn more → from uv.lock. If project metadata and the lockfile disagree, --locked reports an error instead of updating the lockfile. Resolve that mismatch before asking the agent to debug application code.

Run project commands through uv run; activating the environment is unnecessary. uv run executes the command inside the project’s virtual environment, ensuring all dependencies are installed first.

For a project that already includes Ruff and pytest, a focused task prompt is:

Fix the reported CSV import failure. Reproduce it first, then make the
smallest change that preserves the existing CLI interface.
Use uv for dependency and command management.
Run uv run ruff check ., uv run ruff format --check ., and uv run pytest.
Report which commands passed and which could not run.

If a command fails because it cannot download a dependency or access a service, the check remains unverified. Resolve the environment or access problem before treating the task as complete.

For a new project, use Create a new Python project with Codex.

Include the project’s configured type checker in the same verification loop. For a new setup, Pyrefly is the handbook’s default; an existing project should keep its established checker and command. Record that command beside Ruff and pytest in project instructions so type errors reach the agent as tool output.

Keep project rules in AGENTS.md

Put repository-wide commands and constraints in AGENTS.md. For a project that has Ruff and pytest installed, a short starting point is:

# Work in this repository

- Manage dependencies with uv add and uv add --dev.
- Run commands with uv run; do not use the system Python environment.
- Run uv run ruff check . and uv run ruff format --check . after edits.
- Run uv run pytest before reporting completion.
- Keep pyproject.toml and uv.lock together when changing dependencies.
- Report checks that failed or could not run.

The --dev flag marks a tool as a development dependencyA package needed during development (testing, linting, formatting) that is not shipped to users of your project. Installed with the --dev flag. , keeping it out of production installs.

Codex builds its instruction chain when a session starts. It reads global guidance, then project guidance from the repository root toward the working directory. In each directory, AGENTS.override.md takes precedence over AGENTS.md; configured fallback filenames are checked afterward. More specific guidance appears later in the chain. Start a new session after changing instructions so discovery runs again. See the official discovery rules.

For scope rules and a fuller template, see Write AGENTS.md for a Python project.

Turn repeated workflows into skills

Keep standing repository rules in AGENTS.md. Use a skill for a repeatable task such as auditing dependencies or preparing a release.

A skill is a directory containing SKILL.md and optional scripts, references, or templates. Repository skills live under .agents/skills/. Codex initially sees their names and descriptions, then reads the full instructions when a task calls for them. In the CLI, mention a skill with $skill-name or choose it through /skills; Codex can also select one from its description.

MCP connections add tools and access to external systems. Skills describe how to perform work; they do not supply credentials or override permissions. Review third-party instructions and requested access before installing them.

Review the result and continue work

Use the app’s diff view, the editor integration, or the CLI’s /review command to inspect changes. Check that the implementation matches the requested behavior and that dependency changes are necessary. An agent review supplements the project’s lint and test commands.

For long tasks, give the agent observable completion criteria and steer it when evidence shows the approach is failing. Keep durable decisions in project files so a future session can recover them. In the CLI, codex resume opens a picker for previous sessions; /status shows the active configuration.

Automate bounded tasks with codex exec

codex exec runs without the interactive interface. It defaults to a read-only sandbox, which suits repository inspection:

codex exec --sandbox read-only "Summarize this project's Python tooling and list missing setup instructions."

Progress goes to standard error; the final answer goes to standard output. The result is a generated audit, so verify its findings against the repository.

Automation that edits files needs an explicit writable sandbox and dependencies installed in its execution environment. It also needs credentials and an approval strategy suitable for unattended work. Use --json for event streams or --output-schema for a structured final answer. Keep ordinary linting and tests as deterministic CI checks; reserve agent runs for work that needs judgment.