Class ClaudeAxonConnection

constructor

• new ClaudeAxonConnection(
      axon: Axon,
      devbox: Devbox,
      options?: ClaudeAxonConnectionOptions,
  ): ClaudeAxonConnection

  Creates a new Claude connection over the given Axon channel and devbox.

  Unlike ACP, the transport is not opened until connect is called.

  Parameters

  • axon: Axon

    The Axon channel to communicate over (from @runloop/api-client).

  • devbox: Devbox

    The Runloop devbox hosting the Claude Code agent.

  • Optionaloptions: ClaudeAxonConnectionOptions

    Optional configuration for verbose logging, system prompt, model selection, error handling, and lifecycle hooks.

  Returns ClaudeAxonConnection

ReadonlyaxonId

ReadonlydevboxId

isConnected

• get isConnected(): boolean

  Whether the transport is connected and the read loop is active. Returns true after connect resolves and before disconnect.

  Returns boolean

isDisconnected

• get isDisconnected(): boolean

  Whether the connection is not live after having been connected at least once. Returns false before the first successful connect, and true after a disconnect/teardown until connect runs again.

  Returns boolean

isInitialized

• get isInitialized(): boolean

  Whether the connection has been fully initialized (transport connected, read loop active, and protocol handshake complete). Returns false before initialize resolves or after the read loop ends.

  Returns boolean

abortStream

• abortStream(): void

  Aborts the underlying SSE stream without clearing registered listeners or running the onDisconnect callback.

  Unlike disconnect, listeners remain registered. Note that after calling this method, the connection cannot be reused — create a new ClaudeAxonConnection instance to reconnect.

  Returns void

connect

• connect(): Promise<void>

  Opens the transport and starts the background read loop.

  Call this before initialize to establish the Axon connection.

  When replay is true (the default), queries the axon for the current head sequence and replays all events up to that point without invoking handlers. Unresolved control requests are dispatched to handlers after replay completes.

  Returns Promise<void>

  Throws

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

  Throws

  If the transport is already connected (code: "already_connected").

  Throws

  If both replay and afterSequence are set.

disconnect

• disconnect(): Promise<void>

  Closes the transport, fails all pending control requests, and runs the onDisconnect callback if one was provided.

  User-registered listeners (onAxonEvent, onTimelineEvent, onControlRequest) are preserved so they keep working after another connect.

  Idempotent — subsequent calls are no-ops until the next connect.

  Returns Promise<void>

  Resolves once all teardown (including onDisconnect) completes.

initialize

• initialize(): Promise<void>

  Runs the Claude agent protocol initialize step with the Claude Code CLI.

  This is required once after connect on first startup: connect() only opens the transport and read loop; the agent does not accept prompts or control traffic until this handshake completes. If ClaudeAxonConnectionOptions.model was set, a set_model control request is sent immediately afterward.

  Returns Promise<void>

  Throws

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

  Throws

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

  Throws

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

interrupt

• interrupt(): Promise<void>

  Interrupts the current conversation turn.

  Returns Promise<void>

  Throws

  On timeout or if the CLI rejects the interrupt.

onAxonEvent

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

  Registers a listener for every Axon event (before origin filtering). Useful for debugging, observability, and building Axon event viewers.

  Parameters

  • listener: AxonEventListener

    Callback invoked with the raw AxonEventView for every event on the channel, regardless of origin.

  Returns () => void

  An unsubscribe function that removes the listener.

onControlRequest

• onControlRequest<S extends any>(
      subtype: S,
      handler: ControlRequestHandler<S>,
  ): () => void

  Register a handler for incoming control requests of a given subtype.

  When Claude Code sends a control request (e.g. asking permission to use a tool), the registered handler is called instead of the built-in default. The handler receives the full SDKControlRequest and must return a complete SDKControlResponse. The connection sends it back as-is.

  Only one handler can be registered per subtype. Calling this method again with the same subtype replaces the previous handler.

  Type Parameters

  • S extends any

  Parameters

  • subtype: S

    The control request subtype to handle (e.g. "can_use_tool").

  • handler: ControlRequestHandler<S>

    Async function that processes the request and returns a full SDKControlResponse.

  Returns () => void

  Example

  connection.onControlRequest("can_use_tool", async (message) => {
    return {
      type: "control_response",
      response: {
        subtype: "success",
        request_id: message.request_id,
        response: { behavior: "allow", updatedInput: message.request.input },
      },
    };
  });
  Copy

