OpenAI Codex Rust CLI Agent Best Practices

This skill teaches you to write Rust code in the style of the OpenAI Codex codebase - a production CLI/agent system with 50 crates and 787 Rust files.

Key Characteristics

• Edition 2024 with strict Clippy configuration
• Zero unwrap/expect in non-test code (enforced at workspace level)
• Tokio async runtime with proper Send + Sync bounds
• thiserror for library errors, anyhow for application code
• Flat workspace structure with centralized dependencies

When to Apply

Apply this skill when:

• Building CLI tools or agent systems in Rust
• Writing async Rust with Tokio
• Designing Rust workspace organization
• Implementing error handling patterns
• Working on production Rust codebases

Quick Reference

Critical Rules (Must Follow)

Rule	Description
err-no-unwrap	Never use unwrap() in non-test code
err-no-expect	Avoid expect() in library code
err-thiserror-domain	Use thiserror for domain errors
err-context-chain	Add context to errors with .context()

Error Handling

Rule	Description
err-anyhow-application	Use anyhow::Result for entry points
err-from-derive	Use #[from] for error conversion
err-transparent	Use #[error(transparent)] for wrapped errors
err-structured-variants	Include relevant data in error variants
err-io-result	Use std::io::Result for I/O functions
err-map-err-conversion	Use map_err for error conversion
err-doc-errors	Document error conditions

Organization

Rule	Description
org-workspace-flat	Flat workspace with utils subdirectory
org-crate-naming	kebab-case directories, project prefix
org-module-visibility	Use pub(crate) for internal APIs
org-test-common-crate	Shared test utilities crate
org-integration-tests-suite	Tests in suite directory
org-feature-modules	Feature-based module organization
org-handlers-subdir	Handlers in dedicated subdirectory
org-errors-file	Errors in dedicated file

Component Patterns

Rule	Description
mod-derive-order	Consistent derive macro ordering
mod-async-trait-macro	Use #[async_trait] for async traits
mod-trait-bounds	Send + Sync + 'static for concurrent traits
mod-extension-trait-suffix	Ext suffix for extension traits
mod-builder-pattern	Builder pattern for complex config
mod-type-alias-complex	Type aliases for complex generics
mod-impl-block-order	Consistent impl block ordering
mod-generic-constraints	Where clauses for complex bounds
mod-newtype-pattern	Newtypes for type safety
mod-struct-visibility	Private fields with public constructor
mod-serde-rename	Serde rename for wire format
mod-jsonschema-derive	JsonSchema for API types

Naming Conventions

Rule	Description
name-async-no-suffix	No _async suffix for async functions
name-try-prefix-fallible	try_ prefix for fallible constructors
name-with-prefix-builder	with_ prefix for builder methods
name-handler-suffix	Handler suffix for handlers
name-error-suffix	Error suffix for error types
name-result-type-alias	Crate-specific Result alias
name-const-env-var	_ENV_VAR suffix for env constants
name-request-response	Request/Response type pairing
name-options-suffix	Options suffix for config bundles
name-info-suffix	Info suffix for read-only data
name-provider-suffix	Provider suffix for services
name-client-suffix	Client suffix for API clients
name-manager-suffix	Manager suffix for lifecycle mgmt
name-bool-is-prefix	is_/has_/should_ for booleans
name-plural-collections	Plural names for collections

Style

Rule	Description
style-import-granularity	One item per use statement
style-deny-stdout	Deny stdout/stderr in libraries
style-inline-format-args	Inline format arguments
style-module-docs	Module-level documentation
style-expect-reason	#[expect] with reason for lints
style-cfg-test-module	Unit tests in mod tests

Cross-Crate

Rule	Description
cross-workspace-lints	Workspace-level lint config
cross-workspace-deps	Centralized dependency versions

Example: Proper Error Handling

use thiserror::Error;
use anyhow::Context;

// Domain error with thiserror
#[derive(Debug, Error)]
pub enum ConfigError {
    #[error("failed to read config file: {path}")]
    ReadFailed {
        path: PathBuf,
        #[source]
        source: std::io::Error,
    },

    #[error(transparent)]
    Parse(#[from] toml::de::Error),
}

// Library function returns domain error
pub fn load_config(path: &Path) -> Result<Config, ConfigError> {
    let content = fs::read_to_string(path)
        .map_err(|source| ConfigError::ReadFailed {
            path: path.to_owned(),
            source,
        })?;
    toml::from_str(&content).map_err(Into::into)
}

// Application code uses anyhow with context
fn main() -> anyhow::Result<()> {
    let config = load_config(Path::new("config.toml"))
        .context("failed to load configuration")?;
    run(config).await
}

Source

Patterns extracted from OpenAI Codex (codex-rs/ subdirectory) - a production Rust codebase with 50 crates and 787 Rust files.