CC API

CC API is a native, session-oriented API for running Claude through the Claude Agent SDK without forcing third-party apps through a stateless OpenAI-style loop.

Why This Exists

Generic OpenAI compatibility was the wrong foundation for Claude-heavy agent runtimes. The inefficient part is not just the HTTP schema. The real waste comes from replaying long histories, re-sending tool definitions, rebuilding continuation state, and duplicating compaction logic in every client.

CC API keeps Claude on a native harness-style session boundary instead:

• persistent session identity
• incremental turns instead of full transcript replay
• structured tool call and tool result continuation
• server-owned event history
• gateway-side compaction and persistence

That makes it a better backend for clients like Hermes and OpenClaw, which can keep their own UX and local tools while avoiding a large amount of repeated token burn.

What It Is

This repo is a self-hosted API server built on the Claude Agent SDK. A user authenticates Claude locally, starts CC API, and points a compatible client at the gateway URL.

This repo is not:

• a hosted Anthropic auth proxy
• a claude.ai subscription resale layer
• a browser login passthrough service

Features

• native session API
• durable session persistence
• SSE event streaming
• multimodal turn input with text, image, and document blocks
• structured tool-call and tool-result continuation
• interrupt and compaction endpoints
• model metadata endpoint with context window information

Endpoints

• GET /
• GET /healthz
• GET /api/models
• GET /api/sessions
• POST /api/sessions
• GET /api/sessions/{id}
• DELETE /api/sessions/{id}
• POST /api/sessions/{id}/interrupt
• GET /api/sessions/{id}/events
• GET /api/sessions/{id}/events/stream
• POST /api/sessions/{id}/turns
• POST /api/sessions/{id}/tool-results
• POST /api/sessions/{id}/compact

Quick Start

python3 -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
cc-api start

Optional gateway auth:

export CC_API_KEY=change-me

The Claude SDK itself still needs local auth, either via existing Claude Code / Claude SDK login state or ANTHROPIC_API_KEY.

Simple Usage

CLI:

cc-api start
cc-api status
cc-api logs
cc-api stop

Foreground mode:

cc-api run

Useful environment variables for local startup:

• CC_API_HOST
• CC_API_PORT
• CC_API_HOME

CC API stores its local process state and logs in ~/.cc-api by default.

macOS Menu Bar App

If you want a simple on/off control in the macOS menu bar:

pip install -e '.[macos]'
cc-api-menu

The menu bar app lets you:

• start CC API
• stop CC API
• open the local server in a browser
• open the current log file

It uses the same launcher and process state as the CLI, so cc-api start and cc-api-menu stay in sync.

Configuration

Canonical environment variables:

• CC_API_MODEL
  • Default model when session creation omits model
  • Default: claude-sonnet-4-5
• CC_API_MODELS
  • Comma-separated seed list for /api/models
• CC_API_PERMISSION_MODE
  • Claude Agent SDK permission mode for plain turns
  • Default: bypassPermissions
• CC_API_TOOL_PERMISSION_MODE
  • Claude Agent SDK permission mode for tool turns
  • Default: bypassPermissions
• CC_API_MAX_TURNS
  • Default: 8
• CC_API_TOOL_MAX_TURNS
  • Default: 4
• CC_API_CWD
  • Working directory used by the SDK
  • Default: repo root
• CC_API_KEY
  • Optional bearer token required by the gateway
• CC_API_SESSION_DB
  • Optional SQLite path for session persistence
  • Default: <repo>/.gateway_sessions/sessions.db
• CC_API_SESSION_DIR
  • Optional JSON-directory persistence backend

Example

Create a session:

curl http://127.0.0.1:8000/api/sessions \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer change-me' \
  -d '{
    "model": "anthropic/claude-opus-4.6",
    "system_prompt": "You are a concise coding assistant."
  }'

Send a turn:

curl http://127.0.0.1:8000/api/sessions/<session_id>/turns \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer change-me' \
  -d '{
    "input": "Inspect this repo and tell me what it does."
  }'

Continue a tool call:

curl http://127.0.0.1:8000/api/sessions/<session_id>/tool-results \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer change-me' \
  -d '{
    "results": [
      {
        "tool_call_id": "call_weather_1",
        "content": "Vancouver is 12C."
      }
    ]
  }'

Development

source .venv/bin/activate
pytest
python -m compileall src