Metadata-Version: 2.4
Name: claude-code-headless
Version: 0.1.2
Summary: Call Claude programmatically using your Claude Max subscription via Claude Code CLI
Project-URL: Homepage, https://github.com/yourusername/claude-code-headless
Project-URL: Repository, https://github.com/yourusername/claude-code-headless
Project-URL: Issues, https://github.com/yourusername/claude-code-headless/issues
License-Expression: MIT
License-File: LICENSE
Keywords: ai,anthropic,claude,claude-code,headless,llm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# Claude Code Headless

[![PyPI version](https://badge.fury.io/py/claude-code-headless.svg)](https://pypi.org/project/claude-code-headless/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

## Installation

```bash
pip install claude-code-headless
```

### Prerequisites

1. [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed:
```bash
npm install -g @anthropic-ai/claude-code
```

2. Login to Claude:
```bash
claude login
```

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

## Quick Start

```python
from claude_code_headless import call_claude

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

## Usage

### Basic Call

```python
from claude_code_headless import call_claude

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

### With System Prompt

```python
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)

```python
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

```python
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

```python
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

```python
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

```python
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"

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

### WSL errors on Windows

```powershell
wsl --install
wsl --set-default Ubuntu
```

## License

MIT
