| Name | ccproxy-api JSON |
| Version |
0.1.6
JSON |
| download |
| home_page | None |
| Summary | API server that provides an Anthropic and OpenAI compatible interface over Claude Code, allowing to use your Claude OAuth account or over the API. |
| upload_time | 2025-08-13 14:50:18 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.11 |
| license | None |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# CCProxy API Server
`ccproxy` is a local reverse proxy server that provides unified access to multiple AI providers through a single interface. It supports both Anthropic Claude and OpenAI Codex backends, allowing you to use your existing subscriptions without separate API key billing.
## Supported Providers
### Anthropic Claude
Access Claude via your Claude Max subscription at `api.anthropic.com/v1/messages`.
The server provides two primary modes of operation:
- **SDK Mode (`/sdk`):** Routes requests through the local `claude-code-sdk`. This enables access to tools configured in your Claude environment and includes an integrated MCP (Model Context Protocol) server for permission management.
- **API Mode (`/api`):** Acts as a direct reverse proxy, injecting the necessary authentication headers. This provides full access to the underlying API features and model settings.
### OpenAI Codex Response API (Experimental)
Access OpenAI's [Response API](https://platform.openai.com/docs/api-reference/responses) via your ChatGPT Plus subscription. This provides programmatic access to ChatGPT models through the `chatgpt.com/backend-api/codex` endpoint.
- **Response API (`/codex/responses`):** Direct reverse proxy to ChatGPT backend for conversation responses
- **Session Management:** Supports both auto-generated and persistent session IDs for conversation continuity
- **OpenAI OAuth:** Uses the same OAuth2 PKCE authentication flow as the official Codex CLI
- **ChatGPT Plus Required:** Requires an active ChatGPT Plus subscription for API access
- **Instruction Prompt:** Automatically injects the Codex instruction prompt into conversations
The server includes a translation layer to support both Anthropic and OpenAI-compatible API formats for requests and responses, including streaming.
## Installation
```bash
# The official claude-code CLI is required for SDK mode
npm install -g @anthropic-ai/claude-code
# run it with uv
uvx ccproxy-api
# run it with pipx
pipx run ccproxy-api
# install with uv
uv tool install ccproxy-api
# Install ccproxy with pip
pipx install ccproxy-api
# Optional: Enable shell completion
eval "$(ccproxy --show-completion zsh)" # For zsh
eval "$(ccproxy --show-completion bash)" # For bash
```
For dev version replace `ccproxy-api` with `git+https://github.com/caddyglow/ccproxy-api.git@dev`
## Authentication
The proxy uses different authentication mechanisms depending on the provider and mode.
### Claude Authentication
1. **Claude CLI (`sdk` mode):**
This mode relies on the authentication handled by the `claude-code-sdk`.
```bash
claude /login
```
It's also possible now to get a long live token to avoid renewing issues
using
```bash
claude setup-token
```
2. **ccproxy (`api` mode):**
This mode uses its own OAuth2 flow to obtain credentials for direct API access.
```bash
ccproxy auth login
```
If you are already connected with Claude CLI the credentials should be found automatically
### OpenAI Codex Authentication (Experimental)
The Codex Response API requires ChatGPT Plus subscription and OAuth2 authentication:
```bash
# Enable Codex provider
ccproxy config codex --enable
# Authentication options:
# Option 1: Use existing Codex CLI credentials (if available)
# CCProxy will automatically detect and use valid credentials from:
# - $HOME/.codex/auth.json (Codex CLI credentials)
# - Automatically renews tokens if expired but refresh token is valid
# Option 2: Login via CCProxy CLI (opens browser)
ccproxy auth login-openai
# Option 3: Use the official Codex CLI
codex auth login
# Check authentication status for all providers
ccproxy auth status
```
**Important Notes:**
- Credentials are stored in `$HOME/.codex/auth.json`
- CCProxy reuses existing Codex CLI credentials when available
- If credentials are expired, CCProxy attempts automatic renewal
- Without valid credentials, users must authenticate using either CCProxy or Codex CLI
### Authentication Status
You can check the status of all credentials with:
```bash
ccproxy auth status # All providers
ccproxy auth validate # Claude only
ccproxy auth info # Claude only
```
Warning is shown on startup if no credentials are setup.
## Usage
### Running the Server
```bash
# Start the proxy server
ccproxy
```
The server will start on `http://127.0.0.1:8000` by default.
### Client Configuration
Point your existing tools and applications to the local proxy instance by setting the appropriate environment variables. A dummy API key is required by most client libraries but is not used by the proxy itself.
**For Claude (OpenAI-compatible clients):**
```bash
# For SDK mode
export OPENAI_BASE_URL="http://localhost:8000/sdk/v1"
# For API mode
export OPENAI_BASE_URL="http://localhost:8000/api/v1"
export OPENAI_API_KEY="dummy-key"
```
**For Claude (Anthropic-compatible clients):**
```bash
# For SDK mode
export ANTHROPIC_BASE_URL="http://localhost:8000/sdk"
# For API mode
export ANTHROPIC_BASE_URL="http://localhost:8000/api"
export ANTHROPIC_API_KEY="dummy-key"
```
**For OpenAI Codex Response API:**
```bash
# Create a new conversation response (auto-generated session)
curl -X POST http://localhost:8000/codex/responses \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5",
"messages": [
{"role": "user", "content": "Hello, can you help me with Python?"}
]
}'
# Continue conversation with persistent session ID
curl -X POST http://localhost:8000/codex/my_session_123/responses \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5",
"messages": [
{"role": "user", "content": "Show me an example of async/await"}
]
}'
# Stream responses (SSE format)
curl -X POST http://localhost:8000/codex/responses \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5",
"messages": [{"role": "user", "content": "Explain quantum computing"}],
"stream": true
}'
```
**For OpenAI-compatible clients using Codex:**
```yaml
# Example aichat configuration (~/.config/aichat/config.yaml)
clients:
- type: claude
api_base: http://127.0.0.1:8000/codex
# Usage
aichat --model openai:gpt-5 "hello"
```
**Important Codex Limitations:**
- Limited model support (e.g., `gpt-5` works, others may not)
- Many OpenAI parameters not supported (temperature, top_p, etc.)
- Reasoning content appears in XML tags for capable models
**Note:** The Codex instruction prompt is automatically injected into all conversations to maintain compatibility with the ChatGPT backend.
### Codex Response API Details
#### Session Management
The Codex Response API supports flexible session management for conversation continuity:
- **Auto-generated sessions**: `POST /codex/responses` - Creates a new session ID for each request
- **Persistent sessions**: `POST /codex/{session_id}/responses` - Maintains conversation context across requests
- **Header forwarding**: Optional `session_id` header for custom session tracking
#### Instruction Prompt Injection
**Important:** CCProxy automatically injects the Codex instruction prompt into every conversation. This is required for proper interaction with the ChatGPT backend but affects your token usage:
- The instruction prompt is prepended to your messages
- This consumes additional tokens in each request
- The prompt ensures compatibility with ChatGPT's response generation
- You cannot disable this injection as it's required by the backend
#### Model Differences
The Response API models differ from standard OpenAI API models:
- Uses ChatGPT Plus models (e.g., `gpt-4`, `gpt-4-turbo`)
- Model behavior matches ChatGPT web interface
- Token limits and pricing follow ChatGPT Plus subscription terms
- See [OpenAI Response API Documentation](https://platform.openai.com/docs/api-reference/responses) for details
## MCP Server Integration & Permission System
In SDK mode, CCProxy automatically configures an MCP (Model Context Protocol) server that provides permission checking tools for Claude Code. This enables interactive permission management for tool execution.
### Permission Management
**Starting the Permission Handler:**
```bash
# In a separate terminal, start the permission handler
ccproxy permission-handler
# Or with custom settings
ccproxy permission-handler --host 127.0.0.1 --port 8000
```
The permission handler provides:
- **Real-time Permission Requests**: Streams permission requests via Server-Sent Events (SSE)
- **Interactive Approval/Denial**: Command-line interface for managing tool permissions
- **Automatic MCP Integration**: Works seamlessly with Claude Code SDK tools
**Working Directory Control:**
Control which project the Claude SDK API can access using the `--cwd` flag:
```bash
# Set working directory for Claude SDK
ccproxy --claude-code-options-cwd /path/to/your/project
# Example with permission bypass and formatted output
ccproxy --claude-code-options-cwd /tmp/tmp.AZyCo5a42N \
--claude-code-options-permission-mode bypassPermissions \
--claude-sdk-message-mode formatted
# Alternative: Change to project directory and start ccproxy
cd /path/to/your/project
ccproxy
```
### Claude SDK Message Formatting
CCProxy supports flexible message formatting through the `sdk_message_mode` configuration:
- **`forward`** (default): Preserves original Claude SDK content blocks with full metadata
- **`formatted`**: Converts content to XML tags with pretty-printed JSON data
- **`ignore`**: Filters out Claude SDK-specific content entirely
Configure via environment variables:
```bash
# Use formatted XML output
CLAUDE__SDK_MESSAGE_MODE=formatted ccproxy
# Use compact formatting without pretty-printing
CLAUDE__PRETTY_FORMAT=false ccproxy
```
## Claude SDK Pool Mode
CCProxy supports connection pooling for Claude Code SDK clients to improve request performance by maintaining a pool of pre-initialized Claude instances.
### Benefits
- **Reduced Latency**: Eliminates Claude Code startup overhead on each request
- **Improved Performance**: Reuses established connections for faster response times
- **Resource Efficiency**: Maintains a configurable pool size to balance performance and resource usage
### Usage
Pool mode is disabled by default and can be enabled using the CLI flag:
```bash
# Enable pool mode with default settings
ccproxy --sdk-enable-pool
# Configure pool size (default: 3)
ccproxy --sdk-enable-pool --sdk-pool-size 5
```
### Limitations
- **No Dynamic Options**: Pool instances cannot change Claude options (max_tokens, model, etc.) after initialization
- **Shared Configuration**: All requests using the pool must use identical Claude configuration
- **Memory Usage**: Each pool instance consumes additional memory
Pool mode is most effective for high-frequency requests with consistent configuration requirements.
## Using with Aider
CCProxy works seamlessly with Aider and other AI coding assistants:
### Anthropic Mode
```bash
export ANTHROPIC_API_KEY=dummy
export ANTHROPIC_BASE_URL=http://127.0.0.1:8000/api
aider --model claude-sonnet-4-20250514
```
### OpenAI Mode with Model Mapping
If your tool only supports OpenAI settings, ccproxy automatically maps OpenAI models to Claude:
```bash
export OPENAI_API_KEY=dummy
export OPENAI_BASE_URL=http://127.0.0.1:8000/api/v1
aider --model o3-mini
```
### API Mode (Direct Proxy)
For minimal interference and direct API access:
```bash
export OPENAI_API_KEY=dummy
export OPENAI_BASE_URL=http://127.0.0.1:8000/api/v1
aider --model o3-mini
```
### Using with OpenAI Codex
For tools that support custom API bases, you can use the Codex provider. Note that this has significant limitations compared to Claude providers.
**Example with aichat:**
```yaml
# ~/.config/aichat/config.yaml
clients:
- type: claude
api_base: http://127.0.0.1:8000/codex
```
```bash
# Usage with confirmed working model
aichat --model openai:gpt-5 "hello"
```
**Codex Limitations:**
- Only select models work (gpt-5 confirmed, others may fail)
- No support for temperature, top_p, or most OpenAI parameters
- When using reasoning models, reasoning appears as XML tags in output
### `curl` Example
```bash
# SDK mode
curl -X POST http://localhost:8000/sdk/v1/messages \
-H "Content-Type: application/json" \
-d '{
"model": "claude-3-5-sonnet-20241022",
"messages": [{"role": "user", "content": "Hello!"}],
"max_tokens": 100
}'
# API mode
curl -X POST http://localhost:8000/api/v1/messages \
-H "Content-Type: application/json" \
-d '{
"model": "claude-3-5-sonnet-20241022",
"messages": [{"role": "user", "content": "Hello!"}],
"max_tokens": 100
}'
```
More examples are available in the `examples/` directory.
## Endpoints
The proxy exposes endpoints under multiple prefixes for different providers and modes.
### Claude Endpoints
| Mode | URL Prefix | Description | Use Case |
| ------- | ---------- | ------------------------------------------------- | ---------------------------------- |
| **SDK** | `/sdk/` | Uses `claude-code-sdk` with its configured tools. | Accessing Claude with local tools. |
| **API** | `/api/` | Direct proxy with header injection. | Full API control, direct access. |
- **Anthropic Format:**
- `POST /sdk/v1/messages`
- `POST /api/v1/messages`
- **OpenAI-Compatible Format:**
- `POST /sdk/v1/chat/completions`
- `POST /api/v1/chat/completions`
### OpenAI Codex Endpoints
- **Response API:**
- `POST /codex/responses` - Create response with auto-generated session
- `POST /codex/{session_id}/responses` - Create response with persistent session
- `POST /codex/chat/completions` - OpenAI-compatible chat completions endpoint
- `POST /codex/v1/chat/completions` - Alternative OpenAI-compatible endpoint
- Supports streaming via SSE when `stream: true` is set
- See [Response API docs](https://platform.openai.com/docs/api-reference/responses)
**Codex Chat Completions Limitations:**
- **No Tool/Function Calling Support**: Tool use and function calling are not supported (use `/codex/responses` for tool calls)
- **Limited Parameter Support**: Many OpenAI parameters (temperature, top_p, frequency_penalty, etc.) are not supported
- **Restricted Model Support**: Only certain models work (e.g., `gpt-5` confirmed working, others may fail)
- **No Custom System Prompts**: System messages and instructions are overridden by the required Codex instruction prompt
- **Reasoning Mode**: GPT models with reasoning capabilities pass reasoning content between XML tags (`<reasoning>...</reasoning>`)
- **Session Management**: Uses auto-generated sessions; persistent sessions require the `/codex/{session_id}/responses` endpoint
- **ChatGPT Plus Required**: Requires active ChatGPT Plus subscription for access
**Note**: The `/codex/responses` endpoint supports tool calling and more parameters, but specific feature availability depends on ChatGPT's backend - users should test individual capabilities.
### Utility Endpoints
- **Health & Status:**
- `GET /health`
- `GET /sdk/models`, `GET /api/models`
- `GET /sdk/status`, `GET /api/status`
- **Authentication:**
- `GET /oauth/callback` - OAuth callback for both Claude and OpenAI
- **MCP & Permissions:**
- `POST /mcp/permission/check` - MCP permission checking endpoint
- `GET /permissions/stream` - SSE stream for permission requests
- `GET /permissions/{id}` - Get permission request details
- `POST /permissions/{id}/respond` - Respond to permission request
- **Observability (Optional):**
- `GET /metrics`
- `GET /logs/status`, `GET /logs/query`
- `GET /dashboard`
## Supported Models
CCProxy supports recent Claude models including Opus, Sonnet, and Haiku variants. The specific models available to you will depend on your Claude account and the features enabled for your subscription.
- `claude-opus-4-20250514`
- `claude-sonnet-4-20250514`
- `claude-3-7-sonnet-20250219`
- `claude-3-5-sonnet-20241022`
- `claude-3-5-sonnet-20240620`
## Configuration
Settings can be configured through (in order of precedence):
1. Command-line arguments
2. Environment variables
3. `.env` file
4. TOML configuration files (`.ccproxy.toml`, `ccproxy.toml`, or `~/.config/ccproxy/config.toml`)
5. Default values
For complex configurations, you can use a nested syntax for environment variables with `__` as a delimiter:
```bash
# Server settings
SERVER__HOST=0.0.0.0
SERVER__PORT=8080
# etc.
```
## Securing the Proxy (Optional)
You can enable token authentication for the proxy. This supports multiple header formats (`x-api-key` for Anthropic, `Authorization: Bearer` for OpenAI) for compatibility with standard client libraries.
**1. Generate a Token:**
```bash
ccproxy generate-token
# Output: SECURITY__AUTH_TOKEN=abc123xyz789...
```
**2. Configure the Token:**
```bash
# Set environment variable
export SECURITY__AUTH_TOKEN=abc123xyz789...
# Or add to .env file
echo "SECURITY__AUTH_TOKEN=abc123xyz789..." >> .env
```
**3. Use in Requests:**
When authentication is enabled, include the token in your API requests.
```bash
# Anthropic Format (x-api-key)
curl -H "x-api-key: your-token" ...
# OpenAI/Bearer Format
curl -H "Authorization: Bearer your-token" ...
```
## Observability
`ccproxy` includes an optional but powerful observability suite for monitoring and analytics. When enabled, it provides:
- **Prometheus Metrics:** A `/metrics` endpoint for real-time operational monitoring.
- **Access Log Storage:** Detailed request logs, including token usage and costs, are stored in a local DuckDB database.
- **Analytics API:** Endpoints to query and analyze historical usage data.
- **Real-time Dashboard:** A live web interface at `/dashboard` to visualize metrics and request streams.
These features are disabled by default and can be enabled via configuration. For a complete guide on setting up and using these features, see the [Observability Documentation](docs/observability.md).
## Troubleshooting
### Common Issues
1. **Authentication Error:** Ensure you're using the correct mode (`/sdk` or `/api`) for your authentication method.
2. **Claude Credentials Expired:** Run `ccproxy auth login` to refresh credentials for API mode. Run `claude /login` for SDK mode.
3. **OpenAI/Codex Authentication Failed:**
- Check if valid credentials exist: `ccproxy auth status`
- Ensure you have an active ChatGPT Plus subscription
- Try re-authenticating: `ccproxy auth login-openai` or `codex auth login`
- Verify credentials in `$HOME/.codex/auth.json`
4. **Codex Response API Errors:**
- "Instruction prompt injection failed": The backend requires the Codex prompt; this is automatic
- "Session not found": Use persistent session IDs for conversation continuity
- "Model not available": Ensure you're using ChatGPT Plus compatible models
5. **Missing API Auth Token:** If you've enabled security, include the token in your request headers.
6. **Port Already in Use:** Start the server on a different port: `ccproxy --port 8001`.
7. **Model Not Available:** Check that your subscription includes the requested model.
## Contributing
Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Documentation
- **[Online Documentation](https://caddyglow.github.io/ccproxy-api)**
- **[API Reference](https://caddyglow.github.io/ccproxy-api/api-reference/overview/)**
- **[Developer Guide](https://caddyglow.github.io/ccproxy-api/developer-guide/architecture/)**
## Support
- Issues: [GitHub Issues](https://github.com/CaddyGlow/ccproxy-api/issues)
- Documentation: [Project Documentation](https://caddyglow.github.io/ccproxy-api)
## Acknowledgments
- [Anthropic](https://anthropic.com) for Claude and the Claude Code SDK
- The open-source community
Raw data
{
"_id": null,
"home_page": null,
"name": "ccproxy-api",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/15/12/8e087406ec5f6b8a0626dcddd71668c5d6e48f38cd04d219fde3e7988c3c/ccproxy_api-0.1.6.tar.gz",
"platform": null,
"description": "# CCProxy API Server\n\n`ccproxy` is a local reverse proxy server that provides unified access to multiple AI providers through a single interface. It supports both Anthropic Claude and OpenAI Codex backends, allowing you to use your existing subscriptions without separate API key billing.\n\n## Supported Providers\n\n### Anthropic Claude\n\nAccess Claude via your Claude Max subscription at `api.anthropic.com/v1/messages`.\n\nThe server provides two primary modes of operation:\n\n- **SDK Mode (`/sdk`):** Routes requests through the local `claude-code-sdk`. This enables access to tools configured in your Claude environment and includes an integrated MCP (Model Context Protocol) server for permission management.\n- **API Mode (`/api`):** Acts as a direct reverse proxy, injecting the necessary authentication headers. This provides full access to the underlying API features and model settings.\n\n### OpenAI Codex Response API (Experimental)\n\nAccess OpenAI's [Response API](https://platform.openai.com/docs/api-reference/responses) via your ChatGPT Plus subscription. This provides programmatic access to ChatGPT models through the `chatgpt.com/backend-api/codex` endpoint.\n\n- **Response API (`/codex/responses`):** Direct reverse proxy to ChatGPT backend for conversation responses\n- **Session Management:** Supports both auto-generated and persistent session IDs for conversation continuity\n- **OpenAI OAuth:** Uses the same OAuth2 PKCE authentication flow as the official Codex CLI\n- **ChatGPT Plus Required:** Requires an active ChatGPT Plus subscription for API access\n- **Instruction Prompt:** Automatically injects the Codex instruction prompt into conversations\n\nThe server includes a translation layer to support both Anthropic and OpenAI-compatible API formats for requests and responses, including streaming.\n\n## Installation\n\n```bash\n# The official claude-code CLI is required for SDK mode\nnpm install -g @anthropic-ai/claude-code\n\n# run it with uv\nuvx ccproxy-api\n\n# run it with pipx\npipx run ccproxy-api\n\n# install with uv\nuv tool install ccproxy-api\n\n# Install ccproxy with pip\npipx install ccproxy-api\n\n# Optional: Enable shell completion\neval \"$(ccproxy --show-completion zsh)\" # For zsh\neval \"$(ccproxy --show-completion bash)\" # For bash\n```\n\nFor dev version replace `ccproxy-api` with `git+https://github.com/caddyglow/ccproxy-api.git@dev`\n\n## Authentication\n\nThe proxy uses different authentication mechanisms depending on the provider and mode.\n\n### Claude Authentication\n\n1. **Claude CLI (`sdk` mode):**\n This mode relies on the authentication handled by the `claude-code-sdk`.\n\n ```bash\n claude /login\n ```\n\n It's also possible now to get a long live token to avoid renewing issues\n using\n\n ```bash\n claude setup-token\n ```\n\n2. **ccproxy (`api` mode):**\n This mode uses its own OAuth2 flow to obtain credentials for direct API access.\n\n ```bash\n ccproxy auth login\n ```\n\n If you are already connected with Claude CLI the credentials should be found automatically\n\n### OpenAI Codex Authentication (Experimental)\n\nThe Codex Response API requires ChatGPT Plus subscription and OAuth2 authentication:\n\n```bash\n# Enable Codex provider\nccproxy config codex --enable\n\n# Authentication options:\n\n# Option 1: Use existing Codex CLI credentials (if available)\n# CCProxy will automatically detect and use valid credentials from:\n# - $HOME/.codex/auth.json (Codex CLI credentials)\n# - Automatically renews tokens if expired but refresh token is valid\n\n# Option 2: Login via CCProxy CLI (opens browser)\nccproxy auth login-openai\n\n# Option 3: Use the official Codex CLI\ncodex auth login\n\n# Check authentication status for all providers\nccproxy auth status\n```\n\n**Important Notes:**\n\n- Credentials are stored in `$HOME/.codex/auth.json`\n- CCProxy reuses existing Codex CLI credentials when available\n- If credentials are expired, CCProxy attempts automatic renewal\n- Without valid credentials, users must authenticate using either CCProxy or Codex CLI\n\n### Authentication Status\n\nYou can check the status of all credentials with:\n\n```bash\nccproxy auth status # All providers\nccproxy auth validate # Claude only\nccproxy auth info # Claude only\n```\n\nWarning is shown on startup if no credentials are setup.\n\n## Usage\n\n### Running the Server\n\n```bash\n# Start the proxy server\nccproxy\n```\n\nThe server will start on `http://127.0.0.1:8000` by default.\n\n### Client Configuration\n\nPoint your existing tools and applications to the local proxy instance by setting the appropriate environment variables. A dummy API key is required by most client libraries but is not used by the proxy itself.\n\n**For Claude (OpenAI-compatible clients):**\n\n```bash\n# For SDK mode\nexport OPENAI_BASE_URL=\"http://localhost:8000/sdk/v1\"\n# For API mode\nexport OPENAI_BASE_URL=\"http://localhost:8000/api/v1\"\n\nexport OPENAI_API_KEY=\"dummy-key\"\n```\n\n**For Claude (Anthropic-compatible clients):**\n\n```bash\n# For SDK mode\nexport ANTHROPIC_BASE_URL=\"http://localhost:8000/sdk\"\n# For API mode\nexport ANTHROPIC_BASE_URL=\"http://localhost:8000/api\"\n\nexport ANTHROPIC_API_KEY=\"dummy-key\"\n```\n\n**For OpenAI Codex Response API:**\n\n```bash\n# Create a new conversation response (auto-generated session)\ncurl -X POST http://localhost:8000/codex/responses \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"gpt-5\",\n \"messages\": [\n {\"role\": \"user\", \"content\": \"Hello, can you help me with Python?\"}\n ]\n }'\n\n# Continue conversation with persistent session ID\ncurl -X POST http://localhost:8000/codex/my_session_123/responses \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"gpt-5\",\n \"messages\": [\n {\"role\": \"user\", \"content\": \"Show me an example of async/await\"}\n ]\n }'\n\n# Stream responses (SSE format)\ncurl -X POST http://localhost:8000/codex/responses \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"gpt-5\",\n \"messages\": [{\"role\": \"user\", \"content\": \"Explain quantum computing\"}],\n \"stream\": true\n }'\n```\n\n**For OpenAI-compatible clients using Codex:**\n\n```yaml\n# Example aichat configuration (~/.config/aichat/config.yaml)\nclients:\n - type: claude\n api_base: http://127.0.0.1:8000/codex\n\n# Usage\naichat --model openai:gpt-5 \"hello\"\n```\n\n**Important Codex Limitations:**\n\n- Limited model support (e.g., `gpt-5` works, others may not)\n- Many OpenAI parameters not supported (temperature, top_p, etc.)\n- Reasoning content appears in XML tags for capable models\n\n**Note:** The Codex instruction prompt is automatically injected into all conversations to maintain compatibility with the ChatGPT backend.\n\n### Codex Response API Details\n\n#### Session Management\n\nThe Codex Response API supports flexible session management for conversation continuity:\n\n- **Auto-generated sessions**: `POST /codex/responses` - Creates a new session ID for each request\n- **Persistent sessions**: `POST /codex/{session_id}/responses` - Maintains conversation context across requests\n- **Header forwarding**: Optional `session_id` header for custom session tracking\n\n#### Instruction Prompt Injection\n\n**Important:** CCProxy automatically injects the Codex instruction prompt into every conversation. This is required for proper interaction with the ChatGPT backend but affects your token usage:\n\n- The instruction prompt is prepended to your messages\n- This consumes additional tokens in each request\n- The prompt ensures compatibility with ChatGPT's response generation\n- You cannot disable this injection as it's required by the backend\n\n#### Model Differences\n\nThe Response API models differ from standard OpenAI API models:\n\n- Uses ChatGPT Plus models (e.g., `gpt-4`, `gpt-4-turbo`)\n- Model behavior matches ChatGPT web interface\n- Token limits and pricing follow ChatGPT Plus subscription terms\n- See [OpenAI Response API Documentation](https://platform.openai.com/docs/api-reference/responses) for details\n\n## MCP Server Integration & Permission System\n\nIn SDK mode, CCProxy automatically configures an MCP (Model Context Protocol) server that provides permission checking tools for Claude Code. This enables interactive permission management for tool execution.\n\n### Permission Management\n\n**Starting the Permission Handler:**\n\n```bash\n# In a separate terminal, start the permission handler\nccproxy permission-handler\n\n# Or with custom settings\nccproxy permission-handler --host 127.0.0.1 --port 8000\n```\n\nThe permission handler provides:\n\n- **Real-time Permission Requests**: Streams permission requests via Server-Sent Events (SSE)\n- **Interactive Approval/Denial**: Command-line interface for managing tool permissions\n- **Automatic MCP Integration**: Works seamlessly with Claude Code SDK tools\n\n**Working Directory Control:**\nControl which project the Claude SDK API can access using the `--cwd` flag:\n\n```bash\n# Set working directory for Claude SDK\nccproxy --claude-code-options-cwd /path/to/your/project\n\n# Example with permission bypass and formatted output\nccproxy --claude-code-options-cwd /tmp/tmp.AZyCo5a42N \\\n --claude-code-options-permission-mode bypassPermissions \\\n --claude-sdk-message-mode formatted\n\n# Alternative: Change to project directory and start ccproxy\ncd /path/to/your/project\nccproxy\n```\n\n### Claude SDK Message Formatting\n\nCCProxy supports flexible message formatting through the `sdk_message_mode` configuration:\n\n- **`forward`** (default): Preserves original Claude SDK content blocks with full metadata\n- **`formatted`**: Converts content to XML tags with pretty-printed JSON data\n- **`ignore`**: Filters out Claude SDK-specific content entirely\n\nConfigure via environment variables:\n\n```bash\n# Use formatted XML output\nCLAUDE__SDK_MESSAGE_MODE=formatted ccproxy\n\n# Use compact formatting without pretty-printing\nCLAUDE__PRETTY_FORMAT=false ccproxy\n```\n\n## Claude SDK Pool Mode\n\nCCProxy supports connection pooling for Claude Code SDK clients to improve request performance by maintaining a pool of pre-initialized Claude instances.\n\n### Benefits\n\n- **Reduced Latency**: Eliminates Claude Code startup overhead on each request\n- **Improved Performance**: Reuses established connections for faster response times\n- **Resource Efficiency**: Maintains a configurable pool size to balance performance and resource usage\n\n### Usage\n\nPool mode is disabled by default and can be enabled using the CLI flag:\n\n```bash\n# Enable pool mode with default settings\nccproxy --sdk-enable-pool\n\n# Configure pool size (default: 3)\nccproxy --sdk-enable-pool --sdk-pool-size 5\n```\n\n### Limitations\n\n- **No Dynamic Options**: Pool instances cannot change Claude options (max_tokens, model, etc.) after initialization\n- **Shared Configuration**: All requests using the pool must use identical Claude configuration\n- **Memory Usage**: Each pool instance consumes additional memory\n\nPool mode is most effective for high-frequency requests with consistent configuration requirements.\n\n## Using with Aider\n\nCCProxy works seamlessly with Aider and other AI coding assistants:\n\n### Anthropic Mode\n\n```bash\nexport ANTHROPIC_API_KEY=dummy\nexport ANTHROPIC_BASE_URL=http://127.0.0.1:8000/api\naider --model claude-sonnet-4-20250514\n```\n\n### OpenAI Mode with Model Mapping\n\nIf your tool only supports OpenAI settings, ccproxy automatically maps OpenAI models to Claude:\n\n```bash\nexport OPENAI_API_KEY=dummy\nexport OPENAI_BASE_URL=http://127.0.0.1:8000/api/v1\naider --model o3-mini\n```\n\n### API Mode (Direct Proxy)\n\nFor minimal interference and direct API access:\n\n```bash\nexport OPENAI_API_KEY=dummy\nexport OPENAI_BASE_URL=http://127.0.0.1:8000/api/v1\naider --model o3-mini\n```\n\n### Using with OpenAI Codex\n\nFor tools that support custom API bases, you can use the Codex provider. Note that this has significant limitations compared to Claude providers.\n\n**Example with aichat:**\n\n```yaml\n# ~/.config/aichat/config.yaml\nclients:\n - type: claude\n api_base: http://127.0.0.1:8000/codex\n```\n\n```bash\n# Usage with confirmed working model\naichat --model openai:gpt-5 \"hello\"\n```\n\n**Codex Limitations:**\n\n- Only select models work (gpt-5 confirmed, others may fail)\n- No support for temperature, top_p, or most OpenAI parameters\n- When using reasoning models, reasoning appears as XML tags in output\n\n### `curl` Example\n\n```bash\n# SDK mode\ncurl -X POST http://localhost:8000/sdk/v1/messages \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"claude-3-5-sonnet-20241022\",\n \"messages\": [{\"role\": \"user\", \"content\": \"Hello!\"}],\n \"max_tokens\": 100\n }'\n\n# API mode\ncurl -X POST http://localhost:8000/api/v1/messages \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"claude-3-5-sonnet-20241022\",\n \"messages\": [{\"role\": \"user\", \"content\": \"Hello!\"}],\n \"max_tokens\": 100\n }'\n```\n\nMore examples are available in the `examples/` directory.\n\n## Endpoints\n\nThe proxy exposes endpoints under multiple prefixes for different providers and modes.\n\n### Claude Endpoints\n\n| Mode | URL Prefix | Description | Use Case |\n| ------- | ---------- | ------------------------------------------------- | ---------------------------------- |\n| **SDK** | `/sdk/` | Uses `claude-code-sdk` with its configured tools. | Accessing Claude with local tools. |\n| **API** | `/api/` | Direct proxy with header injection. | Full API control, direct access. |\n\n- **Anthropic Format:**\n - `POST /sdk/v1/messages`\n - `POST /api/v1/messages`\n- **OpenAI-Compatible Format:**\n - `POST /sdk/v1/chat/completions`\n - `POST /api/v1/chat/completions`\n\n### OpenAI Codex Endpoints\n\n- **Response API:**\n - `POST /codex/responses` - Create response with auto-generated session\n - `POST /codex/{session_id}/responses` - Create response with persistent session\n - `POST /codex/chat/completions` - OpenAI-compatible chat completions endpoint\n - `POST /codex/v1/chat/completions` - Alternative OpenAI-compatible endpoint\n - Supports streaming via SSE when `stream: true` is set\n - See [Response API docs](https://platform.openai.com/docs/api-reference/responses)\n\n**Codex Chat Completions Limitations:**\n\n- **No Tool/Function Calling Support**: Tool use and function calling are not supported (use `/codex/responses` for tool calls)\n- **Limited Parameter Support**: Many OpenAI parameters (temperature, top_p, frequency_penalty, etc.) are not supported\n- **Restricted Model Support**: Only certain models work (e.g., `gpt-5` confirmed working, others may fail)\n- **No Custom System Prompts**: System messages and instructions are overridden by the required Codex instruction prompt\n- **Reasoning Mode**: GPT models with reasoning capabilities pass reasoning content between XML tags (`<reasoning>...</reasoning>`)\n- **Session Management**: Uses auto-generated sessions; persistent sessions require the `/codex/{session_id}/responses` endpoint\n- **ChatGPT Plus Required**: Requires active ChatGPT Plus subscription for access\n\n**Note**: The `/codex/responses` endpoint supports tool calling and more parameters, but specific feature availability depends on ChatGPT's backend - users should test individual capabilities.\n\n### Utility Endpoints\n\n- **Health & Status:**\n - `GET /health`\n - `GET /sdk/models`, `GET /api/models`\n - `GET /sdk/status`, `GET /api/status`\n- **Authentication:**\n - `GET /oauth/callback` - OAuth callback for both Claude and OpenAI\n- **MCP & Permissions:**\n - `POST /mcp/permission/check` - MCP permission checking endpoint\n - `GET /permissions/stream` - SSE stream for permission requests\n - `GET /permissions/{id}` - Get permission request details\n - `POST /permissions/{id}/respond` - Respond to permission request\n- **Observability (Optional):**\n - `GET /metrics`\n - `GET /logs/status`, `GET /logs/query`\n - `GET /dashboard`\n\n## Supported Models\n\nCCProxy supports recent Claude models including Opus, Sonnet, and Haiku variants. The specific models available to you will depend on your Claude account and the features enabled for your subscription.\n\n- `claude-opus-4-20250514`\n- `claude-sonnet-4-20250514`\n- `claude-3-7-sonnet-20250219`\n- `claude-3-5-sonnet-20241022`\n- `claude-3-5-sonnet-20240620`\n\n## Configuration\n\nSettings can be configured through (in order of precedence):\n\n1. Command-line arguments\n2. Environment variables\n3. `.env` file\n4. TOML configuration files (`.ccproxy.toml`, `ccproxy.toml`, or `~/.config/ccproxy/config.toml`)\n5. Default values\n\nFor complex configurations, you can use a nested syntax for environment variables with `__` as a delimiter:\n\n```bash\n# Server settings\nSERVER__HOST=0.0.0.0\nSERVER__PORT=8080\n# etc.\n```\n\n## Securing the Proxy (Optional)\n\nYou can enable token authentication for the proxy. This supports multiple header formats (`x-api-key` for Anthropic, `Authorization: Bearer` for OpenAI) for compatibility with standard client libraries.\n\n**1. Generate a Token:**\n\n```bash\nccproxy generate-token\n# Output: SECURITY__AUTH_TOKEN=abc123xyz789...\n```\n\n**2. Configure the Token:**\n\n```bash\n# Set environment variable\nexport SECURITY__AUTH_TOKEN=abc123xyz789...\n\n# Or add to .env file\necho \"SECURITY__AUTH_TOKEN=abc123xyz789...\" >> .env\n```\n\n**3. Use in Requests:**\nWhen authentication is enabled, include the token in your API requests.\n\n```bash\n# Anthropic Format (x-api-key)\ncurl -H \"x-api-key: your-token\" ...\n\n# OpenAI/Bearer Format\ncurl -H \"Authorization: Bearer your-token\" ...\n```\n\n## Observability\n\n`ccproxy` includes an optional but powerful observability suite for monitoring and analytics. When enabled, it provides:\n\n- **Prometheus Metrics:** A `/metrics` endpoint for real-time operational monitoring.\n- **Access Log Storage:** Detailed request logs, including token usage and costs, are stored in a local DuckDB database.\n- **Analytics API:** Endpoints to query and analyze historical usage data.\n- **Real-time Dashboard:** A live web interface at `/dashboard` to visualize metrics and request streams.\n\nThese features are disabled by default and can be enabled via configuration. For a complete guide on setting up and using these features, see the [Observability Documentation](docs/observability.md).\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Authentication Error:** Ensure you're using the correct mode (`/sdk` or `/api`) for your authentication method.\n2. **Claude Credentials Expired:** Run `ccproxy auth login` to refresh credentials for API mode. Run `claude /login` for SDK mode.\n3. **OpenAI/Codex Authentication Failed:**\n - Check if valid credentials exist: `ccproxy auth status`\n - Ensure you have an active ChatGPT Plus subscription\n - Try re-authenticating: `ccproxy auth login-openai` or `codex auth login`\n - Verify credentials in `$HOME/.codex/auth.json`\n4. **Codex Response API Errors:**\n - \"Instruction prompt injection failed\": The backend requires the Codex prompt; this is automatic\n - \"Session not found\": Use persistent session IDs for conversation continuity\n - \"Model not available\": Ensure you're using ChatGPT Plus compatible models\n5. **Missing API Auth Token:** If you've enabled security, include the token in your request headers.\n6. **Port Already in Use:** Start the server on a different port: `ccproxy --port 8001`.\n7. **Model Not Available:** Check that your subscription includes the requested model.\n\n## Contributing\n\nPlease see [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Documentation\n\n- **[Online Documentation](https://caddyglow.github.io/ccproxy-api)**\n- **[API Reference](https://caddyglow.github.io/ccproxy-api/api-reference/overview/)**\n- **[Developer Guide](https://caddyglow.github.io/ccproxy-api/developer-guide/architecture/)**\n\n## Support\n\n- Issues: [GitHub Issues](https://github.com/CaddyGlow/ccproxy-api/issues)\n- Documentation: [Project Documentation](https://caddyglow.github.io/ccproxy-api)\n\n## Acknowledgments\n\n- [Anthropic](https://anthropic.com) for Claude and the Claude Code SDK\n- The open-source community\n",
"bugtrack_url": null,
"license": null,
"summary": "API server that provides an Anthropic and OpenAI compatible interface over Claude Code, allowing to use your Claude OAuth account or over the API.",
"version": "0.1.6",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ef8eed8dce78e8007146f8eff53a66b465f1beddbdd78e3096b0ecb25fa9282c",
"md5": "835d2e2d3eaf3ed882de94c31a79d498",
"sha256": "19235fc7b6863d37cbb0131a8ca66ed21d9ff5cca0ead8a759e12bc4acaa7418"
},
"downloads": -1,
"filename": "ccproxy_api-0.1.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "835d2e2d3eaf3ed882de94c31a79d498",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 390815,
"upload_time": "2025-08-13T14:50:16",
"upload_time_iso_8601": "2025-08-13T14:50:16.865971Z",
"url": "https://files.pythonhosted.org/packages/ef/8e/ed8dce78e8007146f8eff53a66b465f1beddbdd78e3096b0ecb25fa9282c/ccproxy_api-0.1.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "15128e087406ec5f6b8a0626dcddd71668c5d6e48f38cd04d219fde3e7988c3c",
"md5": "c177f7f9f870f872bd6069f9ded3e84d",
"sha256": "85b59fa3a6bfb25fc969277a9a7fdf393e398cc96b01bb662f1aae423c512182"
},
"downloads": -1,
"filename": "ccproxy_api-0.1.6.tar.gz",
"has_sig": false,
"md5_digest": "c177f7f9f870f872bd6069f9ded3e84d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 769591,
"upload_time": "2025-08-13T14:50:18",
"upload_time_iso_8601": "2025-08-13T14:50:18.134294Z",
"url": "https://files.pythonhosted.org/packages/15/12/8e087406ec5f6b8a0626dcddd71668c5d6e48f38cd04d219fde3e7988c3c/ccproxy_api-0.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-13 14:50:18",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "ccproxy-api"
}
