Skip to main content
This guide outlines the coding standards, conventions, and best practices for invited contributors to the Codex CLI project.

​
Development Workflow

If you’ve been invited by a Codex team member to contribute a PR, follow this recommended workflow:
1

Create a Topic Branch

Create a branch from main with a descriptive name:
git checkout -b feat/interactive-prompt
git checkout -b fix/snapshot-rendering
2

Keep Changes Focused

Multiple unrelated fixes should be opened as separate PRs. Focus on one problem at a time.
3

Ensure Quality

Before pushing, ensure your change is free of:
  • Lint warnings
  • Test failures
  • Type errors (TypeScript)
4

Keep Commits Atomic

Each commit should:
  • Compile successfully
  • Pass all tests
  • Be logically independent (makes reviews and rollbacks easier)

​
Guidance for Invited Code Contributions

1. Start with an Issue

Open a new issue or comment on an existing discussion to agree on the solution before writing code.

2. Add or Update Tests

Bug fixes should come with test coverage that fails before your change and passes afterwards. Aim for meaningful assertions.

3. Document Behavior

If your change affects user-facing behavior, update the README, inline help (codex --help), or relevant example projects.

4. Keep Commits Atomic

Each commit should compile and tests should pass. This makes reviews and potential rollbacks easier.

​
Rust Code Conventions

​
General Rules

Crate names are prefixed with codex-. For example, the core folder’s crate is named codex-core.
  • Always run just fmt after making Rust code changes
  • Run just fix -p <crate> to fix linter issues before finalizing changes
  • Do not re-run tests after running fix or fmt
  • Always collapse if statements per clippy::collapsible_if
  • When possible, make match statements exhaustive and avoid wildcard arms
Do not create small helper methods that are referenced only once. Keep code inline for clarity.

​
TUI Code Conventions

For the terminal user interface (codex-tui), follow these ratatui styling conventions: 
use ratatui::style::Stylize;

// Basic spans
"text".into()

// Styled spans
"error".red()
"success".green()
"info".cyan()
"muted".dim()

// Chained styling
url.cyan().underlined()
header.bold().magenta()
See codex-rs/tui/styles.md for complete TUI styling conventions.

​
Text Wrapping

  • Always use textwrap::wrap to wrap plain strings
  • For ratatui Line wrapping, use helpers in tui/src/wrapping.rs (e.g., word_wrap_lines, word_wrap_line)
  • Use initial_indent/subsequent_indent options from RtOptions for indenting wrapped lines
  • Use prefix_lines helper from line_utils for prefixing lines

​
TypeScript Code Conventions

The TypeScript implementation is legacy. These conventions are for reference only.

​
Code Quality Tools

  • Vitest for unit tests
  • ESLint for linting
  • Prettier for code formatting
  • TypeScript for type checking

​
Before Pushing

pnpm test && pnpm run lint && pnpm run typecheck

​
Opening a Pull Request

Remember: Pull requests must be explicitly invited by a Codex team member.
1

Fill in the PR Template

Include:
  • What? - What does this PR change?
  • Why? - Why is this change necessary?
  • How? - How does it work?
  • Link to the bug report or enhancement request
2

Run All Checks Locally

just fmt
just fix -p <crate>
cargo test -p <crate>
CI failures that could have been caught locally slow down the process.
3

Update Your Branch

Make sure your branch is up-to-date with main and resolve any merge conflicts.
4

Mark as Ready for Review

Only mark the PR as Ready for review when you believe it is in a merge-able state.

​
Model Metadata Updates

When updating model catalogs or model metadata (/models payloads, presets, or fixtures):
  • Set input_modalities explicitly for any model that does not support images
  • Keep compatibility defaults in mind: omitted input_modalities currently implies text + image support
  • Ensure client surfaces that accept images (e.g., TUI paste/attach) consume the same capability signal
  • Add/update tests that cover unsupported-image behavior and warning paths

​
App-Server API Development

When working on app-server protocol in codex-rs:

​
Core Rules

v2 Development

All active API development should happen in app-server v2. Do not add new API surface area to v1.

Payload Naming

  • *Params for request payloads
  • *Response for responses
  • *Notification for notifications

RPC Methods

Expose as <resource>/<method> with singular <resource> (e.g., thread/read, app/list)

Field Casing

Use camelCase on the wire with #[serde(rename_all = "camelCase")]

​
Development Workflow

1

Update Documentation

Update app-server/README.md when API behavior changes.
2

Regenerate Schema Fixtures

just write-app-server-schema

# If experimental API is affected:
just write-app-server-schema --experimental
3

Validate Changes

cargo test -p codex-app-server-protocol

​
Review Process

1

Maintainer Assignment

One maintainer will be assigned as a primary reviewer.
2

Scope Verification

If your invited PR introduces scope or behavior that was not previously discussed and approved, the PR may be closed.
3

Requested Changes

We may ask for changes. Please do not take this personally. We value the work, but also value consistency and long-term maintainability.
4

Merge

When there is consensus that the PR meets the bar, a maintainer will squash-and-merge.

​
Contributor License Agreement (CLA)

All contributors must accept the CLA.
The process is lightweight:
1

Open Your Pull Request

Create and submit your PR.
2

Sign the CLA

Paste the following comment (or reply recheck if you’ve signed before):
I have read the CLA Document and I hereby sign the CLA
3

Bot Verification

The CLA-Assistant bot records your signature and marks the status check as passed.
No special Git commands, email attachments, or commit footers required.

​
Configuration Changes

If you change ConfigToml or nested config types: 
just write-config-schema
This updates codex-rs/core/config.schema.json.

​
Dependency Changes

If you change Rust dependencies (Cargo.toml or Cargo.lock): 
# From repo root
just bazel-lock-update
just bazel-lock-check
Include the lockfile update in the same change.

​
Community Values

Be Kind and Inclusive

Treat others with respect. We follow the Contributor Covenant.

Assume Good Intent

Written communication is hard - err on the side of generosity.

Teach & Learn

If you spot something confusing, open an issue or discussion with suggestions or clarifications.

​
Getting Help

If you run into problems:
  • Open a Discussion topic
  • Jump into the relevant issue
  • Ask in community channels
We are happy to help. Together we can make Codex CLI an incredible tool.

​
Security & Responsible AI

Have you discovered a vulnerability or have concerns about model output?Please email [email protected] and we will respond promptly.

​
Next Steps

Setup

Set up your development environment

Building

Learn how to build the project

Testing

Run tests to validate changes