@spec abort(pid()) :: :ok | {:error, term()}

Abort the current query. Alias for interrupt/1.

@spec account_info(session()) :: {:ok, map()} | {:error, term()}

Get account information from the init response.

Returns account details (email, org, subscription type, etc.) from the initialize control_response.

Examples

{:ok, account} = ClaudeEx.account_info(session)
account["email"]  # => "user@example.com"

@spec active_betas(pid()) :: {:ok, list()} | {:error, term()}

List active beta features from the system init data.

@spec api_key_source(pid()) :: {:ok, binary() | nil} | {:error, term()}

Get the API key source from the system init data.

@spec block_to_message(content_block()) :: %{
  type: :raw | :text | :thinking | :tool_result | :tool_use,
  content: term(),
  raw: term(),
  tool_input: term(),
  tool_name: term(),
  tool_use_id: term()
}

Convert a single content_block into a flat message.

@spec child_spec([session_opt()]) :: Supervisor.child_spec()

Supervisor child specification for embedding a session.

Examples

children = [
  {ClaudeEx, cli_path: "claude", work_dir: "/my/project"}
]
Supervisor.start_link(children, strategy: :one_for_one)

@spec cli_version(pid()) :: {:ok, binary() | nil} | {:error, term()}

Get the CLI version from the system init data.

@spec command_run(pid(), binary(), map()) ::
  {:ok, %{exit_code: integer(), output: binary()}}
  | {:error,
     {:port_exit, term()} | {:port_failed, term()} | {:timeout, timeout()}}

Run a command via universal command execution.

@spec current_model(pid()) :: {:ok, binary() | nil} | {:error, term()}

Get the current model from session info.

Extracts from the session's model field or system init data.

@spec current_permission_mode(pid()) ::
  {:ok, atom() | binary() | nil} | {:error, term()}

Get the current permission mode from session info.

@spec delete_session(binary()) :: :ok

Delete a session and its messages.

@spec extract_todos([message()]) :: [BeamAgent.Todo.todo_item()]

Extract all TodoWrite items from a list of messages.

Scans assistant messages for TodoWrite tool use blocks and returns a flat list of todo items with :content, :status, and optional :active_form fields.

@spec filter_todos([BeamAgent.Todo.todo_item()], BeamAgent.Todo.todo_status()) :: [
  BeamAgent.Todo.todo_item()
]

Filter todo items by status.

Valid statuses: :pending, :in_progress, :completed.

@spec flatten_assistant(map()) :: [map()]

Flatten an assistant message (with content_blocks) into individual messages.

Non-assistant messages pass through as a single-element list. Context fields from the parent are propagated to children.

@spec fork_session(pid(), map()) :: {:ok, session_info_map()} | {:error, :not_found}

Fork a tracked session into a new session ID.

@spec get_native_session_messages(binary(), [{:config_dir, binary()}]) ::
  {:ok, [map()]} | {:error, term()}

Read all messages from a past Claude Code session transcript on disk.

Parses the full JSONL file and returns messages in conversation order.

Options

• :config_dir — Override the Claude config directory (default: ~/.claude)

Examples

{:ok, messages} = ClaudeEx.get_native_session_messages("session-uuid-123")

@spec get_session(binary()) :: {:ok, session_info_map()} | {:error, :not_found}

Get session metadata by ID.

@spec get_session_messages(binary()) :: {:ok, [message()]} | {:error, :not_found}

Get messages for a session.

@spec get_session_messages(binary(), map()) ::
  {:ok, [message()]} | {:error, :not_found}

Get messages with options.

@spec health(session()) ::
  :ready | :connecting | :initializing | :active_query | :error

Get the current health/state of a session.

Examples

:ready = ClaudeEx.health(session)

@spec interrupt(pid()) :: :ok | {:error, term()}

Interrupt the current active query.

Sends an interrupt signal to the CLI subprocess. The current query will terminate and the session returns to idle state.

@spec list_agents(pid()) :: {:ok, list()} | {:error, term()}

List available agents from the system init data.

@spec list_mcp_servers(pid()) :: {:ok, list()} | {:error, term()}

List configured MCP servers from the system init data.

@spec list_native_sessions(config_dir: binary(), cwd: binary(), limit: pos_integer()) ::
  {:ok,
   [
     %{
       file_path: binary(),
       modified_at: integer(),
       session_id: binary(),
       cwd: binary(),
       model: binary()
     }
   ]}

List past Claude Code session transcripts from disk.

