CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

A local Anthropic-compatible API proxy that lets Claude Code talk to AI Nexus Claude models. It receives Anthropic Messages API requests and translates them to AWS Bedrock Converse API calls targeting the corporate Nexus endpoint.

Commands

# Install dependencies
uv sync --extra dev

# Start the proxy (prints Claude Code env helper)
uv run nexus-claude-api start --port 4141 --claude-code

# Start in dev mode (local config/logs instead of ~/.config)
uv run nexus-claude-api start --dev --port 4141 --claude-code

# Validate config without starting
uv run nexus-claude-api start --dry-run

# Run all tests
uv run pytest

# Run a single test file or focused test
uv run pytest tests/test_cli.py
uv run pytest tests/test_routes.py -k messages_stream

There is no lint, typecheck, or build command configured. Do not invent those steps.

Architecture

Claude Code  →  FastAPI (routes/)  →  NexusClient (boto3)  →  AI Nexus Bedrock

cli.py — CLI entrypoint (argparse). __main__.py just forwards to it.
server.py — App factory (create_app), stores settings and nexus_client on app.state.
config.py — Settings frozen dataclass, credential resolution, model ID mapping, defaults.
nexus_client.py — Wraps boto3 Bedrock converse / converse_stream.
routes/messages.py — POST /v1/messages and /v1/messages/count_tokens. Owns request validation, translation dispatch, SSE streaming, and error shaping.
translators/ — anthropic_to_bedrock.py, bedrock_to_anthropic.py, stream.py. Pure conversion logic.
errors.py — NexusClaudeError exception mapped to Anthropic-shaped JSON errors with correlation IDs.
diagnostics.py — Request summarization for logs; deliberately omits secrets, prompt text, base64.
shell.py — Generates PowerShell env vars for Claude Code (sets ANTHROPIC_AUTH_TOKEN='dummy' as a placeholder).

Key Design Decisions

Credential priority: --api-key → nexus-claude-api.local.json → NEXUS_API_KEY env → AWS_BEARER_TOKEN_BEDROCK env (fixed in Settings.from_values()).
Model aliasing: Sonnet/Haiku aliases resolve to Opus because users only have Opus access.
Localhost only: Server binds to 127.0.0.1.
No console logging: App logs go to files only (~/.config/nexus-claude-api/logs/ or ./logs/ in dev mode).
NexusClient side effect: Writes settings.api_key into AWS_BEARER_TOKEN_BEDROCK env var before building the boto3 client.

Testing Notes

Tests use stub clients (FakeNexusClient, AccessDeniedNexusClient) — no network calls.
pythonpath = ["src"] in pyproject.toml enables src-layout imports; keep this intact.
tests/test_cli.py uses per-test temp workspaces under .test-tmp/.
nexus-claude-api.local.json is gitignored and may exist locally; never overwrite it while testing.
After changing request/error/logging behavior, run uv run pytest tests/test_routes.py — it covers SSE responses, correlation IDs, and verifies logs don't leak secrets.

3.1 KiB Raw Blame History