claude-lite-llm

A lightweight Python wrapper around Anthropic's claude (Claude Code) CLI that allows developers to run Claude LLMs programmatically using their active Claude Pro/Max subscription via CLAUDE_CODE_TOKEN — bypassing pay-per-token API keys.

Features

• Subscription-Powered: Authenticate using your Claude Code subscription token (CLAUDE_CODE_TOKEN) instead of standard Anthropic API keys.
• LiteLLM / OpenAI Style API: Simple completion(...) and async acompletion(...) functions.
• Flexible Message Formats: Pass raw prompt strings or conversational message dicts ([{"role": "user", "content": "..."}]).
• Structured Responses: Access generated text, token usage metrics, latency, and session IDs.
• Safe Execution: Disables built-in CLI tool execution (file editing / bash execution) by default for pure text completions.
• Granular Error Handling: Dedicated exceptions for rate limits (session quota / 429), authentication failures, and CLI execution errors.

Installation

pip install claude-lite-llm

Prerequisites

Ensure the Claude Code CLI is installed on your system:

npm install -g @anthropic-ai/claude-code
# or native install:
# curl -fsSL https://claude.ai/install.sh | bash

Generate your subscription token (or retrieve your existing session token):

claude setup-token

Add the token to your .env file or export it:

CLAUDE_CODE_TOKEN=sk-ant-oat01-...

Usage

1. Basic Completion

from claude_lite_llm import completion

response = completion("Explain quantum computing in 2 sentences.")
print(response.content)
print(f"Tokens: {response.usage.input_tokens} in / {response.usage.output_tokens} out")

2. Multi-Message Conversation

from claude_lite_llm import completion

messages = [
    {"role": "system", "content": "You are an expert Python architect."},
    {"role": "user", "content": "What is the best way to structure an async CLI wrapper?"},
]

response = completion(messages, model="sonnet")
print(response.content)

3. Using ClaudeClient

from claude_lite_llm import ClaudeClient

client = ClaudeClient(
    token="sk-ant-...",  # Optional: loads from CLAUDE_CODE_TOKEN by default
    default_model="sonnet",  # 'sonnet', 'opus', or 'haiku'
)

response = client.completion("Draft a quick haiku about coding.")
print(response.content)

4. Asynchronous Completion

import asyncio
from claude_lite_llm import acompletion


async def main():
    response = await acompletion("Write a unit test with pytest for a palindrome function.")
    print(response.content)


asyncio.run(main())

5. Handling Rate Limits & Errors

When session limits or quota thresholds are reached on your Claude subscription, claude-lite-llm raises typed exceptions:

from claude_lite_llm import completion
from claude_lite_llm.exceptions import ClaudeRateLimitError, ClaudeAuthError

try:
    response = completion("Hello Claude!")
    print(response.content)
except ClaudeRateLimitError as e:
    # Captures 429 session limits and subscription reset times
    print(f"Rate limit reached: {e}")
except ClaudeAuthError as e:
    print(f"Authentication failure: {e}")

Development

uv sync --all-extras --dev
uv run pytest
uv run ruff check .
uv run mypy

Install the git hooks once after cloning:

uv run pre-commit install

Make targets

License

MIT