Module protocol

Expand description

App-server v2 protocol types for the Codex CLI.

These types represent the JSON-RPC request parameters, response payloads, and notification bodies used by codex app-server. All wire types use camelCase field names via #[serde(rename_all = "camelCase")].

§Organization

Request/Response pairs — ThreadStartParams/ThreadStartResponse, TurnStartParams/TurnStartResponse, etc.
Server notifications — Structs like TurnCompletedNotification, AgentMessageDeltaNotification that can be deserialized from the params field of a [ServerMessage::Notification]
Approval flow types — CommandExecutionApprovalParams and FileChangeApprovalParams for server-to-client requests that need a response
Method constants — The methods module contains all JSON-RPC method name strings

§Parsing notifications

Prefer the typed dispatch in crate::messages over manual method checks:

use codex_codes::{Notification, ServerMessage};

fn handle(msg: ServerMessage) {
    if let ServerMessage::Notification(Notification::TurnCompleted(c)) = msg {
        println!("Turn {} on thread {} completed", c.turn.id, c.thread_id);
    }
}

Re-exports§

pub use crate::protocol_generated::types::*;

Modules§

methods: JSON-RPC method names used by the app-server protocol.

Structs§

AccountLoginCompletedNotification: account/login/completed notification.
AccountRateLimitsUpdatedNotification: account/rateLimits/updated notification.
AgentMessageDeltaNotification: item/agentMessage/delta notification.
ClientInfo: Client info sent during the initialize handshake.
CmdOutputDeltaNotification: item/commandExecution/outputDelta notification.
CommandExecutionApprovalParams: Parameters for item/commandExecution/requestApproval (server → client).
CommandExecutionApprovalResponse: Response for item/commandExecution/requestApproval.
ConfigWarningNotification: configWarning notification.
DeprecationNoticeNotification: deprecationNotice notification.
ErrorNotification: error notification.
FileChangeApprovalParams: Parameters for item/fileChange/requestApproval (server → client).
FileChangeApprovalResponse: Response for item/fileChange/requestApproval.
FileChangeOutputDeltaNotification: item/fileChange/outputDelta notification.
FileChangePatchUpdatedNotification: item/fileChange/patchUpdated notification.
FsChangedNotification: fs/changed notification.
GuardianWarningNotification: guardianWarning notification.
InitializeCapabilities: Client capabilities negotiated during initialize.
InitializeParams: Parameters for the initialize request.
InitializeResponse: Response from the initialize request.
ItemCompletedNotification: item/completed notification.
ItemStartedNotification: item/started notification.
McpServerOauthLoginCompletedNotification: mcpServer/oauthLogin/completed notification.
McpServerStartupStatusUpdatedNotification: mcpServer/startupStatus/updated notification.
PlanDeltaNotification: item/plan/delta notification (EXPERIMENTAL).
RateLimitWindow: A rate-limit window descriptor used inside RateLimits.
RateLimits: Rate-limit envelope sent in AccountRateLimitsUpdatedNotification.
ReasoningDeltaNotification: item/reasoning/summaryTextDelta notification.
ReasoningSummaryPartAddedNotification: item/reasoning/summaryPartAdded notification.
ReasoningTextDeltaNotification: item/reasoning/textDelta notification.
RemoteControlStatusChangedNotification: remoteControl/status/changed notification.
SkillsChangedNotification: skills/changed notification (no payload).
ThreadArchiveParams: Parameters for thread/archive.
ThreadArchiveResponse: Response from thread/archive.
ThreadArchivedNotification: thread/archived notification.
ThreadClosedNotification: thread/closed notification.
ThreadGoalClearedNotification: thread/goal/cleared notification.
ThreadInfo: Thread metadata returned inside a ThreadStartResponse.
ThreadNameUpdatedNotification: thread/name/updated notification.
ThreadStartParams: Parameters for thread/start.
ThreadStartResponse: Response from thread/start.
ThreadStartedNotification: thread/started notification.
ThreadStatusChangedNotification: thread/status/changed notification.
ThreadTokenUsageUpdatedNotification: thread/tokenUsage/updated notification.
ThreadUnarchivedNotification: thread/unarchived notification.
TokenCounts: A snapshot of token counts within a single turn or aggregated across a thread. Sub-field of TokenUsage.
TokenUsage: Cumulative token usage for a thread.
Turn: A completed turn with its items and final status.
TurnCompletedNotification: turn/completed notification.
TurnDiffUpdatedNotification: turn/diff/updated notification.
TurnError: Error information from a failed turn.
TurnInterruptParams: Parameters for turn/interrupt.
TurnInterruptResponse: Response from turn/interrupt.
TurnPlanStep: One step in a turn-level plan.
TurnPlanUpdatedNotification: turn/plan/updated notification.
TurnStartParams: Parameters for turn/start.
TurnStartResponse: Response from turn/start.
TurnStartedNotification: turn/started notification.
WarningNotification: warning notification (general advisory).

Enums§

CommandApprovalDecision: Decision for command execution approval.
FileChangeApprovalDecision: Decision for file change approval.
ThreadStatus: Status of a thread, sent via ThreadStatusChangedNotification.
TurnPlanStepStatus: Lifecycle state of a TurnPlanStep.
TurnStatus: Status of a turn within a Turn.
UserInput: User input sent as part of a TurnStartParams.

Module protocol

Module protocol Copy item path

§Organization

§Parsing notifications

Re-exports§

Modules§

Structs§

Enums§

Module protocol