# AGENTS.md

## Repo shape
- Single Python package repo. Runtime code lives in `src/nexus_claude_api/`, tests in `tests/`, design/product docs in `docs/`.
- There is no monorepo/workspace layer, no task runner, and no repo-configured lint/typecheck/build command. Do not invent those steps in plans or completion reports.

## Commands that are actually supported
- Install dev dependencies: `uv sync --extra dev`
- Start the local proxy and print the Claude Code helper: `uv run nexus-claude-api start --port 4141 --claude-code`
- Fast config check without starting the server: `uv run nexus-claude-api start --dry-run`
- Run all tests: `uv run pytest`
- Run focused tests: `uv run pytest tests/test_cli.py` or `uv run pytest tests/test_routes.py -k messages_stream`

## Real entrypoints and change boundaries
- CLI entrypoint is `src/nexus_claude_api/cli.py`; `src/nexus_claude_api/__main__.py` just forwards to it.
- FastAPI app wiring is in `src/nexus_claude_api/server.py`; it stores `settings` and `nexus_client` on `app.state`.
- The main HTTP behavior is in `src/nexus_claude_api/routes/messages.py`. That file owns request validation, Anthropic→Bedrock translation, SSE streaming, and Anthropic-shaped error responses.
- Translation boundaries live under `src/nexus_claude_api/translators/`. Upstream Nexus/Bedrock transport lives in `src/nexus_claude_api/nexus_client.py`.

## Runtime/config facts worth preserving
- Credential lookup order is fixed in `Settings.from_values()`: `--api-key` -> `nexus-claude-api.local.json` -> `NEXUS_API_KEY` -> `AWS_BEARER_TOKEN_BEDROCK`.
- `nexus-claude-api.local.json` is gitignored and may exist locally; never commit it or overwrite it casually while testing.
- `NexusClient` writes `settings.api_key` back into `AWS_BEARER_TOKEN_BEDROCK` before building the boto3 Bedrock client. Keep that side effect in mind for tests and env-sensitive refactors.
- Defaults from `src/nexus_claude_api/config.py`: host `127.0.0.1`, port `4141`, endpoint `https://genai-nexus.api.corpinter.net`, main model `claude-opus-4.6`, small model `claude-opus-4.6`. Sonnet and Haiku aliases intentionally resolve to Opus for users who only have Opus access.
- The Claude Code helper from `src/nexus_claude_api/shell.py` intentionally sets `ANTHROPIC_AUTH_TOKEN='dummy'`. That placeholder is only for Claude Code compatibility; it is not the Nexus key.

## Repo-specific verification gotchas
- Tests rely on pytest `pythonpath = ["src"]` from `pyproject.toml`; keep the src-layout imports intact.
- `tests/test_cli.py` uses per-test temp workspaces under `.test-tmp/`. Logging writes to `logs/nexus-claude-api.log`. Both paths are gitignored.
- If you change request/error/logging behavior, re-run `uv run pytest tests/test_routes.py`. It covers SSE responses, correlation IDs, and the requirement that logs do not leak API keys, `Authorization`, or raw payload blobs.