ClaudeCode.Supervisor (ClaudeCode v0.3.0)

View Source

Supervisor for managing multiple ClaudeCode sessions.

This supervisor allows you to start and manage multiple named Claude sessions in your application's supervision tree, providing fault tolerance and automatic restart capabilities.

Examples

Basic usage with predefined sessions

children = [
  {ClaudeCode.Supervisor, [
    [name: :code_reviewer, api_key: api_key, system_prompt: "You are an expert code reviewer"],
    [name: :test_writer, api_key: api_key, system_prompt: "You write comprehensive tests"]
  ]}
]

Supervisor.start_link(children, strategy: :one_for_one)

Using global names for distributed access

children = [
  {ClaudeCode.Supervisor, [
    [name: {:global, :main_assistant}, api_key: api_key],
    [name: {:via, Registry, {MyApp.Registry, :helper}}, api_key: api_key]
  ]}
]

Dynamic session management

# Start the supervisor without initial sessions
{:ok, supervisor} = ClaudeCode.Supervisor.start_link([])

# Add sessions dynamically
ClaudeCode.Supervisor.start_session(supervisor, [
  name: :dynamic_session,
  api_key: api_key,
  system_prompt: "Dynamic helper"
])

# Remove sessions when no longer needed
ClaudeCode.Supervisor.terminate_session(supervisor, :dynamic_session)

Session Access

Once supervised, sessions can be accessed by name from anywhere in your application:

# Query a supervised session
{:ok, response} = ClaudeCode.query(:code_reviewer, "Review this function")

# Stream from a supervised session
:test_writer
|> ClaudeCode.query_stream("Write tests for UserController")
|> Stream.each(&IO.inspect/1)
|> Stream.run()

Fault Tolerance

If a session crashes, the supervisor will automatically restart it:

  • Session state is lost but the process name is preserved
  • Conversation history is cleared on restart
  • Other sessions continue running unaffected

Configuration

Sessions inherit application configuration and can override specific options:

# config/config.exs
config :claude_code,
  model: "opus",
  timeout: 300_000

# Supervisor sessions automatically use app config
{ClaudeCode.Supervisor, [
  [name: :assistant, api_key: api_key],  # Uses app config defaults
  [name: :writer, api_key: api_key, model: "sonnet"]  # Overrides model
]}

Summary

Functions

Returns a specification to start this module under a supervisor.

Gets the count of sessions managed by the supervisor.

Lists all sessions currently managed by the supervisor.

Restarts a specific session.

Starts the ClaudeCode supervisor.

Dynamically starts a new session under the supervisor.

Terminates a session managed by the supervisor.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

count_sessions(supervisor)

Gets the count of sessions managed by the supervisor.

Examples

count = ClaudeCode.Supervisor.count_sessions(supervisor)
#=> 3

list_sessions(supervisor)

Lists all sessions currently managed by the supervisor.

Returns a list of {child_id, child_pid, type, modules} tuples.

Examples

sessions = ClaudeCode.Supervisor.list_sessions(supervisor)
#=> [{:assistant, #PID<0.123.0>, :worker, [ClaudeCode.Session]}]

restart_session(supervisor, session_id)

Restarts a specific session.

This will terminate the current session process and start a new one with the same configuration. Note that conversation history will be lost.

Examples

:ok = ClaudeCode.Supervisor.restart_session(supervisor, :assistant)

start_link(sessions, opts \\ [])

Starts the ClaudeCode supervisor.

Arguments

Options

  • :name - Name for the supervisor process (optional)
  • :strategy - Supervision strategy (defaults to :one_for_one)
  • :max_restarts - Maximum restarts allowed (defaults to 3)
  • :max_seconds - Time window for max restarts (defaults to 5)

Examples

# Start with predefined sessions
{:ok, sup} = ClaudeCode.Supervisor.start_link([
  [name: :assistant, api_key: "sk-ant-..."],
  [name: :reviewer, api_key: "sk-ant-...", system_prompt: "Review code"]
])

# Start empty supervisor for dynamic management
{:ok, sup} = ClaudeCode.Supervisor.start_link([])

# Start with custom supervisor options
{:ok, sup} = ClaudeCode.Supervisor.start_link(
  [
    [name: :assistant, api_key: "sk-ant-..."]
  ],
  name: MyApp.ClaudeSupervisor,
  max_restarts: 5,
  max_seconds: 10
)

start_session(supervisor, session_config, opts \\ [])

Dynamically starts a new session under the supervisor.

Arguments

  • supervisor - PID or name of the ClaudeCode.Supervisor
  • session_config - Keyword list of session options

Examples

ClaudeCode.Supervisor.start_session(supervisor, [
  name: :new_assistant,
  api_key: api_key,
  system_prompt: "You are helpful"
])

# With custom child ID
ClaudeCode.Supervisor.start_session(supervisor, [
  name: :temp_session,
  api_key: api_key
], id: :my_temp_session)

terminate_session(supervisor, session_id)

Terminates a session managed by the supervisor.

Arguments

  • supervisor - PID or name of the ClaudeCode.Supervisor
  • session_id - Child ID or session name

Examples

ClaudeCode.Supervisor.terminate_session(supervisor, :old_session)