pydantic-claude-code 0.1.0__tar.gz

pydantic_claude_code-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/

pydantic_claude_code-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Pfaffenberger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pydantic_claude_code-0.1.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.5
+Name: pydantic-claude-code
+Version: 0.1.0
+Summary: Use your Claude Code subscription from a Pydantic AI Agent, with full tool support
+Project-URL: Repository, https://github.com/mpfaffenberger/pydantic-ai-claude-code
+Project-URL: Homepage, https://pypi.org/project/pydantic-claude-code/
+Author: Michael Pfaffenberger
+License: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: <3.15,>=3.11
+Requires-Dist: pydantic-ai-slim[anthropic]<3,>=2.31.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.1; extra == 'dev'
+Requires-Dist: pytest>=8.3.4; extra == 'dev'
+Requires-Dist: ruff<0.16,>=0.15; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pydantic-claude-code
+
+Use your Claude Code subscription from a plain pydantic-ai `Agent`, with full
+pydantic-ai tool support. No API key, no separate billing: if Claude Code works
+from your terminal, this wheel works too.
+
+The repo is `mpfaffenberger/pydantic-ai-claude-code` and the import is
+`pydantic_ai_claude_code`; the PyPI project is `pydantic-claude-code`
+(`pip install pydantic-claude-code`).
+
+## Why
+
+pydantic-ai gained a Codex OAuth path where `openai-codex:gpt-6-astra` just
+works against a ChatGPT subscription. This wheel brings the same experience to
+Claude: authenticate once, then run pydantic-ai agents against your Claude
+subscription, using `claude-sonnet-4-5`, `claude-opus-5`, or whatever model you
+subscribe to.
+
+Two deliberate design choices distinguish this from a fork of pydantic-ai:
+
+1. **pydantic-ai owns the loop.** We don't hand the whole agent loop to the
+   Claude Code CLI. pydantic-ai's own `Agent` machinery drives the conversation,
+   executes your tools, and validates structured output. The wheel is a model
+   + provider, not a second agent fighting for control.
+2. **Object-only resolution.** Instead of a `claude-code:` model-name string
+   (which would require patching pydantic-ai's internals), pass the model
+   object you build from the provider.
+
+## Quick start
+
+```python
+import asyncio
+
+from pydantic_ai import Agent
+
+from pydantic_ai_claude_code import ClaudeCodeProvider, login
+
+async def main() -> None:
+    # One-time: opens your browser, mints tokens, stores them
+    # (only needs to run again when tokens are revoked).
+    await login()
+
+    provider = ClaudeCodeProvider()  # loads the stored tokens
+    agent = Agent(provider.model('claude-sonnet-4-5'))
+
+    result = await agent.run('Say hi in three words.')
+    print(result.data)
+
+asyncio.run(main())
+```
+
+### With tools
+
+```python
+from pydantic_ai import Agent
+
+provider = ClaudeCodeProvider()
+agent = Agent(provider.model('claude-sonnet-4-5'))
+
+@agent.tool_plain
+def add(a: int, b: int) -> int:
+    """Add two numbers."""
+    return a + b
+```
+
+Tools defined on the agent are passed to the API as standard Anthropic tool
+definitions, and structured output works the same way as with the built-in
+`anthropic` provider. That's the whole point of the wheel.
+
+## How auth works
+
+The flow uses the same shared OAuth client the Claude Code CLI uses:
+
+- Authorization URL: `https://claude.ai/oauth/authorize`
+- Token URL: `https://platform.claude.com/v1/oauth/token`
+- Scopes: `org:create_api_key user:profile user:inference`
+
+Tokens are stored in (overridable via `CLAUDE_CODE_AUTH_FILE`):
+
+```
+~/.local/share/pydantic-ai-claude-code/auth.json
+```
+
+The file is written with `0o600` permissions and only ever contains what the
+issuer gave us. We never read the CLI's own credential files.
+
+Refreshes happen automatically in the background: the auth shim refreshes
+before expiry and retries once on a 401, exactly like the codex provider does.
+
+Requests identify as Claude Code: `"You are Claude Code, Anthropic's official
+CLI for Claude."` is prepended to the system context (position 0), the same
+persona the CLI sends. The subscription backend expects it and rate-gates
+premium models without it.
+
+## Security and scope
+
+This is a plain Anthropic Messages API client authenticated by your Claude
+subscription tokens. It does not run the Claude Code CLI in a subprocess, so it
+does not inherit Claude Code's sandboxing, permission prompts, or hooks. Treat
+it like any code-executing agent: only give it tools you trust.
+
+Projects using this are responsible for following Anthropic's rules for using
+Claude Code credentials in their own products.
+
+## Development
+
+```bash
+uv sync --extra dev  # or: source .venv/bin/activate && pip install -e ".[dev]"
+ruff check src tests
+pytest
+```
+
+## Prior art
+
+The OAuth mechanics (shared client id, PKCE, token storage and refresh) are
+lifted from the `claude_code_oauth` plugin in
+[`code_puppy_core_plugins`](https://github.com/mpfaffenberger/code_puppy_core_plugins),
+cleaned up and reshaped around the provider pattern in pydantic-ai.

pydantic_claude_code-0.1.0/README.md

@@ -0,0 +1,118 @@
+# pydantic-claude-code
+
+Use your Claude Code subscription from a plain pydantic-ai `Agent`, with full
+pydantic-ai tool support. No API key, no separate billing: if Claude Code works
+from your terminal, this wheel works too.
+
+The repo is `mpfaffenberger/pydantic-ai-claude-code` and the import is
+`pydantic_ai_claude_code`; the PyPI project is `pydantic-claude-code`
+(`pip install pydantic-claude-code`).
+
+## Why
+
+pydantic-ai gained a Codex OAuth path where `openai-codex:gpt-6-astra` just
+works against a ChatGPT subscription. This wheel brings the same experience to
+Claude: authenticate once, then run pydantic-ai agents against your Claude
+subscription, using `claude-sonnet-4-5`, `claude-opus-5`, or whatever model you
+subscribe to.
+
+Two deliberate design choices distinguish this from a fork of pydantic-ai:
+
+1. **pydantic-ai owns the loop.** We don't hand the whole agent loop to the
+   Claude Code CLI. pydantic-ai's own `Agent` machinery drives the conversation,
+   executes your tools, and validates structured output. The wheel is a model
+   + provider, not a second agent fighting for control.
+2. **Object-only resolution.** Instead of a `claude-code:` model-name string
+   (which would require patching pydantic-ai's internals), pass the model
+   object you build from the provider.
+
+## Quick start
+
+```python
+import asyncio
+
+from pydantic_ai import Agent
+
+from pydantic_ai_claude_code import ClaudeCodeProvider, login
+
+async def main() -> None:
+    # One-time: opens your browser, mints tokens, stores them
+    # (only needs to run again when tokens are revoked).
+    await login()
+
+    provider = ClaudeCodeProvider()  # loads the stored tokens
+    agent = Agent(provider.model('claude-sonnet-4-5'))
+
+    result = await agent.run('Say hi in three words.')
+    print(result.data)
+
+asyncio.run(main())
+```
+
+### With tools
+
+```python
+from pydantic_ai import Agent
+
+provider = ClaudeCodeProvider()
+agent = Agent(provider.model('claude-sonnet-4-5'))
+
+@agent.tool_plain
+def add(a: int, b: int) -> int:
+    """Add two numbers."""
+    return a + b
+```
+
+Tools defined on the agent are passed to the API as standard Anthropic tool
+definitions, and structured output works the same way as with the built-in
+`anthropic` provider. That's the whole point of the wheel.
+
+## How auth works
+
+The flow uses the same shared OAuth client the Claude Code CLI uses:
+
+- Authorization URL: `https://claude.ai/oauth/authorize`
+- Token URL: `https://platform.claude.com/v1/oauth/token`
+- Scopes: `org:create_api_key user:profile user:inference`
+
+Tokens are stored in (overridable via `CLAUDE_CODE_AUTH_FILE`):
+
+```
+~/.local/share/pydantic-ai-claude-code/auth.json
+```
+
+The file is written with `0o600` permissions and only ever contains what the
+issuer gave us. We never read the CLI's own credential files.
+
+Refreshes happen automatically in the background: the auth shim refreshes
+before expiry and retries once on a 401, exactly like the codex provider does.
+
+Requests identify as Claude Code: `"You are Claude Code, Anthropic's official
+CLI for Claude."` is prepended to the system context (position 0), the same
+persona the CLI sends. The subscription backend expects it and rate-gates
+premium models without it.
+
+## Security and scope
+
+This is a plain Anthropic Messages API client authenticated by your Claude
+subscription tokens. It does not run the Claude Code CLI in a subprocess, so it
+does not inherit Claude Code's sandboxing, permission prompts, or hooks. Treat
+it like any code-executing agent: only give it tools you trust.
+
+Projects using this are responsible for following Anthropic's rules for using
+Claude Code credentials in their own products.
+
+## Development
+
+```bash
+uv sync --extra dev  # or: source .venv/bin/activate && pip install -e ".[dev]"
+ruff check src tests
+pytest
+```
+
+## Prior art
+
+The OAuth mechanics (shared client id, PKCE, token storage and refresh) are
+lifted from the `claude_code_oauth` plugin in
+[`code_puppy_core_plugins`](https://github.com/mpfaffenberger/code_puppy_core_plugins),
+cleaned up and reshaped around the provider pattern in pydantic-ai.

pydantic_claude_code-0.1.0/examples/basic.py

@@ -0,0 +1,30 @@
+"""Run the OAuth web flow, then run a real agent on `claude-fable-5-1`.
+
+Requires a Claude (chat) subscription and a browser. Run:
+
+    python examples/basic.py
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+from pydantic_ai import Agent
+
+from pydantic_ai_claude_code import ClaudeCodeProvider, ClaudeCodeTokenStore, login
+
+
+async def main() -> None:
+    # Only run the browser flow when no usable credentials are stored yet.
+    if ClaudeCodeTokenStore().load() is None:
+        await login()
+
+    provider = ClaudeCodeProvider()
+    agent = Agent(provider.model("claude-fable-5-1"))
+
+    result = await agent.run("Say hi in exactly three words.")
+    print("Agent said:", result.output)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

pydantic_claude_code-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pydantic-claude-code"
+version = "0.1.0"
+description = "Use your Claude Code subscription from a Pydantic AI Agent, with full tool support"
+readme = "README.md"
+requires-python = ">=3.11,<3.15"
+dependencies = [
+    "pydantic-ai-slim[anthropic]>=2.31.0,<3",
+]
+license = { text = "MIT" }
+authors = [{ name = "Michael Pfaffenberger" }]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Repository = "https://github.com/mpfaffenberger/pydantic-ai-claude-code"
+Homepage = "https://pypi.org/project/pydantic-claude-code/"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pydantic_ai_claude_code"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+addopts = "-q"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3.4",
+    "pytest-asyncio>=0.23.1",
+    "ruff>=0.15,<0.16",
+]

pydantic_claude_code-0.1.0/src/pydantic_ai_claude_code/__init__.py

@@ -0,0 +1,35 @@
+"""Use your Claude Code subscription from a Pydantic AI Agent.
+
+Quick start:
+
+    from pydantic_ai import Agent
+    from pydantic_ai_claude_code import ClaudeCodeProvider
+
+    provider = ClaudeCodeProvider()
+    agent = Agent(provider.model('claude-sonnet-4-5'))
+"""
+
+from .credentials import ClaudeCodeCredentials
+from .flow import (
+    ClaudeCodeOAuthFlow,
+    exchange_code,
+    login,
+    parse_pasteback,
+    refresh_credentials,
+)
+from .model import ClaudeCodeModel
+from .provider import ClaudeCodeProvider
+from .storage import ClaudeCodeTokenStore, default_auth_path
+
+__all__ = [
+    "ClaudeCodeCredentials",
+    "ClaudeCodeModel",
+    "ClaudeCodeOAuthFlow",
+    "ClaudeCodeProvider",
+    "ClaudeCodeTokenStore",
+    "default_auth_path",
+    "exchange_code",
+    "login",
+    "parse_pasteback",
+    "refresh_credentials",
+]

pydantic_claude_code-0.1.0/src/pydantic_ai_claude_code/__main__.py

@@ -0,0 +1,19 @@
+"""Run `python -m pydantic_ai_claude_code login` to authenticate."""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+
+from . import login
+
+
+def main() -> None:
+    if "login" not in sys.argv[1:]:
+        print("Usage: python -m pydantic_ai_claude_code login", file=sys.stderr)
+        sys.exit(2)
+    asyncio.run(login())
+
+
+if __name__ == "__main__":
+    main()

pydantic_claude_code-0.1.0/src/pydantic_ai_claude_code/auth.py

@@ -0,0 +1,83 @@
+"""httpx2 auth shim that authenticates Messages API calls with Claude Code tokens."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import AsyncGenerator, Awaitable, Callable
+
+import httpx2
+
+from pydantic_ai.exceptions import UserError
+
+from . import config
+from .credentials import ClaudeCodeCredentials
+from .flow import refresh_credentials
+
+CredentialsRefreshCallback = Callable[[ClaudeCodeCredentials], Awaitable[None]]
+
+
+class ClaudeCodeCredentialsPersistenceError(UserError):
+    """Raised after refreshed in-memory credentials could not be persisted."""
+
+
+def _expires_soon(credentials: ClaudeCodeCredentials) -> bool:
+    if credentials.expires_at is None:
+        return False
+    return time.time() + 30 >= credentials.expires_at.timestamp()
+
+
+class _ClaudeCodeAuth(httpx2.Auth):
+    requires_response_body = True
+
+    def __init__(self, credentials: ClaudeCodeCredentials, callback: CredentialsRefreshCallback | None = None) -> None:
+        self.credentials = credentials
+        self.callback = callback
+        self.revision = 0
+        self.lock = asyncio.Lock()
+        self.refresh_client = httpx2.AsyncClient()
+
+    async def _refresh(self, used_revision: int) -> None:
+        async with self.lock:
+            if self.revision != used_revision:
+                return
+            updated = await refresh_credentials(self.credentials, http_client=self.refresh_client)
+            self.credentials = updated
+            self.revision += 1
+            if self.callback is not None:
+                try:
+                    await self.callback(updated)
+                except Exception as exc:  # noqa: BLE001 - surface the persistence failure to the caller
+                    raise ClaudeCodeCredentialsPersistenceError(
+                        "Claude Code credentials refreshed in memory, but the persistence callback failed."
+                    ) from exc
+
+    def _apply(self, request: httpx2.Request) -> int:
+        # Subscription tokens are `Authorization: Bearer` credentials, not API keys.
+        # The SDK injects `x-api-key` from the placeholder `api_key`, so it must be
+        # removed or the server validates it first and rejects it as an API key.
+        if "x-api-key" in request.headers:
+            del request.headers["x-api-key"]
+        request.headers["Authorization"] = f"Bearer {self.credentials.token}"
+        request.headers["x-app"] = config.X_APP
+        request.headers["user-agent"] = config.USER_AGENT
+        # Anthropic's SDK manages its own betas; ours must be merged, not replaced.
+        existing_beta = request.headers.get("anthropic-beta")
+        if config.ANTHROPIC_BETA not in (existing_beta or ""):
+            request.headers["anthropic-beta"] = ", ".join(filter(None, [existing_beta, config.ANTHROPIC_BETA]))
+
+        return self.revision
+
+    async def async_auth_flow(self, request: httpx2.Request) -> AsyncGenerator[httpx2.Request, httpx2.Response]:
+        revision = self._apply(request)
+        if _expires_soon(self.credentials):
+            await self._refresh(revision)
+            revision = self._apply(request)
+        response = yield request
+        if response.status_code != 401:
+            return
+        await response.aread()
+        await response.aclose()
+        await self._refresh(revision)
+        self._apply(request)
+        yield request

pydantic_claude_code-0.1.0/src/pydantic_ai_claude_code/config.py

@@ -0,0 +1,44 @@
+"""OAuth endpoint and client configuration for Claude Code authentication.
+
+These constants were verified against the Claude Code CLI 2.1.263 binary
+(embedded config) and its published client metadata:
+
+- `https://claude.ai/oauth/claude-code-client-metadata` (dynamic client registration)
+- Authorization server: `https://claude.com/cai/oauth/authorize`
+- Token endpoint: `https://platform.claude.com/v1/oauth/token`
+
+The shared `9d1c250a...` client id is the public client the official CLI uses,
+so our flow presents the same credentials to Anthropic's authorization server.
+See `flow.py` for the authorization-code flow, and `provider.py` for the API client.
+"""
+
+# OAuth endpoints and the shared public client id used by the Claude Code CLI.
+AUTH_URL = "https://claude.ai/oauth/authorize"
+TOKEN_URL = "https://platform.claude.com/v1/oauth/token"
+CLIENT_ID = "9d1c250a-e61b-44d9-88ed-5944d1962f5e"
+# Same scope set the plugin in `code_puppy_core_plugins` uses. The binary's
+# `user:ccr_inference` scope is not recognized by the authorization server.
+SCOPES = "org:create_api_key user:profile user:inference"
+
+# The subscription tokens minted by this flow are valid against api.anthropic.com.
+API_BASE_URL = "https://api.anthropic.com"
+
+# Must open the system context when authenticating with Claude Code tokens. This
+# is the exact persona string the official CLI sends; the subscription backend
+# expects it at position 0.
+CLAUDE_CODE_SYSTEM_PROMPT = "You are Claude Code, Anthropic's official CLI for Claude."
+
+# Redirect handling. We host a short-lived callback server on localhost. The
+# authorization server accepts `http://localhost:<any port>/callback` but
+# rejects `127.0.0.1` variants, so the host must stay `localhost`.
+REDIRECT_HOST = "http://localhost"
+REDIRECT_PATH = "callback"
+CALLBACK_PORT_RANGE = (8765, 8795)
+CALLBACK_TIMEOUT = 180
+PASTEBACK_SCHEMES = ("claude://",)
+
+# Request headers that must accompany Claude Code subscription tokens. `anthropic-beta` is
+# appended (never replaced) by the auth layer so feature betas set by pydantic-ai survive.
+ANTHROPIC_BETA = "oauth-2025-04-20"
+USER_AGENT = "claude-cli/2.1.263 (external, cli)"
+X_APP = "cli"

pydantic_claude_code-0.1.0/src/pydantic_ai_claude_code/credentials.py

@@ -0,0 +1,72 @@
+"""Credentials for Claude Code subscription authentication."""
+
+from __future__ import annotations
+
+import time
+from datetime import UTC, datetime
+
+from pydantic import BaseModel, SecretStr
+
+from pydantic_ai.exceptions import UserError
+
+
+class ClaudeCodeCredentials(BaseModel):
+    """Credentials minted by the Claude Code OAuth flow.
+
+    `access_token` is the bearer token sent to the Messages API. `refresh_token`
+    is used by the auth layer to mint a new pair before expiry.
+    """
+
+    access_token: SecretStr
+    refresh_token: SecretStr
+    expires_at: datetime | None = None
+
+    @property
+    def token(self) -> str:
+        """The plaintext access token."""
+        return self.access_token.get_secret_value()
+
+    def to_wire_dict(self) -> dict[str, object]:
+        """A JSON-serializable, plain-string form of the credentials for storage.
+
+        Pydantic 2.13 masks `SecretStr` in some serialization modes, so the stored
+        form is spelled out here instead of trusting `model_dump`.
+        """
+        return {
+            "access_token": self.token,
+            "refresh_token": self.refresh_token.get_secret_value(),
+            "expires_at": self.expires_at.isoformat() if self.expires_at is not None else None,
+        }
+
+    @classmethod
+    def from_token_response(cls, data: object, previous: ClaudeCodeCredentials | None = None) -> ClaudeCodeCredentials:
+        """Build credentials from a token-endpoint response.
+
+        Args:
+            data: The parsed JSON body of a token response.
+            previous: Prior credentials whose refresh token is reused when the
+                issuer omits a new one, as Anthropic's refresh responses do.
+        """
+        root = data if isinstance(data, dict) else None
+        access_token = root.get("access_token") if root is not None else None
+        refresh_token = root.get("refresh_token") if root is not None else None
+        if not isinstance(access_token, str):
+            raise UserError("Claude Code token response did not contain a string `access_token`.")
+        if not isinstance(refresh_token, str):
+            if previous is None:
+                raise UserError("Claude Code token response did not contain a string `refresh_token`.")
+            refresh_token = previous.refresh_token.get_secret_value()
+        expires_at = None
+        if expires_in := root.get("expires_in"):
+            if isinstance(expires_in, (int, float)) and not isinstance(expires_in, bool):
+                expires_at = datetime.fromtimestamp(time.time() + float(expires_in), tz=UTC)
+        return cls(
+            access_token=SecretStr(access_token),
+            refresh_token=SecretStr(refresh_token),
+            expires_at=expires_at,
+        )
+
+    @classmethod
+    def from_token_file(cls, data: object) -> ClaudeCodeCredentials:
+        """Parse a stored token file (the saved output of a previous exchange)."""
+        return cls.model_validate(data)