Cloud Tasks (codex cloud)

Relevant source files

• codex-rs/cloud-tasks-client/BUILD.bazel
• codex-rs/cloud-tasks-client/Cargo.toml
• codex-rs/cloud-tasks-client/src/api.rs
• codex-rs/cloud-tasks-client/src/http.rs
• codex-rs/cloud-tasks-client/src/lib.rs
• codex-rs/cloud-tasks-mock-client/BUILD.bazel
• codex-rs/cloud-tasks-mock-client/Cargo.toml
• codex-rs/cloud-tasks-mock-client/src/lib.rs
• codex-rs/cloud-tasks-mock-client/src/mock.rs
• codex-rs/cloud-tasks/Cargo.toml
• codex-rs/cloud-tasks/src/app.rs
• codex-rs/cloud-tasks/src/cli.rs
• codex-rs/cloud-tasks/src/env_detect.rs
• codex-rs/cloud-tasks/src/env_detect_tests.rs
• codex-rs/cloud-tasks/src/lib.rs
• codex-rs/cloud-tasks/src/ui.rs
• codex-rs/cloud-tasks/src/util.rs
• codex-rs/cloud-tasks/tests/env_filter.rs
• codex-rs/tui/src/chatwidget/snapshots/codex_tui__chatwidget__tests__exploring_step1_start_ls.snap
• codex-rs/tui/src/chatwidget/snapshots/codex_tui__chatwidget__tests__exploring_step3_start_cat_foo.snap

The codex-cloud-tasks crate provides the implementation for the codex cloud (aliased as cloud-tasks) subcommand codex-rs/cloud-tasks/src/lib.rs8 It offers a Terminal User Interface (TUI) and Command Line Interface (CLI) for interacting with Codex Cloud, enabling users to submit tasks to remote environments, browse task history, monitor execution status, and apply generated diffs to their local workspace codex-rs/cloud-tasks/src/cli.rs15-27

Architecture and Data Flow

The system is built around a CloudBackend abstraction, allowing the application to switch between a live HttpClient and a MockClient for testing codex-rs/cloud-tasks/src/lib.rs42-46

Cloud Task Interaction Diagram

This diagram illustrates the flow from a user command through the backend client to the Codex Cloud API.

Sources: codex-rs/cloud-tasks/src/lib.rs42-46 codex-rs/cloud-tasks/src/cli.rs15-27 codex-rs/cloud-tasks-client/src/api.rs136-176

Component Mapping: Natural Language to Code Entities

This diagram maps user-facing concepts to the internal Rust structs and traits used for cloud task management.

Sources: codex-rs/cloud-tasks/src/app.rs6-11 codex-rs/cloud-tasks-client/src/api.rs67-74 codex-rs/cloud-tasks-client/src/api.rs29-34 codex-rs/cloud-tasks-client/src/api.rs85-93

Backend Abstraction (CloudBackend)

The CloudBackend trait codex-rs/cloud-tasks-client/src/api.rs136-176 decouples the UI and CLI from the network implementation.

HttpClient Implementation

The HttpClient codex-rs/cloud-tasks-client/src/http.rs25-28 handles authentication and request routing to the backend services.

• Authentication: It utilizes codex-login to load credentials via AuthManager codex-rs/cloud-tasks/src/util.rs61-70 It extracts ChatGPT account IDs to inject them into headers codex-rs/cloud-tasks/src/lib.rs114-116
• API Organization: Internally organized into specialized sub-clients for Tasks, Attempts, and Apply logic codex-rs/cloud-tasks-client/src/http.rs55-65

Mock Backend

For development and testing, the system supports a mock mode activated via the CODEX_CLOUD_TASKS_MODE=mock environment variable codex-rs/cloud-tasks/src/lib.rs49-53 This uses codex_cloud_tasks_mock_client::MockClient codex-rs/cloud-tasks/src/lib.rs63 to simulate different task lists and environment behaviors without network calls.

Sources: codex-rs/cloud-tasks/src/lib.rs48-70 codex-rs/cloud-tasks-client/src/http.rs25-66 codex-rs/cloud-tasks/src/util.rs46-72

