claude-lite-llm

A lightweight Python wrapper around Anthropic's Claude Code CLI and OpenAI's Codex CLI that allows developers to run Claude and ChatGPT LLMs programmatically using their active subscriptions (CLAUDE_CODE_TOKEN and ChatGPT account / CODEX_ACCESS_TOKEN) — bypassing pay-per-token API keys.

Also includes built-in custom providers for LiteLLM (ClaudeSubscriptionProvider, CodexSubscriptionProvider, and register_with_litellm).

Features

• Subscription-Powered: Authenticate using Claude Code (CLAUDE_CODE_TOKEN) and OpenAI Codex CLI subscriptions.
• Claude & Codex CLI Support: Unified programmatic access to Anthropic Claude (Sonnet, Opus, Haiku) and OpenAI Codex (o3-mini, o3, gpt-4o).
• LiteLLM Native Integration: Exported ClaudeSubscriptionProvider and CodexSubscriptionProvider classes plus 1-line register_with_litellm() for litellm.completion(model="claude_sub/sonnet").
• 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 tool execution and runs sandboxed (read-only) 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

# With LiteLLM support:
pip install "claude-lite-llm[litellm]"

Prerequisites

1. Claude CLI (if using Claude models):

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

   Add CLAUDE_CODE_TOKEN to your app's .env:

   CLAUDE_CODE_TOKEN=sk-ant-oat01-...
   

2. Codex CLI (if using Codex / ChatGPT models):

   npm install -g @openai/codex
   codex login
   

   Or provide CODEX_ACCESS_TOKEN in .env.

Usage

1. Claude Completion

from claude_lite_llm import completion

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

2. Codex Completion (OpenAI / ChatGPT)

from claude_lite_llm import codex_completion

response = codex_completion("Write a Python function to reverse a linked list.", model="o3-mini")
print(response.content)
print(f"Tokens: {response.usage.input_tokens} in / {response.usage.output_tokens} out")

3. Native Integration with LiteLLM

Use register_with_litellm() to route any LiteLLM call through your Claude or Codex subscription:

import litellm
from claude_lite_llm import register_with_litellm

# Register 'claude_sub' and 'codex_sub' custom providers in LiteLLM
register_with_litellm()

# Call Claude via subscription in LiteLLM
claude_res = litellm.completion(
    model="claude_sub/sonnet",
    messages=[{"role": "user", "content": "Explain async/await in Python."}],
)
print(claude_res.choices[0].message.content)

# Call Codex via subscription in LiteLLM
codex_res = litellm.completion(
    model="codex_sub/o3-mini",
    messages=[{"role": "user", "content": "Write a binary search in Python."}],
)
print(codex_res.choices[0].message.content)

You can also instantiate the providers directly:

from claude_lite_llm import ClaudeSubscriptionProvider, CodexSubscriptionProvider
import litellm

litellm.custom_provider_map = [
    {"provider": "my_claude", "custom_handler": ClaudeSubscriptionProvider()},
    {"provider": "my_codex", "custom_handler": CodexSubscriptionProvider()},
]

4. Asynchronous Completions

import asyncio
from claude_lite_llm import acompletion, codex_acompletion


async def main():
    claude_res = await acompletion("Hello from Claude async!")
    print("Claude:", claude_res.content)

    codex_res = await codex_acompletion("Hello from Codex async!", model="o3-mini")
    print("Codex:", codex_res.content)


asyncio.run(main())

5. Handling Rate Limits & Errors

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

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