Claude Code Headless

Call Claude programmatically using your Claude Max subscription via Claude Code CLI - no API key required.

Installation

pip install claude-code-headless

Prerequisites

1. Claude Code CLI installed:

npm install -g @anthropic-ai/claude-code

2. Login to Claude:

claude login

3. WSL (Windows Subsystem for Linux) if running on Windows

Quick Start

from claude_code_headless import call_claude

response = call_claude("What is the capital of France?")
print(response)  # Paris

Usage

Basic Call

from claude_code_headless import call_claude

response = call_claude("Explain Python in one sentence.")
print(response)

With System Prompt

from claude_code_headless import call_claude_with_system

response = call_claude_with_system(
    prompt="Explain quantum computing",
    system="You are a teacher explaining to a 10-year-old."
)
print(response)

JSON Output (with metadata)

from claude_code_headless import call_claude_json

response = call_claude_json("What is 2 + 2?")
print(response["result"])  # 4
print(response["usage"])   # Token usage stats

Streaming Output

from claude_code_headless import call_claude_streaming

# Print as it streams
call_claude_streaming("Write a poem about coding")

# Or use a callback
chunks = []
call_claude_streaming(
    "Write a poem",
    callback=lambda chunk: chunks.append(chunk)
)

With Tools

from claude_code_headless import call_claude

# Allow Claude to read files
response = call_claude(
    "Summarize the contents of README.md",
    allowed_tools=["Read"]
)

Available tools: Read, Edit, Write, Bash, Glob, Grep, WebSearch, WebFetch

Class-based Interface

from claude_code_headless import ClaudeClient

client = ClaudeClient(
    default_tools=["Read"],
    default_system="Be concise and helpful."
)

response = client.ask("What files are in this directory?")
print(response)

# JSON response
data = client.ask_json("Count to 5")
print(data["result"])

API Reference

Functions

Function	Description
call_claude(prompt, allowed_tools=None)	Basic call, returns text
call_claude_with_system(prompt, system)	Call with system prompt
call_claude_json(prompt, allowed_tools=None)	Returns full JSON with metadata
call_claude_streaming(prompt, allowed_tools=None, callback=None)	Streaming output

ClaudeClient Class

client = ClaudeClient(
    default_tools=None,    # Default tools for all calls
    default_system=None    # Default system prompt
)

client.ask(prompt, tools=None, system=None)        # Text response
client.ask_json(prompt, tools=None)                # JSON response
client.ask_streaming(prompt, tools=None, callback=None)  # Streaming

Platform Support

Platform	Support
Windows (CMD, PowerShell, Git Bash)	Via WSL
WSL	Native
Linux	Native
macOS	Native

How It Works

This package wraps Claude Code's headless mode (-p flag), routing calls through the CLI:

Python → Claude Code CLI → Claude API (using Max subscription)

On Windows, commands are automatically routed through WSL.

Comparison: API vs Claude Code Headless

Feature	Claude API	Claude Code Headless
Cost	Pay per token	Included in Max subscription
Setup	API key required	Just login
Tools	Manual implementation	Built-in (Read, Edit, Bash, etc.)
Best for	Production apps	Scripts, automation, prototyping

Troubleshooting

"claude: command not found"

npm install -g @anthropic-ai/claude-code
claude --version

WSL errors on Windows

wsl --install
wsl --set-default Ubuntu

License

MIT