claude-local

A lightweight local emulator for the Anthropic Claude API, built for testing and local development.

Install it as a LocalStack extension to intercept Claude API calls within your LocalStack-powered test environment — no API key, no network, no credits consumed.

Quick start

LocalStack extension

# Install into a running LocalStack instance
pip install localstack-claude
localstack extensions install localstack-claude

# Or dev mode
make ls-dev

Then point your SDK at:

ANTHROPIC_BASE_URL=http://claude.localhost.localstack.cloud:4566
ANTHROPIC_API_KEY=test-key

API coverage

Supported models

All current Claude models are recognized (by versioned ID or alias):

• claude-opus-4-7 / claude-opus-4-7-20250514
• claude-sonnet-4-6 / claude-sonnet-4-6-20250514
• claude-haiku-4-5 / claude-haiku-4-5-20251001
• claude-3-5-sonnet-20241022, claude-3-5-haiku-20241022
• claude-3-opus-20240229, claude-3-sonnet-20240229, claude-3-haiku-20240307

Response behaviour

The emulator does not call a real LLM. It returns a deterministic response that can be configured:

# Environment variable (set before startup)
CLAUDE_LOCAL_RESPONSE="My custom response"

# Runtime override (POST to the control plane)
curl -s -X POST http://localhost:5002/_claude/config \
  -H "Content-Type: application/json" \
  -d '{"response": "My custom response"}'

Tool use

Force a tool call response by sending the X-Claude-Local-Tool: <tool_name> header, or by setting tool_choice to {"type": "any"} in the request.

Snapshot testing

claude-local ships with snapshot tests that record real Anthropic API responses and verify the emulator produces structurally identical output (using localstack-snapshot).

# Install deps
pip install -e ".[dev,snapshot]"

# Record real API responses
ANTHROPIC_API_KEY=sk-ant-... pytest -m snapshot --snapshot-update

# Verify emulator parity (no key needed)
pytest -m snapshot

Development

make install-dev   # install with dev deps
make test          # run all tests
make run           # start emulator on port 5002
make lint          # ruff check

License

Apache 2.0