Class CodexAxonConnection

constructor

• new CodexAxonConnection(
      axon: Axon,
      devbox: Devbox,
      options?: CodexAxonConnectionOptions,
  ): CodexAxonConnection

  Parameters

  • axon: Axon
  • devbox: Devbox
  • options: CodexAxonConnectionOptions = {}

  Returns CodexAxonConnection

ReadonlyaxonId

ReadonlydevboxId

currentTurnId

• get currentTurnId(): string | undefined

  The in-flight turn id, set on turn/started and cleared on turn/completed.

  Returns string | undefined

initializeResponse

• get initializeResponse(): InitializeResponse | undefined

  The app-server's initialize response, once initialize has run.

  Returns InitializeResponse | undefined

isConnected

• get isConnected(): boolean

  Returns boolean

isDisconnected

• get isDisconnected(): boolean

  Returns boolean

isInitialized

• get isInitialized(): boolean

  Whether the initialize handshake has completed.

  Returns boolean

threadId

• get threadId(): string | undefined

  The active Codex thread id. Use resumeThread to change threads.

  Returns string | undefined

abortStream

• abortStream(): void

  Aborts only the current SSE stream, preserving listeners.

  Returns void

clearThreadGoal

• clearThreadGoal(): Promise<ThreadGoalClearResponse>

  Clears the active thread's goal (thread/goal/clear).

  Returns Promise<ThreadGoalClearResponse>

compactThread

• compactThread(): Promise<void>

  Compacts the active thread's context server-side (thread/compact/start).

  Returns Promise<void>

connect

• connect(): Promise<void>

  Opens the SSE transport and starts its read loop. Call initialize next — the app-server rejects requests until the handshake completes.

  Returns Promise<void>

  Throws

  ConnectionStateError with terminated or already_connected.

disconnect

• disconnect(): Promise<void>

  Gracefully closes the transport and rejects pending requests. Idempotent.

  Returns Promise<void>

getAccountRateLimits

• getAccountRateLimits(): Promise<GetAccountRateLimitsResponse>

  Reads the account's current rate limits (account/rateLimits/read). Wire params are Option<()>: the params field must be omitted, not {}.

  Returns Promise<GetAccountRateLimitsResponse>

getAccountTokenUsage

• getAccountTokenUsage(): Promise<GetAccountTokenUsageResponse>

  Reads the account's token-usage summary (account/usage/read). Wire params are Option<()>: the params field must be omitted, not {}.

  Returns Promise<GetAccountTokenUsageResponse>

getThreadGoal

• getThreadGoal(): Promise<ThreadGoalGetResponse>

  Reads the active thread's goal (thread/goal/get).

  Returns Promise<ThreadGoalGetResponse>

initialize

• initialize(params?: Partial<InitializeParams>): Promise<void>

  Runs the Codex app-server initialize handshake: sends the initialize request (client info + capabilities) and the initialized notification. Required once after connect — the app-server rejects all other requests with -32600 "Not initialized" until this completes. If the server was already initialized (e.g. by a previous session against the same process), that response is treated as success.

  Uses a longer timeout (120 s) because the app-server may still be starting.

  Parameters

  • Optionalparams: Partial<InitializeParams>

    Overrides merged over CodexAxonConnectionOptions.initializeParams and the SDK defaults.

  Returns Promise<void>

  Throws

  ConnectionStateError If the connection is not reusable after a fatal broker error (code: "terminated").

  Throws

  ConnectionStateError If connect has not been called yet (code: "not_connected").

  Throws

  ConnectionStateError If the handshake has already completed (code: "already_initialized").

interrupt

• interrupt(): Promise<void>

  Interrupts the in-flight turn (turn/interrupt). The app-server requires the thread and turn ids, which the connection tracks from turn/started notifications. A no-op when no turn is in flight.

  Returns Promise<void>

  Throws

  ConnectionStateError with not_connected if no thread is active.

listMcpServerStatus

• listMcpServerStatus(
      params?: ListMcpServerStatusParams,
  ): Promise<ListMcpServerStatusResponse>

  Lists configured MCP servers with startup/auth status (mcpServerStatus/list).

  Parameters

  • params: ListMcpServerStatusParams = {}

  Returns Promise<ListMcpServerStatusResponse>

listSkills

• listSkills(params?: SkillsListParams): Promise<SkillsListResponse>

  Lists skills available to the session (skills/list).

  Parameters

  • params: SkillsListParams = {}

  Returns Promise<SkillsListResponse>

onApprovalRequest