onTimelineEvent

• onTimelineEvent(
      listener: TimelineEventListener<ClaudeTimelineEvent>,
  ): () => void

  Registers a listener for classified timeline events (push API).

  Every Axon event on the channel is classified into one of:

  • claude_protocol — a known Claude protocol event (user or agent message)
  • system — a broker system event (turn.started, turn.completed, broker.error)
  • unknown — anything else

  For a pull-based alternative, see receiveTimelineEvents. Both APIs deliver the same events; choose whichever fits your consumption pattern.

  Parameters

  • listener: TimelineEventListener<ClaudeTimelineEvent>

    Callback invoked with each ClaudeTimelineEvent.

  Returns () => void

  An unsubscribe function that removes the listener.

publish

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

  Publishes a custom event to the Axon channel.

  The event will appear in the SSE stream and be classified by the timeline (typically as kind: "unknown" unless the event_type matches a known Claude protocol message type).

  Parameters

  • params: AxonPublishParams

    The event to publish (same shape as Axon.publish()).

  Returns Promise<PublishResultView>

  The publish result with sequence number and timestamp.

receiveAgentEvents

• receiveAgentEvents(): AsyncGenerator<SDKMessage, void, undefined>

  Async iterator that yields every SDKMessage from Claude indefinitely.

  Does not stop at result messages — use receiveAgentResponse for single-turn convenience. Iteration ends when the transport closes or disconnect is called.

  Returns AsyncGenerator<SDKMessage, void, undefined>

  Yields

  Each SDKMessage as it arrives from the agent.

receiveAgentResponse

• receiveAgentResponse(): AsyncGenerator<SDKMessage, void, undefined>

  Async iterator that yields SDKMessages until (and including) a result message, then terminates automatically.

  Convenient for single-turn usage: send a prompt, iterate receiveAgentResponse(), and the loop ends when Claude finishes.

  Returns AsyncGenerator<SDKMessage, void, undefined>

  Yields

  Each SDKMessage up to and including the result.

  Example

  await conn.send("Summarize this file.");
  for await (const msg of conn.receiveAgentResponse()) {
    console.log(msg.type, msg);
  }
  Copy

receiveMessages

• receiveMessages(): AsyncGenerator<SDKMessage, void, undefined>

  Returns AsyncGenerator<SDKMessage, void, undefined>

  Deprecated

  Use receiveAgentEvents instead.

receiveResponse

• receiveResponse(): AsyncGenerator<SDKMessage, void, undefined>

  Returns AsyncGenerator<SDKMessage, void, undefined>

  Deprecated

  Use receiveAgentResponse instead.

receiveTimelineEvents

• receiveTimelineEvents(): AsyncGenerator<ClaudeTimelineEvent, void, undefined>

  Async generator that yields classified timeline events (pull API).

  Mirrors the pull-based pattern of receiveAgentEvents. The generator completes when the connection is disconnected or the read loop ends.

  For a push-based alternative, see onTimelineEvent. Both APIs deliver the same events; choose whichever fits your consumption pattern.

  Returns AsyncGenerator<ClaudeTimelineEvent, void, undefined>

  An async generator of ClaudeTimelineEvent.

send

• send(prompt: string | SDKUserMessage): Promise<void>

  Sends a single user message to Claude.

  If given a plain string, it is automatically wrapped into an SDKUserMessage with role: "user". Pass a pre-built SDKUserMessage for full control (e.g. to set parent_tool_use_id).

  Parameters

  • prompt: string | SDKUserMessage

    A string message or a fully formed SDKUserMessage.

  Returns Promise<void>

  Throws

  If not connected (code: "not_connected") or after a fatal error (code: "terminated").

  Example

  await conn.send("What files are in this directory?");
  Copy

setModel

• setModel(model: string | null): Promise<void>

  Changes the AI model used by Claude Code.

  Parameters

  • model: string | null

    Anthropic model identifier (e.g. "claude-sonnet-4-5"), or null to revert to the agent's default.

  Returns Promise<void>

  Throws

  On timeout or if the CLI rejects the model change.

setPermissionMode

• setPermissionMode(mode: PermissionMode): Promise<void>

  Changes the permission mode for tool use.

  Parameters

  • mode: PermissionMode

    The new permission mode (e.g. "default", "acceptEdits").

  Returns Promise<void>

  Throws

  On timeout or if the CLI rejects the mode change.