Scans ~/.claude/projects/ for JSONL transcript files and returns metadata (session_id, model, timestamps) sorted by most recent first.

Options

• :config_dir — Override the Claude config directory (default: ~/.claude)
• :cwd — Filter to sessions for a specific working directory
• :limit — Maximum number of sessions to return

Examples

{:ok, sessions} = ClaudeEx.list_native_sessions()
{:ok, sessions} = ClaudeEx.list_native_sessions(limit: 10)

@spec list_plugins(pid()) :: {:ok, list()} | {:error, term()}

List available plugins from the system init data.

@spec list_sessions() :: {:ok, [session_info_map()]}

List all tracked sessions.

@spec list_sessions(map()) :: {:ok, [session_info_map()]}

List sessions with filters.

@spec list_skills(pid()) :: {:ok, list()} | {:error, term()}

List available skills from the system init data.

@spec list_tools(pid()) :: {:ok, list()} | {:error, term()}

List available tools from the system init data.

@spec mcp_server(binary(), [mcp_tool_map()]) :: mcp_server_map()

Create an MCP server with a list of tools.

The server is registered with the session at startup and handles JSON-RPC tool calls from Claude in-process.

Examples

tool = ClaudeEx.mcp_tool("greet", "Greet user", %{"type" => "object"},
  fn _input -> {:ok, [%{type: :text, text: "Hello!"}]} end
)
server = ClaudeEx.mcp_server("my-tools", [tool])
{:ok, session} = ClaudeEx.start_session(sdk_mcp_servers: [server])

@spec mcp_server_status(session()) :: {:ok, term()} | {:error, term()}

Query MCP server health and status.

Returns connection status, availability, and diagnostics for all configured MCP servers in the session.

Examples

{:ok, status} = ClaudeEx.mcp_server_status(session)

@spec mcp_tool(binary(), binary(), map(), (map() ->
                                       {:error, binary()} | {:ok, [map()]})) ::
  mcp_tool_map()

Create an MCP tool definition for in-process tool handling.

The handler function receives the tool input as a map and must return {:ok, [content_result()]} or {:error, binary()}.

Examples

tool = ClaudeEx.mcp_tool("echo", "Echo input",
  %{"type" => "object", "properties" => %{"text" => %{"type" => "string"}}},
  fn input -> {:ok, [%{type: :text, text: input["text"]}]} end
)

@spec message_to_block(map()) :: content_block()

Convert a single flat message into a content_block.

@spec messages_to_blocks([map()]) :: [content_block()]

Convert a list of flat messages into content_block() format.

Supported types (text, thinking, tool_use, tool_result) map to their block equivalents. Other types are wrapped in raw blocks.

@spec normalize_messages([map()]) :: [map()]

Normalize a list of messages from any adapter into a uniform flat stream.

Claude produces assistant messages with nested content_blocks. All other adapters produce individual typed messages (text, tool_use, etc.). This function flattens both into a uniform stream where each message has a single, specific type — never nested content_blocks.

Context fields (uuid, session_id, model, timestamp) from assistant messages are propagated to flattened children.

Examples

# Works identically regardless of which adapter produced messages:
ClaudeEx.normalize_messages(messages)
|> Enum.filter(& &1.type == :text)
|> Enum.map(& &1.content)
|> Enum.join("")

@spec output_style(pid()) :: {:ok, binary() | nil} | {:error, term()}

Get the output style from the system init data.

@spec query(session(), binary(), [query_opt()]) ::
  {:ok, [message()]} | {:error, term()}

Send a query and collect all response messages (blocking).

Returns the complete list of messages once the query finishes. This is the simple, synchronous interface.

Examples

{:ok, messages} = ClaudeEx.query(session, "Hello!")
last = List.last(messages)
IO.puts(last.content)

@spec reconnect_mcp_server(session(), binary()) :: {:ok, term()} | {:error, term()}

Reconnect a failed MCP server by name.

Examples

{:ok, _} = ClaudeEx.reconnect_mcp_server(session, "my_server")

@spec revert_session(pid(), map()) ::
  {:ok, session_info_map()} | {:error, :invalid_selector | :not_found}

Revert the visible session history to a prior boundary.

@spec rewind_files(session(), binary()) :: {:ok, term()} | {:error, term()}

Revert file changes to a checkpoint identified by UUID.

Only meaningful when file checkpointing is enabled in session opts.

Examples

{:ok, _} = ClaudeEx.rewind_files(session, "msg-uuid-123")

@spec sdk_hook(atom(), hook_callback()) :: hook_map()