• onApprovalRequest(
      method:
          | "item/commandExecution/requestApproval"
          | "item/fileChange/requestApproval"
          | "item/tool/requestUserInput"
          | "item/permissions/requestApproval"
          | "applyPatchApproval"
          | "execCommandApproval",
      handler: ApprovalHandler,
  ): () => void

  Registers an approval handler. Without one, command/file approvals are accepted, legacy approvals are approved, user-input answers are empty, and requested permissions are granted for the turn. Handler timeouts are declined. Mounting with approval_policy=never avoids approval traffic.

  Parameters

  • method:
        | "item/commandExecution/requestApproval"
        | "item/fileChange/requestApproval"
        | "item/tool/requestUserInput"
        | "item/permissions/requestApproval"
        | "applyPatchApproval"
        | "execCommandApproval"
  • handler: ApprovalHandler

  Returns () => void

onAxonEvent

• onAxonEvent(listener: AxonEventListener): () => void

  Registers a raw Axon event listener.

  Parameters

  • listener: AxonEventListener

  Returns () => void

onTimelineEvent

• onTimelineEvent(listener: TimelineEventListener<CodexTimelineEvent>): () => void

  Registers a classified Codex timeline listener.

  Parameters

  • listener: TimelineEventListener<CodexTimelineEvent>

  Returns () => void

publish

• publish(params: AxonPublishParams): Promise<PublishResultView>

  Parameters

  • params: AxonPublishParams

  Returns Promise<PublishResultView>

readConfig

• readConfig(params?: ConfigReadParams): Promise<ConfigReadResponse>

  Reads the app-server's effective configuration (config/read).

  Parameters

  • params: ConfigReadParams = {}

  Returns Promise<ConfigReadResponse>

readThread

• readThread(params?: Partial<ThreadReadParams>): Promise<ThreadReadResponse>

  Reads a thread's metadata — and optionally its turns — from rollout history (thread/read). Defaults to the active thread.

  Parameters

  • Optionalparams: Partial<ThreadReadParams>

  Returns Promise<ThreadReadResponse>

receiveAgentEvents

• receiveAgentEvents(): AsyncGenerator<CodexFrame>

  Yields agent notifications until the connection closes.

  Returns AsyncGenerator<CodexFrame>

receiveTimelineEvents

• receiveTimelineEvents(): AsyncGenerator<CodexTimelineEvent>

  Pull-based classified timeline event stream.

  Returns AsyncGenerator<CodexTimelineEvent>

receiveTurn

• receiveTurn(): AsyncGenerator<CodexFrame>

  Yields one turn and terminates after turn/completed.

  Returns AsyncGenerator<CodexFrame>

resumeThread

• resumeThread(threadId: string): Promise<void>

  Resumes a known server-side thread and makes it current.

  Parameters

  • threadId: string

  Returns Promise<void>

send

• send(prompt: string | UserInput[], options?: TurnOptions): Promise<void>

  Sends text or structured input, creating a thread on the first call. options carries per-turn overrides (see TurnOptions); the app-server applies them to this turn and subsequent turns.

  Parameters

  • prompt: string | UserInput[]
  • Optionaloptions: TurnOptions

  Returns Promise<void>

setThreadGoal

• setThreadGoal(
      params: Omit<ThreadGoalSetParams, "threadId">,
  ): Promise<ThreadGoalSetResponse>

  Sets or updates the active thread's goal (thread/goal/set).

  Parameters

  • params: Omit<ThreadGoalSetParams, "threadId">

  Returns Promise<ThreadGoalSetResponse>

setThreadName

• setThreadName(name: string): Promise<ThreadSetNameResponse>

  Renames the active thread (thread/name/set).

  Parameters

  • name: string

  Returns Promise<ThreadSetNameResponse>

startReview

• startReview(
      target?: ReviewTarget,
      delivery?: ReviewDelivery | null,
  ): Promise<ReviewStartResponse>

  Starts a Codex review on the current thread (review/start), creating a thread if needed. Defaults to reviewing uncommitted changes.

  Parameters

  • target: ReviewTarget = ...
  • Optionaldelivery: ReviewDelivery | null

  Returns Promise<ReviewStartResponse>

startThread

• startThread(params?: ThreadStartParams): Promise<string>

  Starts and tracks a Codex thread, returning its server-assigned id.

  Parameters

  • params: ThreadStartParams = ...

  Returns Promise<string>

steer

• steer(prompt: string | UserInput[]): Promise<void>

  Steers the current in-flight turn.

  Parameters

  • prompt: string | UserInput[]

  Returns Promise<void>