@spec account_info(session()) ::
  {:ok, ClaudeCode.Session.AccountInfo.t() | nil} | {:error, term()}

Returns account information from the initialization response.

Examples

{:ok, account} = ClaudeCode.Session.account_info(session)
IO.puts(account.email)

@spec alive?(session()) :: boolean()

Checks if a session is alive.

Examples

true = ClaudeCode.Session.alive?(session)

@spec clear(session()) :: :ok

Clears the current session ID to start a fresh conversation.

This will cause the next query to start a new conversation context rather than continuing the existing one. Useful when you want to reset the conversation history.

Examples

:ok = ClaudeCode.Session.clear(session)

# Next stream will start fresh
ClaudeCode.Session.stream(session, "Hello!")
|> Enum.each(&IO.inspect/1)

@spec conversation(
  session() | String.t(),
  keyword()
) ::
  {:ok,
   [
     ClaudeCode.Message.AssistantMessage.t()
     | ClaudeCode.Message.UserMessage.t()
   ]}
  | {:error, term()}

Reads conversation history from a session's JSONL file.

Accepts either a session ID string or a running session reference. Returns user and assistant messages parsed into SDK message structs.

Options

• :project_path - Specific project path to search in (optional)
• :claude_dir - Override the Claude directory (default: ~/.claude)

Examples

# Read conversation history by session ID
{:ok, messages} = ClaudeCode.Session.conversation("abc123-def456")

# Or from a running session
{:ok, session} = ClaudeCode.start_link()
ClaudeCode.Session.stream(session, "Hello!") |> Stream.run()
{:ok, messages} = ClaudeCode.Session.conversation(session)

See ClaudeCode.History for more options.

@spec health(session()) :: ClaudeCode.Adapter.health()

Returns the health status of the session's adapter.

Examples

:healthy = ClaudeCode.Session.health(session)
{:unhealthy, :port_dead} = ClaudeCode.Session.health(session)

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

Interrupts the current generation.

Sends an interrupt signal to the CLI to stop the current generation. This is a fire-and-forget operation — the CLI will stop generating and emit a result message.

Examples

:ok = ClaudeCode.Session.interrupt(session)

@spec mcp_reconnect(session(), String.t()) :: :ok | {:error, term()}

Reconnects a disconnected or failed MCP server.

Examples

:ok = ClaudeCode.Session.mcp_reconnect(session, "my-server")

@spec mcp_status(session()) :: {:ok, [ClaudeCode.MCP.Status.t()]} | {:error, term()}

Queries MCP server connection status.

Examples

{:ok, servers} = ClaudeCode.Session.mcp_status(session)
Enum.each(servers, &IO.puts(&1.name))

@spec mcp_toggle(session(), String.t(), boolean()) :: :ok | {:error, term()}

Enables or disables an MCP server.

Examples

:ok = ClaudeCode.Session.mcp_toggle(session, "my-server", false)

@spec rewind_files(session(), String.t(), keyword()) ::
  {:ok, ClaudeCode.CLI.Control.Types.rewind_files_result()} | {:error, term()}

Rewinds tracked files to the state at a specific user message checkpoint.

Options

• :dry_run - When true, preview changes without applying them (default: false)

Examples

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

# Preview changes without applying
{:ok, preview} = ClaudeCode.Session.rewind_files(session, "user-msg-uuid-123", dry_run: true)

@spec server_info(session()) ::
  {:ok, ClaudeCode.CLI.Control.Types.initialize_response() | nil}
  | {:error, term()}

Gets server initialization info cached from the control handshake.

Examples

{:ok, info} = ClaudeCode.Session.server_info(session)

@spec session_id(session()) :: String.t() | nil

Gets the current session ID for conversation continuity.

Returns the session ID that Claude CLI is using to maintain conversation context. This ID is automatically captured from CLI responses and used for subsequent queries to continue the conversation.

You can use this session ID with the :resume option when starting a new session to continue the conversation later, or with :fork_session to create a branch.

Examples

session_id = ClaudeCode.Session.session_id(session)
# => "abc123-session-id"

# For a new session with no queries yet
nil = ClaudeCode.Session.session_id(session)

# Resume later
{:ok, new_session} = ClaudeCode.start_link(resume: session_id)

# Or fork the conversation
{:ok, forked} = ClaudeCode.start_link(resume: session_id, fork_session: true)

@spec set_mcp_servers(session(), map()) ::
  {:ok, ClaudeCode.CLI.Control.Types.set_servers_result()} | {:error, term()}

Replaces the set of dynamically managed MCP servers.

Examples

{:ok, _} = ClaudeCode.Session.set_mcp_servers(session, %{"tools" => %{"type" => "stdio", "command" => "npx"}})

@spec set_model(session(), String.t()) :: :ok | {:error, term()}

Changes the model mid-conversation.

Examples

:ok = ClaudeCode.Session.set_model(session, "claude-sonnet-4-5-20250929")

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

Changes the permission mode mid-conversation.

Examples

:ok = ClaudeCode.Session.set_permission_mode(session, :bypass_permissions)

@spec start_link(keyword()) :: GenServer.on_start()

Starts a new Claude Code session.

See ClaudeCode.start_link/1 for full documentation and examples.

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

Stops a Claude Code session.

This closes the CLI subprocess and cleans up resources.

Examples

:ok = ClaudeCode.Session.stop(session)

@spec stop_task(session(), String.t()) :: :ok | {:error, term()}

Stops a running task.

A task_notification with status 'stopped' will be emitted.

Examples

:ok = ClaudeCode.Session.stop_task(session, "task-id-123")

@spec stream(session(), String.t(), keyword()) :: Enumerable.t(ClaudeCode.Message.t())

Sends a query to a session and returns a stream of messages.

See ClaudeCode.stream/3 for full documentation and examples.

@spec supported_agents(session()) ::
  {:ok, [ClaudeCode.Session.AgentInfo.t()]} | {:error, term()}

Returns the list of available subagents from the initialization response.

Examples

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

@spec supported_commands(session()) ::
  {:ok, [ClaudeCode.Session.SlashCommand.t()]} | {:error, term()}

Returns the list of available commands from the initialization response.

Examples

{:ok, commands} = ClaudeCode.Session.supported_commands(session)
Enum.each(commands, &IO.puts(&1.name))

@spec supported_models(session()) ::
  {:ok, [ClaudeCode.Model.Info.t()]} | {:error, term()}

Returns the list of available models from the initialization response.

Examples

{:ok, models} = ClaudeCode.Session.supported_models(session)
Enum.each(models, &IO.puts(&1.display_name))