Examples

Note: Examples are available in the source repository and are not included in the Hex package to minimize download size. Clone the repo to run them locally.

These examples demonstrate real integration with the Claude Code CLI.

Prerequisites

• Claude Code CLI: npm install -g @anthropic-ai/claude-code
• Authentication: claude login (or set ANTHROPIC_API_KEY / CLAUDE_AGENT_OAUTH_TOKEN)

Runtime Config Notes

Some examples that exercise in-process tools and query streaming are affected by runtime config:

# Timeouts and buffer sizes are centralized in Config.* modules:
config :claude_agent_sdk, ClaudeAgentSDK.Config.Timeouts,
  tool_execution_ms: 30_000

# Legacy flat keys still work for non-migrated settings:
config :claude_agent_sdk,
  cli_stream_module: ClaudeAgentSDK.Query.CLIStream,
  task_supervisor_strict: false,
  agents_temp_file_max_age_seconds: 86_400

See the Configuration Internals guide for all tunable constants and their defaults.

process_module is still accepted as a fallback key for query streaming, but it is deprecated.

All live examples call Examples.Support.ensure_live!/0, which starts ClaudeAgentSDK.TaskSupervisor for clean supervised async task execution.

If you enable strict mode (task_supervisor_strict: true) and the configured task supervisor is missing, background task scheduling returns {:error, {:task_supervisor_unavailable, supervisor}} instead of unsupervised fallback.

Transport-level close/missing-command errors normalize to :not_connected and :cli_not_found at query/control boundaries.

For lifecycle tests and demos, transport/session modules also support startup_mode: :lazy to defer subprocess startup until handle_continue/2.

Mix Task Example (Recommended Starting Point)

A complete working example app showing how to integrate Claude into your own Mix project:

mix_task_chat/

• Mix tasks using the SDK
• Real-time streaming responses (typewriter effect)
• Interactive multi-turn conversations
• Simple query-response patterns for scripting

git clone https://github.com/nshkrdotcom/claude_agent_sdk.git
cd claude_agent_sdk/examples/mix_task_chat
mix deps.get
mix chat "Hello, Claude!"           # Streaming response
mix chat --interactive              # Multi-turn conversation
mix ask -q "What is 2+2?"           # Script-friendly output

Running Examples

Run All Examples

bash examples/run_all.sh
bash examples/run_all.sh --ssh-host example.internal
bash examples/run_all.sh --ssh-host example.internal --danger-full-access

Sets CLAUDE_EXAMPLES_FORCE_HALT=true to ensure each script exits cleanly. The runner continues after failures and prints a summary at the end (non-zero exit if any example failed).

run_all.sh now uses one transport-aware live preflight for both local and --ssh-host runs. That means missing CLI, remote auth/access failures, and SSH placement issues are caught before the runner fans out into the full example list.

The preflight timeout is backend-aware:

• Anthropic-backed runs default to 30s
• Ollama-backed runs default to 60s

Set CLAUDE_EXAMPLES_PREFLIGHT_TIMEOUT_SECONDS to override the inner transport budget. The shell wrapper keeps a small extra headroom above that value so compile/startup overhead does not trip the outer timeout before the transport budget does. You can also override that headroom with CLAUDE_EXAMPLES_PREFLIGHT_WRAPPER_HEADROOM_SECONDS.

Run with Ollama

Fastest path:

bash examples/run_all.sh --ollama

This runs the full example list against the Ollama-backed Claude path and defaults to llama3.2.

Pick a different Ollama model:

bash examples/run_all.sh --ollama --ollama-model qwen3.5:14b

Environment-variable form still works:

CLAUDE_EXAMPLES_BACKEND=ollama \
CLAUDE_EXAMPLES_OLLAMA_MODEL=llama3.2 \
bash examples/run_all.sh

Ollama mode keeps the example source on canonical Claude names such as haiku and maps them to the selected Ollama model through the core-owned model registry path.

Examples that depend on unsupported Ollama features now self-skip by default. Set CLAUDE_EXAMPLES_FORCE_UNSUPPORTED=true if you want to force those runs.

If Ollama preflight fails, the first things to check are:

• ANTHROPIC_BASE_URL points at a reachable Ollama server
• the selected model is installed and warmed
• CLAUDE_EXAMPLES_PREFLIGHT_TIMEOUT_SECONDS is high enough for cold-start latency

Run Individual Examples

mix run examples/basic_example.exs
mix run examples/basic_example.exs -- --ssh-host example.internal
mix run examples/basic_example.exs -- --ssh-host example.internal --danger-full-access

Shared SSH Flags

Every CLI-backed example in this directory accepts the same optional SSH transport flags:

• --cwd <path> passes an explicit working directory to the example
• --danger-full-access maps the example to permission_mode: :bypass_permissions
• --ssh-host <host> switches the example to execution_surface: :ssh_exec
• --ssh-user <user> overrides the SSH user
• --ssh-port <port> overrides the SSH port
• --ssh-identity-file <path> sets the SSH identity file

If you omit the SSH flags, the examples keep the existing local subprocess default unchanged.

--danger-full-access only changes the Claude runtime permission posture. It does not change transport placement. Use it when you want the same example to stay on execution_surface: :ssh_exec but run with the permissive Claude mode on a remote host.

Run an individual example with Ollama:

CLAUDE_AGENT_PROVIDER_BACKEND=ollama \
ANTHROPIC_AUTH_TOKEN=ollama \
ANTHROPIC_API_KEY='' \
ANTHROPIC_BASE_URL=http://localhost:11434 \
CLAUDE_AGENT_EXTERNAL_MODEL_OVERRIDES='{"haiku":"llama3.2","sonnet":"llama3.2","opus":"llama3.2","sonnet[1m]":"llama3.2","opus[1m]":"llama3.2","legacy-sonnet":"llama3.2"}' \
mix run examples/basic_example.exs

Example Index

Core Examples

Advanced Features

Streaming

Hooks

Runtime Control

Archived Examples

The archive/ directory contains older or experimental scripts, including mock/transport examples for deterministic testing.

Related Documentation

• Getting Started
• Streaming Guide
• Hooks Guide
• Permissions Guide

Recovery-Oriented Example Lanes

The most relevant examples for session recovery and intervention are the live CLI-backed demos run through examples/run_all.sh. In particular, keep an eye on:

• the live session-oriented examples already in the runner
• the examples that exercise multi-turn state and permissions under the real CLI

Those examples are the public smoke-test lane for the same runtime session surfaces now consumed by upper orchestration repos.