nexus-claude-api/docs/PRD.md

nexus-claude-api PRD

Product Overview

nexus-claude-api is a local Python API proxy that lets Claude Code use company-approved Claude models through AI Nexus.

AI Nexus currently documents that the Anthropic Messages API is temporarily unsupported and recommends AWS Bedrock Converse API as the workaround. Claude Code expects an Anthropic-compatible Messages API. This project bridges that gap locally.

Reference: AI_NEXUS_CLAUDE.md

Users

Target users are internal developers who:

• Have an AI Nexus API key.
• Want to use Claude Code with company-approved Claude models.
• Work primarily in local development environments.
• Need Claude Code workflows such as code editing, tool use, and streaming responses.

Goals

• Provide a local Anthropic-compatible API for Claude Code.
• Start locally with a command similar to copilot-api.
• Convert Anthropic Messages requests to AI Nexus Bedrock Converse requests.
• Convert Nexus responses back to Anthropic Messages responses.
• Support text, streaming, tools, tool results, and image inputs.
• Provide model discovery and token-count compatibility endpoints.
• Keep credentials local and avoid logging secrets.

Non-goals

The first version will not include:

• OpenAI-compatible /v1/chat/completions.
• A dashboard.
• Nexus API key provisioning.
• Multi-user hosted gateway deployment.
• Database persistence.
• Direct Anthropic public API forwarding.

Supported Models

The local API exposes:

• claude-opus-4.6

Defaults:

• Main model: claude-opus-4.6
• Small model: claude-opus-4.6

The proxy defaults to Opus because this deployment is intended for users whose Nexus access is limited to claude-opus-4.6. Sonnet and Haiku aliases are accepted for compatibility and resolved to Opus before calling Nexus.

User Stories

• As a developer, I can store my Nexus key in user config with nexus-claude-api config set --api-key <key> or set NEXUS_API_KEY, then run nexus-claude-api start --claude-code to get a Claude Code launch command.
• As a contributor working from the repository, I can pass --dev to use current-directory development config and logs.
• As a Claude Code user, I can run coding workflows through local http://127.0.0.1:4141.
• As a Claude Code user, I can receive streaming model output.
• As a Claude Code user, I can use tool calls and tool results.
• As a multimodal user, I can send images through Claude-compatible image content blocks.
• As a developer debugging setup, I can enable verbose logs without exposing tokens.

Acceptance Criteria

• uv run nexus-claude-api start --port 4141 --claude-code starts a local server.
• nexus-claude-api config set --api-key <key> writes user config to ~/.config/nexus-claude-api/config.json.
• The server binds to 127.0.0.1 by default.
• Default startup reads credentials from user config before environment variables.
• --dev startup reads current-directory nexus-claude-api.local.json instead of user config.
• Default logs are written to ~/.config/nexus-claude-api/logs/nexus-claude-api.log.
• --dev logs are written to current-directory logs/nexus-claude-api.log.
• Missing Nexus credentials fail fast with a clear error.
• GET /health returns healthy status.
• GET /v1/models returns the supported Claude models.
• POST /v1/messages works for non-streaming text generation.
• POST /v1/messages works for streaming text generation.
• Tool use and tool result conversion are covered by tests.
• Image block conversion is covered by tests.
• POST /v1/messages/count_tokens returns an Anthropic-compatible token count response.
• Claude Code can be launched with the printed environment command.

Security Requirements

• Do not persist API keys automatically during startup.
• Persist API keys only when the user explicitly runs nexus-claude-api config set --api-key <key> or manually writes a config file.
• Store normal user configuration in ~/.config/nexus-claude-api/config.json.
• Use ignored current-directory nexus-claude-api.local.json only for explicit --dev repository-local development mode.
• Do not print or log API keys.
• Redact authorization headers in debug logs.
• Bind locally by default.
• Allow 0.0.0.0 only when explicitly requested.