Create an SDK lifecycle hook.

Hooks fire at key session lifecycle points. Events:

• :pre_tool_use — before tool execution (can deny)
• :post_tool_use — after tool result received
• :stop — when result/completion received
• :session_start — when session enters ready state
• :session_end — when session terminates
• :user_prompt_submit — before query sent (can deny)

Examples

hook = ClaudeEx.sdk_hook(:pre_tool_use, fn ctx ->
  case ctx.tool_name do
    "Bash" -> {:deny, "No shell access"}
    _ -> :ok
  end
end)
{:ok, session} = ClaudeEx.start_session(sdk_hooks: [hook])

@spec sdk_hook(atom(), hook_callback(), %{tool_name: binary()}) ::
  hook_with_matcher_map()

Create an SDK lifecycle hook with a matcher filter.

The matcher's :tool_name (exact string or regex) restricts which tools trigger the hook. Only relevant for tool-related events.

Examples

# Only fire on Bash tool
hook = ClaudeEx.sdk_hook(:pre_tool_use,
  fn _ctx -> {:deny, "blocked"} end,
  %{tool_name: "Bash"})

# Fire on Read* tools (regex)
hook = ClaudeEx.sdk_hook(:pre_tool_use,
  fn _ctx -> :ok end,
  %{tool_name: "Read.*"})

@spec send_control(pid(), binary(), map()) :: {:ok, term()} | {:error, term()}

Send a raw control message to the session.

Low-level interface for sending arbitrary control protocol messages. Most users should prefer the higher-level convenience functions.

Examples

ClaudeEx.send_control(session, "setModel", %{"model" => "claude-sonnet-4-6"})

@spec server_health(pid()) ::
  {:ok,
   %{
     adapter: :claude,
     health: :active_query | :connecting | :error | :initializing | :ready
   }}

Check server health. Maps to session health + adapter info for Claude.

@spec session_info(session()) :: {:ok, map()} | {:error, term()}

Query session capabilities and initialization data.

Returns a map with:

• :session_id — the session ID
• :system_info — parsed system init metadata (tools, model, etc.)
• :init_response — raw initialize control_response

Available in all session states (connecting, initializing, ready, active_query, error).

Examples

{:ok, info} = ClaudeEx.session_info(session)
info.system_info.model  # => "claude-sonnet-4-20250514"
info.system_info.tools  # => ["Read", "Write", "Bash"]

@spec set_max_thinking_tokens(session(), pos_integer()) ::
  {:ok, term()} | {:error, term()}

Set the maximum thinking tokens at runtime.

Controls how many tokens the model can use for its internal reasoning/thinking process.

Examples

{:ok, _} = ClaudeEx.set_max_thinking_tokens(session, 8192)

@spec set_mcp_servers(session(), map()) :: {:ok, term()} | {:error, term()}

Dynamically add or replace MCP server configurations.

Accepts a map of server name => server config. Existing servers with the same name are replaced; others are unaffected.

Examples

servers = %{"my_server" => %{"command" => "node", "args" => ["server.js"]}}
{:ok, _} = ClaudeEx.set_mcp_servers(session, servers)

@spec set_model(session(), binary()) :: {:ok, binary()} | {:error, term()}

Change the model at runtime during a session.

Examples

:ok = ClaudeEx.set_model(session, "claude-sonnet-4-20250514")

@spec set_permission_mode(session(), binary()) :: {:ok, binary()} | {:error, term()}

Change the permission mode at runtime.

Examples

:ok = ClaudeEx.set_permission_mode(session, "acceptEdits")

@spec share_session(pid()) :: {:ok, share_info_map()} | {:error, :not_found}

Create or replace share state for the current session.

@spec start_session([session_opt()]) :: {:ok, session()} | {:error, term()}

Start a new Claude Code session.

Returns {:ok, pid} on success. The session process can be added to your supervision tree via ClaudeEx.child_spec/1.

Examples

{:ok, session} = ClaudeEx.start_session(cli_path: "claude")
{:ok, session} = ClaudeEx.start_session(work_dir: "/my/project")
{:ok, session} = ClaudeEx.start_session(
  cli_path: "claude",
  model: "claude-sonnet-4-20250514",
  permission_mode: :accept_edits
)

@spec stop(session()) :: :ok

Gracefully stop a session, closing the CLI subprocess.

@spec stop_task(session(), binary()) :: {:ok, term()} | {:error, term()}

Stop a running agent task by task ID.

Examples

{:ok, _} = ClaudeEx.stop_task(session, "task-abc")

