codexus

codexus is a Rust SDK for the local codex app-server.

It is built around one release rule:

Generated Protocol Core
-> Thin Runtime
-> Thin Human API

The generated protocol layer is the only protocol truth. Ergonomic helpers, workflows, and adapters are intentionally thinner layers on top of that generated surface.

Why This Exists

codexus is for Rust applications that need local Codex runtime access without giving up typed protocol coverage or release discipline.

It is designed to provide:

• protocol-complete typed access to the upstream app-server contract
• ergonomic prompt and session APIs for common flows
• explicit approval, hook, and event-stream control for advanced flows
• checked-in generated protocol output with CI drift detection

Package Overview

The published crate is codexus (1.1.0).

Public layers:

• codexus::protocol: generated method specs, inventory, validators, codecs
• codexus::runtime: typed runtime, sessions, hooks, approvals, state, transport
• codexus::automation: recurring turns on one prepared Session
• codexus::plugin: hook traits and hook-side contracts
• codexus::web, codexus::artifact: higher-level adapters/domains

Entry points by use case:

Level	Entry point	Use when
Fast path	quick_run, quick_run_with_profile	One prompt with safe defaults
Session path	Workflow, runtime::{Client, Session}	Repeated turns with preserved context
Full control	AppServer, runtime::Runtime, protocol	Typed protocol access, live events, approvals, hooks

Core capabilities:

• run one prompt or many turns in one session
• stream assistant output and turn lifecycle events
• start, resume, read, list, archive, and interrupt threads and turns
• watch filesystem paths and consume typed fs/changed notifications
• patch runtime experimental feature enablement through the typed runtime surface
• route typed server requests and approval flows
• attach files and skills to runs
• intercept lifecycle phases with hooks
• run fixed-cadence automation on one prepared session
• persist bounded runtime state snapshots

Requirements

codexus talks to a local Codex CLI runtime by spawning codex app-server.

Before integrating it:

• install a compatible codex CLI on the host machine
• ensure the runtime can launch codex app-server from the process environment
• use Tokio, because the crate is async-first
• provide an absolute working directory for prompt and session flows

Default runtime behavior:

Setting	Default
approval	never
sandbox	read-only
effort	medium
timeout	120s
privileged escalation	false

Quick Start

Add the crate:

[dependencies]
codexus = "1.1.0"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

One prompt:

use codexus::quick_run;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let out = quick_run("/abs/path/workdir", "Summarize this repo in 3 bullets").await?;
    println!("{}", out.assistant_text);
    Ok(())
}

Reusable session:

use codexus::runtime::{Client, SessionConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::connect_default().await?;
    let session = client
        .start_session(SessionConfig::new("/abs/path/workdir"))
        .await?;

    let out = session.ask("Summarize the current design").await?;
    println!("{}", out.assistant_text);

    session.close().await?;
    client.shutdown().await?;
    Ok(())
}

Typed protocol bridge:

use codexus::protocol::client_requests::ThreadStart;
use codexus::runtime::ClientConfig;
use codexus::AppServer;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let server = AppServer::connect(ClientConfig::new()).await?;
    let result = server
        .request_typed::<ThreadStart>(json!({
            "cwd": "/abs/path/workdir",
            "approvalPolicy": "never",
            "sandbox": "read-only"
        }))
        .await?;
    println!("{}", result.thread.id);
    server.shutdown().await?;
    Ok(())
}

Release Model

The repository is release-ready only when all of the following remain true:

• generated protocol output matches the vendored upstream snapshot
• the runtime remains a thin layer over the generated protocol surface
• README examples and product spec claims still match the public crate behavior
• CI continues to block drift in code generation, formatting, linting, and tests

Minimum release verification:

cargo run -p xtask -- protocol-codegen-check
cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

Opt-in real-server coverage:

CODEX_RUNTIME_REAL_SERVER_APPROVED=1 \
cargo test -p codexus ergonomic::tests::real_server:: -- --ignored --nocapture

Documentation Contract

Human-facing docs are intentionally limited to:

• this README.md
• docs/specs/product-spec.md

README.md is the operator-facing entry point. The product spec is the release contract for generated protocol completeness, runtime shape, and release gates. If the two drift, the release is not ready.

License

MIT