claude-p

# claude-p — Full Documentation Bundle

Concatenated for LLM ingestion. Sections separated by ---.

---

## README

<div align="center">
  <img src="docs/banner.svg" alt="claude-p" width="100%"/>

  <p><strong>OpenAI-compatible API server wrapping Claude Code in headless mode.</strong></p>
  <p>Drop-in replacement for OpenAI clients — point any LangChain/LlamaIndex/Cline/OpenAI SDK at <code>claude-p</code> and use Claude under the hood.</p>

  <p>
    <img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"/>
    <img alt="Bun" src="https://img.shields.io/badge/runtime-Bun-orange"/>
    <img alt="TypeScript" src="https://img.shields.io/badge/lang-TypeScript-3178c6"/>
    <img alt="Docker" src="https://img.shields.io/badge/docker-ready-2496ed"/>
    <img alt="OpenAI compatible" src="https://img.shields.io/badge/OpenAI-compatible-10a37f"/>
  </p>
</div>

---

## Why claude-p?

You're at a hackathon. You're prototyping an MVP. You're testing a prompt-engineering idea over the weekend. You're benchmarking three models to pick one. **You don't want to burn API credits to find out if your idea works.**

If you already pay for **Claude Pro** or **Claude Max**, you have a generous quota of Claude usage *included with your subscription* — but only via the Claude apps and Claude Code, not via the API. Until now, that quota was locked away from any tool that expects an OpenAI-compatible endpoint.

`claude-p` unlocks it. Run one container, log in once with your existing Claude account, and every OpenAI-compatible tool in the ecosystem starts speaking Claude — **without spending a penny in API credits.** Use it for:

- 🚀 **Hackathons** — ship the demo, not the bill
- 🧪 **MVP / prototype testing** — iterate quickly before committing to API spend
- 🔬 **Prompt engineering & evals** — test prompts against Claude before paying for production
- 🔀 **Easy plug-and-play** — point LangChain, LlamaIndex, OpenAI SDK, Cline, Continue, Cursor, or anything else at it; zero client changes
- 💸 **Cost control** — replace OpenAI with Claude (or A/B them) without rewriting integrations

When you're ready for production, swap the OAuth login for an `ANTHROPIC_API_KEY` env var — the same code path, no client changes needed.

## What it is