@spec stream(session(), binary(), [query_opt()]) :: Enumerable.t()

Return a Stream that does not raise on errors.

Like stream!/3 but wraps messages in {:ok, msg} tuples and returns {:error, reason} on failure instead of raising.

@spec stream!(session(), binary(), [query_opt()]) :: Enumerable.t()

Return a lazy Stream of messages for the given prompt.

Uses Stream.resource/3 to implement demand-driven consumption: the gen_statem only parses the next JSONL line when the stream consumer requests it. The query is dispatched to the CLI immediately when stream!/3 is called; message consumption is lazy/pull-based.

The stream halts automatically when a :result or :error message is received, or when the query completes.

Examples

ClaudeEx.stream!(session, "Explain GenServer")
|> Stream.filter(& &1.type == :assistant)
|> Enum.flat_map(& &1.content_blocks)
|> Enum.filter(& &1.type == :text)
|> Enum.map(& &1.text)
|> Enum.join("")

# With options
ClaudeEx.stream!(session, "Hello", system_prompt: "Be brief")
|> Enum.to_list()

@spec submit_feedback(pid(), map()) :: :ok

Submit feedback via universal feedback tracking.

@spec summarize_session(pid()) :: {:ok, summary_info_map()} | {:error, :not_found}

Generate and store a summary for the current session.

@spec supported_agents(session()) :: {:ok, list()} | {:error, term()}

List available agents from the init response.

Examples

{:ok, agents} = ClaudeEx.supported_agents(session)

@spec supported_commands(session()) :: {:ok, list()} | {:error, term()}

List available slash commands from the init response.

Returns the commands array from the initialize control_response, or an empty list if not yet initialized.

Examples

{:ok, commands} = ClaudeEx.supported_commands(session)
Enum.each(commands, &IO.inspect/1)

@spec supported_models(session()) :: {:ok, list()} | {:error, term()}

List available models from the init response.

Examples

{:ok, models} = ClaudeEx.supported_models(session)

@spec thread_archive(pid(), binary()) ::
  {:ok, thread_info_map()} | {:error, :not_found}

Archive a thread.

@spec thread_fork(pid(), binary()) :: {:ok, thread_info_map()} | {:error, :not_found}

Fork an existing thread.

@spec thread_list(pid()) :: {:ok, [thread_info_map()]}

List all threads for this session.

@spec thread_read(pid(), binary()) ::
  {:ok, thread_read_info_map()} | {:error, :not_found}

Read thread metadata, optionally including visible messages.

@spec thread_resume(pid(), binary()) ::
  {:ok, thread_info_map()} | {:error, :not_found}

Resume an existing thread.

@spec thread_rollback(pid(), binary(), map()) ::
  {:ok, thread_info_map()} | {:error, :invalid_selector | :not_found}

Rollback the visible thread history.

@spec thread_start(pid(), map()) ::
  {:ok,
   %{
     archived: false,
     created_at: integer(),
     message_count: 0,
     metadata: map(),
     name: binary(),
     session_id: binary(),
     status: :active,
     thread_id: binary(),
     updated_at: integer(),
     visible_message_count: 0,
     parent_thread_id: binary()
   }}

Start a new conversation thread.

@spec thread_unarchive(pid(), binary()) ::
  {:ok, thread_info_map()} | {:error, :not_found}

Unarchive a thread.

@spec todo_summary([BeamAgent.Todo.todo_item()]) :: %{
  :total => non_neg_integer(),
  required(atom()) => non_neg_integer()
}

Get a summary of todo counts by status.

Returns a map like %{pending: 2, in_progress: 1, completed: 3, total: 6}.

@spec toggle_mcp_server(session(), binary(), boolean()) ::
  {:ok, term()} | {:error, term()}

Enable or disable an MCP server at runtime.

Examples

{:ok, _} = ClaudeEx.toggle_mcp_server(session, "my_server", false)
{:ok, _} = ClaudeEx.toggle_mcp_server(session, "my_server", true)

@spec turn_respond(pid(), binary(), map()) ::
  :ok | {:error, :not_found | :already_resolved}

Respond to an agent request via universal turn response.

@spec unrevert_session(pid()) :: {:ok, session_info_map()} | {:error, :not_found}

Clear any stored session revert state.

@spec unshare_session(pid()) :: :ok | {:error, :not_found}

Revoke share state for the current session.

@spec working_directory(pid()) :: {:ok, binary() | nil} | {:error, term()}

Get the working directory from the system init data.