ClaudeCode.Supervisor (ClaudeCode v0.3.0)
View SourceSupervisor 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
Returns a specification to start this module under a supervisor.
See Supervisor
.
Gets the count of sessions managed by the supervisor.
Examples
count = ClaudeCode.Supervisor.count_sessions(supervisor)
#=> 3
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]}]
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)
Starts the ClaudeCode supervisor.
Arguments
sessions
- List of session configurations. Each session config is a keyword list of options passed toClaudeCode.Session.start_link/1
.
Options
:name
- Name for the supervisor process (optional):strategy
- Supervision strategy (defaults to:one_for_one
):max_restarts
- Maximum restarts allowed (defaults to3
):max_seconds
- Time window for max restarts (defaults to5
)
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
)
Dynamically starts a new session under the supervisor.
Arguments
supervisor
- PID or name of the ClaudeCode.Supervisorsession_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)
Terminates a session managed by the supervisor.
Arguments
supervisor
- PID or name of the ClaudeCode.Supervisorsession_id
- Child ID or session name
Examples
ClaudeCode.Supervisor.terminate_session(supervisor, :old_session)