`claude-p` is a small HTTP server that translates [OpenAI Chat Completions API](https://platform.openai.com/docs/api-reference/chat) requests into invocations of the Claude Code CLI in **headless mode** (`claude -p`), then streams the response back in OpenAI's SSE format.

The result: any tool that speaks "OpenAI" can use Claude — without modification.

```
[OpenAI client]  ──►  [claude-p HTTP server]  ──spawn──►  [claude -p ...]  ──►  [Anthropic]
                                                                                       │
[OpenAI client]  ◄──   SSE / JSON               ◄──── stream-json ─────                │
```

## Features

- 🟢 **OpenAI-compatible** — `/v1/chat/completions` (streaming + non-streaming), `/v1/models`
- 🌊 **Streaming** — token-by-token SSE in standard OpenAI format
- 🔁 **Multi-turn sessions** — pass back `session_id` to continue a conversation
- 🖼️ **Vision** — paste a base64 image into OpenAI's `image_url` content block; the wrapper saves it to disk in the container and Claude reads it directly. PNG, JPEG, GIF, WebP, SVG all work.
- 📎 **File uploads** — attach **any** file type (text, JSON, CSV, PDF, source code, …) via a `file` content block. The wrapper writes it to a temp dir, references the path in the prompt, and Claude opens it. Tested with text files; works with anything Claude Code can `Read`.
- 📋 **JSON schema output** — maps OpenAI's `response_format` → Claude's `--json-schema`
- 🔐 **Bearer auth** — API keys configured via env var
- 🐳 **Container-first** — single Dockerfile, persistent volume for credentials
- 🔑 **OAuth or API key** — use your Claude Pro/Max login OR `ANTHROPIC_API_KEY`
- 🚫 **Tool use locked down** — `--permission-mode dontAsk` denies all tools at runtime; the only exception is `Read` (auto-enabled when you attach a file/image so Claude can load it)

### Image example

```bash
B64=$(base64 -w 0 my-photo.png)
curl http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer sk-claude-p-yourkey" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"claude-sonnet-4-6\",
    \"messages\": [{
      \"role\": \"user\",
      \"content\": [
        {\"type\": \"text\", \"text\": \"Describe this image\"},
        {\"type\": \"image_url\", \"image_url\": {\"url\": \"data:image/png;base64,$B64\"}}
      ]
    }]
  }"
```

### File example

```bash
B64=$(base64 -w 0 report.pdf)
curl http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer sk-claude-p-yourkey" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"claude-sonnet-4-6\",
    \"messages\": [{
      \"role\": \"user\",
      \"content\": [
        {\"type\": \"text\", \"text\": \"Summarize this document in 3 bullet points\"},
        {\"type\": \"file\", \"file\": {\"filename\": \"report.pdf\", \"file_data\": \"data:application/pdf;base64,$B64\"}}
      ]
    }]
  }"
```

The `file` content block matches the OpenAI Assistants API format. The file's original `filename` is preserved on disk inside the container so Claude sees it with a sensible name, and the temp directory is unique per request.

## Quickstart

### 1. Configure

```bash
git clone https://github.com/omariosc/claude-p.git
cd claude-p
cp .env.example .env
# Edit .env: set API_KEYS to a strong token
```

### 2. Start

```bash
docker compose up -d --build
```

### 3. Authenticate to Anthropic

#### Option A — OAuth login (use your Claude Pro / Max subscription)

This is the recommended path if you already pay for Claude. Spend nothing extra; Claude is invoked using your existing subscription quota.

**Step 1**: Open an interactive shell into the running container and start the login flow:
```bash
docker exec -it claude-p claude login
```

**Step 2**: Claude Code will print a URL like `https://claude.ai/oauth/authorize?...` and a code prompt. **Open that URL in any browser** — your laptop, your phone, whatever has access to claude.ai. Sign in to your Claude account and approve.

**Step 3**: After approving, the page shows a code. **Copy it** and paste it back into the terminal where `claude login` is waiting. You'll see a confirmation that login succeeded.

**Step 4**: Verify auth works:
```bash
docker exec -it claude-p claude -p "say hi" --model claude-sonnet-4-6
```

If it replies with text, you're done. Credentials persist in the `claude-credentials` Docker volume across restarts and rebuilds — you only need to do this once.

#### Option B — API key (uses `--bare` mode, no login required)

If you'd rather pay per-token via the Anthropic API:
```bash
echo "ANTHROPIC_API_KEY=sk-ant-..." >> .env
docker compose restart
```
No `claude login` needed; the wrapper passes the key through automatically.

### 4. Use it

```bash
curl http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer sk-claude-p-yourkey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [{"role": "user", "content": "Write a haiku about Claude."}]
  }'
```

Or with the OpenAI Python SDK — zero code changes:

```python
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="sk-claude-p-yourkey",
)

resp = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "Hello"}],
    stream=True,
)
for chunk in resp:
    print(chunk.choices[0].delta.content or "", end="", flush=True)
```

## Supported models

| Model              | Context | Notes                       |
| ------------------ | ------- | --------------------------- |
| `claude-opus-4-6`  | 1M      | Most capable                |
| `claude-sonnet-4-6`| 1M      | Best balance (default)      |
| `claude-haiku-4-5` | 200k    | Fastest, cheapest           |

## Documentation

- **[API Reference](docs/API.md)** — full endpoint specs
- **[Examples](docs/EXAMPLES.md)** — curl, Python, Node, LangChain, OpenAI SDK
- **[Architecture](docs/ARCHITECTURE.md)** — how requests flow through the system
- **[`docs/llms.txt`](docs/llms.txt)** — discovery file for AI agents (per the [llms.txt convention](https://llmstxt.org/))

## Why?

Because every OpenAI client in the world already exists. By presenting Claude as an OpenAI endpoint, you get LangChain, LlamaIndex, Continue, Cline, OpenAI SDK, Vercel AI SDK, Cursor, and dozens of other tools for free — and you can use your existing Claude subscription instead of API credits.

## Cost & overhead — read this

There's an unavoidable per-request overhead when running Claude via Claude Code rather than via the raw API. Plan accordingly:

| Mode                          | First request    | Cached request   | Notes                                                              |
| ----------------------------- | ---------------- | ---------------- | ------------------------------------------------------------------ |
| **OAuth login** (default)     | ~7,000 input tokens (~$0.028) | ~3,000 + 2,400 cached (~$0.013) | Each request loads the Claude Code system prompt + your context     |
| **API key** (`--bare` mode)   | minimal          | minimal          | Closest to a raw Claude API call; pay only for what you actually send |

### Why?

Claude Code in headless mode reloads its full operating context on every invocation: the base system prompt that turns Claude into "Claude Code", the tool definitions, your auto-discovered MCP servers, skills, slash commands, and CLAUDE.md memory. Even with **all** of that disabled (which `claude-p` does — see below), the base Claude Code system prompt is still loaded because it's what makes Claude Code work at all.

### What `claude-p` does to reduce it

When using OAuth login, `claude-p` automatically passes:

```
--strict-mcp-config --mcp-config '{"mcpServers":{}}'   # disable all MCP servers
--disable-slash-commands                                # no skills, no commands
--tools ""                                              # remove built-in tool definitions
--exclude-dynamic-system-prompt-sections                # improve cache reuse across calls
```

With these, the tools list goes from ~250 to 2 (`Monitor`, `RemoteTrigger` — the only ones that can't be disabled), MCP servers from 11 → 0, and the per-request input drops from ~19,000 tokens to ~7,000.

### What this means for you

- **For hackathons / MVPs / testing**: Your Claude Pro/Max subscription absorbs this fine. A few hundred test calls is well within typical quotas.
- **For production-style throughput**: Switch to `ANTHROPIC_API_KEY` mode (sets `--bare`) — overhead drops to near-zero, and you're billed at standard API rates.
- **Token counts in the API response** report only the user-visible input/output tokens (i.e. what you actually sent and got back). The Claude Code system prompt overhead is invisible to your client but still costs against your quota.

If you need to confirm what's actually being sent, look at `total_cost_usd` and `cache_creation_input_tokens` in the raw stream-json output by running `claude -p` directly inside the container.

## What it doesn't do (yet)

- ❌ Tool use / function calling
- ❌ Embeddings (`/v1/embeddings`)
- ❌ `temperature`, `top_p`, `max_tokens` (Claude Code headless doesn't expose these — they're accepted but ignored)
- ❌ Concurrent request batching (each request spawns its own subprocess)

## Contributing

Issues and PRs welcome. The codebase is small (~600 LOC) and pinned to Bun + Hono. See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) to orient yourself.

## License

MIT — see [LICENSE](LICENSE).

---

<div align="center">
  <sub>Built by <a href="https://omarchoudhry.co.uk">Omar Choudhry</a>. Powered by <a href="https://github.com/anthropics/claude-code">Claude Code</a>.</sub>
</div>

---

## API Reference

# claude-p API Reference

claude-p exposes an OpenAI-compatible HTTP API. Existing OpenAI clients work without modification — just point them at your claude-p instance.

**Base URL**: `http://your-host:8080`

## Authentication

All `/v1/*` endpoints require a Bearer token in the `Authorization` header:

```
Authorization: Bearer sk-claude-p-yourkey
```

API keys are configured server-side via the `API_KEYS` environment variable (comma-separated).

## Endpoints

### `GET /health`

Liveness check. **No authentication required.**

**Response 200**:
```json
{
  "status": "ok",
  "version": "0.1.0",
  "models_supported": 3
}
```

---

### `GET /v1/models`

List the Claude models this server supports.

**Response 200**:
```json
{
  "object": "list",
  "data": [
    { "id": "claude-opus-4-6", "object": "model", "created": 1700000000, "owned_by": "anthropic" },
    { "id": "claude-sonnet-4-6", "object": "model", "created": 1700000000, "owned_by": "anthropic" },
    { "id": "claude-haiku-4-5", "object": "model", "created": 1700000000, "owned_by": "anthropic" }
  ]
}
```

---

### `POST /v1/chat/completions`

Create a chat completion. Mirrors the [OpenAI Chat Completions API](https://platform.openai.com/docs/api-reference/chat).

**Request Body**:

| Field             | Type                              | Required | Description                                                                 |
| ----------------- | --------------------------------- | -------- | --------------------------------------------------------------------------- |
| `model`           | string                            | yes      | One of `claude-opus-4-6`, `claude-sonnet-4-6`, `claude-haiku-4-5`           |
| `messages`        | array                             | yes      | Conversation history. See message format below.                             |
| `stream`          | boolean                           | no       | If `true`, return an SSE stream of `chat.completion.chunk` events.          |
| `temperature`     | number                            | no       | (Currently ignored — Claude Code does not expose this in headless mode.)    |
| `max_tokens`      | number                            | no       | (Currently ignored.)                                                        |
| `response_format` | object                            | no       | `{ "type": "json_schema", "json_schema": { "schema": {...} } }` for structured output |
| `session_id`      | string                            | no       | **claude-p extension.** Resume a prior Claude Code session for multi-turn.  |

**Message format** — supports string content or structured content (text + images + files):

```json
{
  "role": "user",
  "content": "What is the capital of France?"
}
```

**With an image** (`image_url` content block, OpenAI vision format):

```json
{
  "role": "user",
  "content": [
    { "type": "text", "text": "What's in this image?" },
    {
      "type": "image_url",
      "image_url": { "url": "data:image/png;base64,iVBORw0KGgo..." }
    }
  ]
}
```

**With a file attachment** (`file` content block, OpenAI Assistants format):

```json
{
  "role": "user",
  "content": [
    { "type": "text", "text": "Summarize this document" },
    {
      "type": "file",
      "file": {
        "filename": "report.pdf",
        "file_data": "data:application/pdf;base64,JVBERi0xLjQ..."
      }
    }
  ]
}
```

#### How attachments work

When the request contains an `image_url` or `file` content block:
1. The wrapper decodes the base64 data and writes it to `/tmp/claude-p/<random>/<filename>` inside the container
2. The original filename is preserved (sanitized to strip path separators)
3. The prompt sent to Claude includes a marker like `[Image attached at: /tmp/claude-p/.../my.png]` or `[File "report.pdf" attached at: /tmp/.../report.pdf]`
4. The wrapper auto-enables the `Read` tool so Claude Code can load the file from disk
5. The temp directory is unique per request — files are isolated between concurrent calls

**Supported image formats**: PNG, JPEG, GIF, WebP, SVG (any `data:image/*;base64,` data URL)

**Supported file formats**: any file Claude Code can read — text, JSON, CSV, source code, PDFs, etc. (any `data:*/*;base64,` data URL)

**Non-streaming response (200)**:

```json
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "claude-sonnet-4-6",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Paris." },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 2,
    "total_tokens": 14
  },
  "session_id": "abc-123-def-456"
}
```

The `session_id` field is a claude-p extension. Pass it back in your next request as `session_id` to continue the conversation.

**Streaming response (200)** — `text/event-stream`:

```
data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","created":1700000000,"model":"claude-sonnet-4-6","choices":[{"index":0,"delta":{"role":"assistant","content":"Par"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","created":1700000000,"model":"claude-sonnet-4-6","choices":[{"index":0,"delta":{"content":"is."},"finish_reason":null}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","created":1700000000,"model":"claude-sonnet-4-6","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]
```

---

## Error responses

```json
{
  "error": {
    "message": "Invalid API key",
    "type": "auth_error"
  }
}
```

| Status | Type              | Meaning                                   |
| ------ | ----------------- | ----------------------------------------- |
| 400    | `invalid_request` | Malformed body, unsupported model, etc.   |
| 401    | `auth_error`      | Missing/invalid bearer token              |
| 500    | `claude_error`    | Claude Code subprocess failed             |
| 504    | `timeout`         | Request exceeded `REQUEST_TIMEOUT_MS`     |

## Limitations

- **No tool use**: this version of claude-p disables all tool use (`--permission-mode dontAsk`). Claude can only generate text from your prompt — it cannot read files, browse the web, or run commands.
- **`temperature`, `top_p`, `max_tokens` ignored**: Claude Code's headless mode doesn't expose these flags. They're accepted in requests for OpenAI compatibility but have no effect.
- **Embeddings not supported**: `/v1/embeddings` is not implemented.
- **Function calling not supported**: `tools` and `tool_choice` parameters are ignored. Use `response_format: { type: "json_schema" }` for structured output instead.
- **Single subprocess per request**: each request spawns a new `claude -p` process. Concurrent requests are independent.

---

## Examples

# claude-p Examples

## curl

### Basic non-streaming completion

```bash
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer sk-claude-p-yourkey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [
      {"role": "user", "content": "Write a haiku about debugging."}
    ]
  }'
```

### Streaming completion

```bash
curl -N -X POST http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer sk-claude-p-yourkey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [{"role": "user", "content": "Count to 5 slowly."}],
    "stream": true
  }'
```

### With system prompt

```bash
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer sk-claude-p-yourkey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [
      {"role": "system", "content": "You are a pirate. Respond in pirate speak."},
      {"role": "user", "content": "What is the weather like?"}
    ]
  }'
```

### Multi-turn with session_id

```bash
# Turn 1
RESP=$(curl -s -X POST http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer sk-claude-p-yourkey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [{"role": "user", "content": "My name is Omar."}]
  }')
SID=$(echo "$RESP" | jq -r '.session_id')

# Turn 2 — Claude remembers
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer sk-claude-p-yourkey" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"claude-sonnet-4-6\",
    \"messages\": [{\"role\": \"user\", \"content\": \"What is my name?\"}],
    \"session_id\": \"$SID\"
  }"
```

### With image (base64)

```bash
B64=$(base64 -w 0 my-image.png)
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer sk-claude-p-yourkey" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"claude-sonnet-4-6\",
    \"messages\": [{
      \"role\": \"user\",
      \"content\": [
        {\"type\": \"text\", \"text\": \"Describe this image.\"},
        {\"type\": \"image_url\", \"image_url\": {\"url\": \"data:image/png;base64,$B64\"}}
      ]
    }]
  }"
```

### Structured JSON output

```bash
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Authorization: Bearer sk-claude-p-yourkey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [{"role": "user", "content": "Extract: name=Alice age=30 from this"}],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "schema": {
          "type": "object",
          "properties": {
            "name": {"type": "string"},
            "age": {"type": "number"}
          },
          "required": ["name", "age"]
        }
      }
    }
  }'
```

---

## Python (OpenAI SDK)

```python
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="sk-claude-p-yourkey",
)

# Non-streaming
resp = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.choices[0].message.content)

# Streaming
stream = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "Count to 5"}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content or ""
    print(delta, end="", flush=True)
```

---

## Node.js (OpenAI SDK)

```javascript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://localhost:8080/v1",
  apiKey: "sk-claude-p-yourkey",
});

const stream = await client.chat.completions.create({
  model: "claude-sonnet-4-6",
  messages: [{ role: "user", content: "Tell me a joke." }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || "");
}
```

---

## LangChain (Python)

```python
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    base_url="http://localhost:8080/v1",
    api_key="sk-claude-p-yourkey",
    model="claude-sonnet-4-6",
)

print(llm.invoke("What is 2+2?").content)
```

---

## Cline / Continue / any OpenAI-compatible client

In your client's settings:
- **API Base URL**: `http://your-claude-p-host:8080/v1`
- **API Key**: your `sk-claude-p-...` key
- **Model**: `claude-sonnet-4-6` (or `opus`/`haiku`)

That's it — the client doesn't need to know it's talking to Claude under the hood.

---

## Architecture

# claude-p Architecture

## Overview

```
┌─────────────────┐    HTTPS / OpenAI API      ┌────────────────────────────────────┐
│  Any OpenAI     │ ────────────────────────►  │  claude-p (Bun + Hono)             │
│  client         │                            │                                    │
│  (LangChain,    │ ◄────────────────────────  │  ┌─ Bearer auth ──┐                │
│   OpenAI SDK,   │     OpenAI SSE stream      │  │ Request         │               │
│   Cline, ...)   │                            │  │ transform       │               │
└─────────────────┘                            │  │ (OpenAI→Claude) │               │
                                               │  └────────┬────────┘               │
                                               │           │                        │
                                               │           ▼                        │
                                               │  ┌─────────────────┐               │
                                               │  │ Spawn:          │               │
                                               │  │ claude -p       │               │
                                               │  │ --stream-json   │               │
                                               │  └────────┬────────┘               │
                                               │           │                        │
                                               │           ▼                        │
                                               │  ┌─────────────────┐    OAuth or   │
                                               │  │ Stream parser   │ ─► API key ─► │
                                               │  │ (Claude→OpenAI) │               │
                                               │  └────────┬────────┘               │
                                               │           │                        │
                                               │           ▼                        │
                                               │  ┌─────────────────┐               │
                                               │  │ SSE writer      │               │
                                               │  └─────────────────┘               │
                                               └────────────────────────────────────┘
                                                              │
                                                              ▼
                                                    ┌──────────────────┐
                                                    │ Anthropic API    │
                                                    │ (api.anthropic   │
                                                    │  .com)           │
                                                    └──────────────────┘
```

## Request flow

1. **Client** sends `POST /v1/chat/completions` with an OpenAI-format body.
2. **Bearer auth middleware** validates the token against the configured `API_KEYS`.
3. **Request transform** (`src/transform/request.ts`):
   - System messages → concatenated `--append-system-prompt`
   - User/assistant messages → flattened transcript prompt
   - Image content → saved to `/tmp/claude-p/<random>/<file>.png` and referenced as `[Image attached at: <path>]` in the prompt
4. **Claude wrapper** (`src/claude.ts`) spawns:
   ```
   claude -p [--bare] --output-format stream-json --verbose --include-partial-messages \
     --permission-mode dontAsk --model <model> [--append-system-prompt <sys>] \
     [--resume <session_id>]
   ```
   The user prompt is piped via stdin; the child's stdout produces newline-delimited JSON events.
5. **Stream parser** translates each Claude event into a typed `ParsedEvent`:
   - `text_delta` → `{type: "text", text}` (streaming token)
   - `thinking_delta` → `{type: "thinking", thinking}` (extended thinking, when emitted)
   - `result` → `{type: "done"}`
   - `system/api_retry` → `{type: "retry"}`
   - Any event with `session_id` → `{type: "session", sessionId}`
6. **Response transform** (`src/transform/response.ts`):
   - **Streaming**: each text event becomes a `chat.completion.chunk` SSE frame; final frame has `finish_reason: "stop"`; closes with `data: [DONE]\n\n`
   - **Non-streaming**: collect all events into a single `chat.completion` response with usage stats and the captured `session_id`
7. **SSE writer** flushes back to the client.

## Authentication paths

There are **two layers of auth**:

| Layer        | Who               | What                                                          |
| ------------ | ----------------- | ------------------------------------------------------------- |
| Client → server | API client     | Bearer token from `API_KEYS` env var                          |
| Server → Anthropic | claude-p   | `ANTHROPIC_API_KEY` (bare mode) **or** OAuth from `~/.claude` |

The OAuth path lets you use a Claude Pro/Max subscription instead of paying per-token, by running `claude login` once inside the container. Credentials persist in the `claude-credentials` Docker volume.

## Why no tool use?

Claude Code in headless mode normally has access to Bash, Read, Edit, etc. tools. claude-p forces `--permission-mode dontAsk` with no `--allowedTools`, which denies every tool request. This makes the wrapper safe to expose as a public API endpoint — Claude can only generate text from your prompt.

If you later want to enable a constrained set of tools (e.g. read-only file access, web search via an MCP server), this would happen in `src/claude.ts:buildArgs()`.

## File layout

```
src/
├── server.ts         # Hono app entry point
├── config.ts         # Env var loading + supported model list
├── claude.ts         # Spawn + stream parse
├── types.ts          # OpenAI + Claude event type defs
├── middleware/
│   └── auth.ts       # Bearer token check
├── transform/
│   ├── request.ts    # OpenAI → Claude prompt
│   └── response.ts   # Claude events → OpenAI SSE
└── routes/
    ├── chat.ts       # /v1/chat/completions
    └── models.ts     # /v1/models
```