claude-runner

The easiest way to build AI agents with Claude in Python. 5 lines to start.

The official SDK is an engine 🔧 — claude-runner is the car 🚗.

A thin, clean wrapper around the Anthropic SDK. Zero required dependencies.

from claude_runner import Runner

runner = Runner(api_key="sk-ant-...")
result = await runner.run("Analyze this codebase and suggest improvements")
print(result.text)

Also available as a TypeScript/npm package.

Install

# API Mode — no CLI needed, deploys anywhere
pip install claude-runner-py[api]

# Agent Mode — full Claude Code power (needs CLI)
pip install claude-runner-py[agent]

# Everything
pip install claude-runner-py[all]

Quick Start

Simple await

import asyncio
from claude_runner import Runner

async def main():
    runner = Runner(api_key="sk-ant-...")
    result = await runner.run("Fix the failing tests in this project")

    print(result.text)
    print(f"Cost: ${result.cost:.4f}")
    print(f"Turns: {result.turns}")

asyncio.run(main())

Streaming

async for event in runner.stream("Refactor the auth module"):
    match event.type:
        case "text":
            print(event.text, end="", flush=True)
        case "tool_start":
            print(f"  → {event.tool}")
        case "tool_end":
            print(f"  ← {event.tool} ({event.duration:.0f}ms)")
        case "done":
            print(f"\nCost: ${event.result.cost:.4f}")

Custom Tools

from claude_runner import Runner, define_tool, ToolResult

async def get_weather(city: str) -> ToolResult:
    return ToolResult(content=[{"type": "text", "text": f"72°F and sunny in {city}"}])

weather = define_tool(
    "get_weather",
    "Get current weather for a city",
    {"city": {"type": "string"}},
    get_weather,
)

runner = Runner(api_key="sk-ant-...", tools=[weather])
result = await runner.run("What's the weather in San Francisco?")

CLI

# With API key
ANTHROPIC_API_KEY=sk-xxx claude-runner "Analyze this codebase"
claude-runner --api-key sk-xxx "Fix the tests"

# Choose model
claude-runner -m opus "Refactor the auth module"

# JSON output
claude-runner --json "What files are in this project?"

API Mode vs Agent Mode

Models

Runner(model="opus")       # claude-opus-4-6
Runner(model="sonnet")     # claude-sonnet-4-6
Runner(model="haiku")      # claude-haiku-4-5
Runner(model="opus-4.5")   # claude-opus-4-5-20250918
Runner(model="sonnet-4.5") # claude-sonnet-4-5-20250514

Real-World Use Cases

FastAPI endpoint

@app.post("/chat")
async def chat(message: str):
    runner = Runner(api_key=os.environ["ANTHROPIC_API_KEY"])
    result = await runner.run(message)
    return {"reply": result.text, "cost": result.cost}

Data analysis

runner = Runner(api_key=key, model="haiku")
result = await runner.run(f"Analyze this CSV:\n{csv_data}")

Slack bot

@app.event("message")
async def handle(event):
    runner = Runner(api_key=key, tools=[search_docs, query_db])
    result = await runner.run(event["text"])
    await say(result.text)

Examples

API Reference

Runner

class Runner:
    def __init__(self, **kwargs) -> None
    async def run(self, prompt: str) -> RunResult
    async def stream(self, prompt: str) -> AsyncIterator[RunEvent]
    @property
    def last_session_id(self) -> str | None

RunResult

@dataclass
class RunResult:
    text: str
    session_id: str
    cost: float          # USD
    duration: float      # ms
    usage: dict          # {"input": N, "output": N}
    turns: int
    tool_calls: list[ToolCallSummary]
    error: str | None

RunEvent types

RunnerOptions

Links

• TypeScript version: github.com/SanthoshDhandapani/claude-runner
• npm: npmjs.com/package/claude-runner

License

MIT