CLI Commands

The codex cloud command supports several subcommands defined in the Command enum codex-rs/cloud-tasks/src/cli.rs15-27

Command	Struct	Description
exec	ExecCommand	Submits a new task to the cloud and returns the task URL codex-rs/cloud-tasks/src/cli.rs30-50
list	ListCommand	Lists tasks with optional environment filtering and pagination codex-rs/cloud-tasks/src/cli.rs82-98
status	StatusCommand	Checks the current execution status of a task codex-rs/cloud-tasks/src/cli.rs75-79
apply	ApplyCommand	Fetches the diff for a task and applies it locally codex-rs/cloud-tasks/src/cli.rs101-109
diff	DiffCommand	Displays the unified diff for a cloud task codex-rs/cloud-tasks/src/cli.rs112-120

Execution Logic

The execution flow for run_exec_command codex-rs/cloud-tasks/src/lib.rs177-200:

1. Backend Init: Initializes BackendContext via init_backend codex-rs/cloud-tasks/src/lib.rs48-123
2. Environment Resolution: Resolves target environment ID via resolve_environment_id codex-rs/cloud-tasks/src/lib.rs202-230 which uses list_environments codex-rs/cloud-tasks/src/env_detect.rs242-261
3. Git Ref Resolution: Determines the branch via resolve_git_ref codex-rs/cloud-tasks/src/lib.rs149-175
4. Task Creation: Calls CloudBackend::create_task codex-rs/cloud-tasks-client/src/api.rs168-175 and prints the browser URL codex-rs/cloud-tasks/src/lib.rs197-198

Sources: codex-rs/cloud-tasks/src/lib.rs177-230 codex-rs/cloud-tasks/src/cli.rs15-120 codex-rs/cloud-tasks/src/env_detect.rs242-261

Terminal User Interface (TUI)

The TUI provides an interactive interface managed by the App struct codex-rs/cloud-tasks/src/app.rs47-75

UI Components and Rendering

• Task List: Renders TaskSummary items using draw_list codex-rs/cloud-tasks/src/ui.rs176-214
• New Task Page: A view for composing prompts using NewTaskPage and its composer codex-rs/cloud-tasks/src/ui.rs104-174
• Diff Overlay: A full-screen overlay for inspecting task diffs using ScrollableDiff codex-rs/cloud-tasks/src/app.rs136-150
• Modals: Support for environment selection (EnvModalState), attempt selection (BestOfModalState), and application results (ApplyModalState) codex-rs/cloud-tasks/src/app.rs14-40

Best-of-N and Attempts

The system supports multiple assistant attempts (up to 4) codex-rs/cloud-tasks/src/cli.rs52-61 The DiffOverlay tracks these in attempts: Vec<AttemptView> codex-rs/cloud-tasks/src/app.rs144 allowing users to cycle through different AI solutions before applying.

Sources: codex-rs/cloud-tasks/src/app.rs47-150 codex-rs/cloud-tasks/src/ui.rs28-57 codex-rs/cloud-tasks/src/cli.rs52-61

Local Patch Application

Applying a cloud task diff involves fetching the patch and utilizing codex-git-utils.

1. Preflight: The client can perform a dry-run via apply_task_preflight codex-rs/cloud-tasks-client/src/api.rs158-162 to check for conflicts.
2. Execution: apply_task codex-rs/cloud-tasks-client/src/api.rs163-167 fetches the diff and uses codex_git_utils::apply_git_patch codex-rs/cloud-tasks-client/src/http.rs22 to modify the working tree.
3. Outcome: Returns an ApplyOutcome containing the ApplyStatus (Success, Partial, or Error) and lists of skipped_paths or conflict_paths codex-rs/cloud-tasks-client/src/api.rs85-93

Sources: codex-rs/cloud-tasks-client/src/api.rs76-93 codex-rs/cloud-tasks-client/src/http.rs102-125 codex-rs/cloud-tasks/src/app.rs32-40