ClaudeCode.Adapter behaviour (ClaudeCode v0.21.0)

View Source

Behaviour for ClaudeCode adapters.

Adapters handle the full lifecycle of a Claude Code execution environment: provisioning, communication, health checking, and cleanup.

Message Protocol

Adapters communicate with Session using the notification helpers:

  • notify_message(session, request_id, message) - A parsed message from Claude
  • notify_done(session, request_id, reason) - Query complete (reason: :completed)
  • notify_error(session, request_id, reason) - Error occurred

  • notify_status(session, status) - Adapter status change (:provisioning | :ready | {:error, reason})

Usage

Adapters are specified as {Module, config} tuples:

{:ok, session} = ClaudeCode.start_link(
  adapter: {ClaudeCode.Adapter.Local, cli_path: "/usr/bin/claude"},
  model: "opus"
)

The default adapter is ClaudeCode.Adapter.Local.

Summary

Types

adapter_config()
done_reason()
health()

Callbacks

get_server_info(adapter)

Returns cached server initialization info from the control handshake.

health(adapter)

Returns the health status of the adapter's execution environment.

interrupt(adapter)

Sends an interrupt signal to stop the current generation.

send_control_request(adapter, subtype, params)

Sends a control request to the adapter and waits for a response.

send_query(adapter, request_id, prompt, opts)

Sends a query to the adapter.

start_link(session, adapter_config)

Starts the adapter process and provisions the execution environment.

stop(adapter)

Stops the adapter and cleans up resources.

Functions

notify_control_request(session, request_id, request)

Forwards an inbound control request from adapter to session.

notify_done(session, request_id, reason)

Notifies the session that a request has completed.

notify_error(session, request_id, reason)

Notifies the session that a request encountered an error.

notify_message(session, request_id, message)

Sends a parsed message to the session for a specific request.

notify_status(session, status)

Notifies the session of an adapter status change.

Types

adapter_config()

@type adapter_config() :: keyword()

done_reason()

@type done_reason() :: :completed

health()

@type health() :: :healthy | :degraded | {:unhealthy, reason :: term()}

Callbacks

get_server_info(adapter)

(optional) 
@callback get_server_info(adapter :: pid()) :: {:ok, map() | nil} | {:error, term()}

Returns cached server initialization info from the control handshake.

This is an optional callback.

health(adapter)

@callback health(adapter :: pid()) :: health()

Returns the health status of the adapter's execution environment.

interrupt(adapter)

(optional) 
@callback interrupt(adapter :: pid()) :: :ok | {:error, term()}

Sends an interrupt signal to stop the current generation.

This is an optional, fire-and-forget callback — the CLI stops generating and emits a result message. No response is expected.

send_control_request(adapter, subtype, params)

(optional) 
@callback send_control_request(adapter :: pid(), subtype :: atom(), params :: map()) ::
  {:ok, map()} | {:error, term()}

Sends a control request to the adapter and waits for a response.

This is an optional callback — adapters that don't support the control protocol simply don't implement it. Use function_exported?/3 to check.

send_query(adapter, request_id, prompt, opts)

@callback send_query(
  adapter :: pid(),
  request_id :: reference(),
  prompt :: String.t(),
  opts :: keyword()
) :: :ok | {:error, term()}

Sends a query to the adapter.

The adapter should send messages back to the session via send/2:

  • {:adapter_message, request_id, message} for each message
  • {:adapter_done, request_id, reason} when the query completes
  • {:adapter_error, request_id, reason} on errors

Parameters

  • adapter - PID of the adapter process
  • request_id - Unique reference for this request
  • prompt - The user's query string
  • opts - Query options (includes :session_id if resuming)

start_link(session, adapter_config)

@callback start_link(session :: pid(), adapter_config()) ::
  {:ok, pid()} | {:error, term()}

Starts the adapter process and provisions the execution environment.

This should eagerly provision resources (find binary, start container, etc.) and return {:error, reason} immediately if provisioning fails.

Parameters

  • session - PID of the Session GenServer
  • adapter_config - Adapter-specific configuration keyword list

stop(adapter)

@callback stop(adapter :: pid()) :: :ok

Stops the adapter and cleans up resources.

Functions

notify_control_request(session, request_id, request)

@spec notify_control_request(pid(), String.t(), map()) :: :ok

Forwards an inbound control request from adapter to session.

notify_done(session, request_id, reason)

@spec notify_done(pid(), reference(), done_reason()) :: :ok

Notifies the session that a request has completed.

notify_error(session, request_id, reason)

@spec notify_error(pid(), reference(), term()) :: :ok

Notifies the session that a request encountered an error.

notify_message(session, request_id, message)

@spec notify_message(pid(), reference(), term()) :: :ok

Sends a parsed message to the session for a specific request.

notify_status(session, status)

@spec notify_status(pid(), :provisioning | :ready | {:error, term()}) :: :ok

Notifies the session of an adapter status change.

Status values:

  • :provisioning — adapter is starting up
  • :ready — adapter is ready to accept queries
  • {:error, reason} — provisioning failed