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);
    }
}

Modules§

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

Structs§

AccountLoginCompletedNotification: account/login/completed notification.
AccountRateLimitsUpdatedNotification: account/rateLimits/updated notification.
AccountUpdatedNotification: account/updated notification (stub — accepts the wire shape unchanged).
AgentMessageDeltaNotification: item/agentMessage/delta notification.
AppListUpdatedNotification: app/list/updated notification (stub).
ClientInfo: Client info sent during the initialize handshake.
CmdOutputDeltaNotification: item/commandExecution/outputDelta notification.
CommandExecOutputDeltaNotification: command/exec/outputDelta notification (stub).
CommandExecutionApprovalParams: Parameters for item/commandExecution/requestApproval (server → client).
CommandExecutionApprovalResponse: Response for item/commandExecution/requestApproval.
ConfigWarningNotification: configWarning notification.
ContextCompactedNotification: thread/compacted notification (stub).
DeprecationNoticeNotification: deprecationNotice notification.
ErrorNotification: error notification.
ExternalAgentConfigImportCompletedNotification: externalAgentConfig/import/completed notification (stub).
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.
FuzzyFileSearchSessionCompletedNotification: fuzzyFileSearch/sessionCompleted notification (stub).
FuzzyFileSearchSessionUpdatedNotification: fuzzyFileSearch/sessionUpdated notification (stub).
GuardianWarningNotification: guardianWarning notification.
HookCompletedNotification: hook/completed notification (stub).
HookStartedNotification: hook/started notification (stub).
InitializeCapabilities: Client capabilities negotiated during initialize.
InitializeParams: Parameters for the initialize request.
InitializeResponse: Response from the initialize request.
ItemCompletedNotification: item/completed notification.
ItemGuardianApprovalReviewCompletedNotification: item/autoApprovalReview/completed notification (stub).
ItemGuardianApprovalReviewStartedNotification: item/autoApprovalReview/started notification (stub).
ItemStartedNotification: item/started notification.
McpServerOauthLoginCompletedNotification: mcpServer/oauthLogin/completed notification.
McpServerStartupStatusUpdatedNotification: mcpServer/startupStatus/updated notification.
McpToolCallProgressNotification: item/mcpToolCall/progress notification (stub).
ModelReroutedNotification: model/rerouted notification (stub).
ModelVerificationNotification: model/verification notification (stub).
PlanDeltaNotification: item/plan/delta notification (EXPERIMENTAL).
ProcessExitedNotification: process/exited notification (stub).
ProcessOutputDeltaNotification: process/outputDelta notification (stub).
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.
ServerRequestResolvedNotification: serverRequest/resolved notification (stub).
SkillsChangedNotification: skills/changed notification (no payload).
TerminalInteractionNotification: item/commandExecution/terminalInteraction notification (stub).
ThreadArchiveParams: Parameters for thread/archive.
ThreadArchiveResponse: Response from thread/archive.
ThreadArchivedNotification: thread/archived notification.
ThreadClosedNotification: thread/closed notification.
ThreadGoalClearedNotification: thread/goal/cleared notification.
ThreadGoalUpdatedNotification: thread/goal/updated notification (stub).
ThreadInfo: Thread metadata returned inside a ThreadStartResponse.
ThreadNameUpdatedNotification: thread/name/updated notification.
ThreadRealtimeClosedNotification: thread/realtime/closed notification (stub).
ThreadRealtimeErrorNotification: thread/realtime/error notification (stub).
ThreadRealtimeItemAddedNotification: thread/realtime/itemAdded notification (stub).
ThreadRealtimeOutputAudioDeltaNotification: thread/realtime/outputAudio/delta notification (stub).
ThreadRealtimeSdpNotification: thread/realtime/sdp notification (stub).
ThreadRealtimeStartedNotification: thread/realtime/started notification (stub).
ThreadRealtimeTranscriptDeltaNotification: thread/realtime/transcript/delta notification (stub).
ThreadRealtimeTranscriptDoneNotification: thread/realtime/transcript/done notification (stub).
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).
WindowsSandboxSetupCompletedNotification: windowsSandbox/setupCompleted notification (stub).
WindowsWorldWritableWarningNotification: windows/worldWritableWarning notification (stub).

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

Modules§

Structs§

Enums§

Module protocol