CLI coding tools

A coding tool needs three settings to work with Shannon: the base URL of the API, your API key, and a Shannon model id. This page gives the exact settings for Claude Code and Codex CLI, explains how the coding model shannon-coder-1 is counted, and lists the errors these tools meet.

Which endpoint each tool uses

All three endpoints take the same API key, as Authorization: Bearer or as x-api-key. The headers anthropic-version, anthropic-beta and openai-beta that these tools send are accepted.

Select a Shannon model

Every request must name a model id that Shannon publishes. A coding tool sends the name of its own default model unless you tell it otherwise, and a name Shannon does not publish is answered with 400 and the message unknown model: <name>. No other name is mapped to a Shannon model, so set the model in the tool before the first request.

GET /v1/models lists every id with its context window. It needs no key. Models & pricing

Coding tools steer the model with a long system prompt. The system prompt is applied by shannon-coder-1, shannon-1.6-lite, shannon-1.6-pro, shannon-2-lite, shannon-2-pro and the hosted open-weight models, so select one of these for a coding tool.

Claude Code

Claude Code reads its connection from environment variables. Set them in the shell that starts it, or in the env block of ~/.claude/settings.json to keep them for every session.

# Install Claude Code
npm install -g @anthropic-ai/claude-code

# Where to send requests, and your Shannon API key
export ANTHROPIC_BASE_URL=https://api.shannon-ai.com
export ANTHROPIC_AUTH_TOKEN=YOUR_API_KEY

# Shannon model ids: the session model, and the model behind each built-in name
export ANTHROPIC_MODEL=shannon-coder-1
export ANTHROPIC_DEFAULT_OPUS_MODEL=shannon-coder-1
export ANTHROPIC_DEFAULT_SONNET_MODEL=shannon-coder-1
export ANTHROPIC_DEFAULT_HAIKU_MODEL=shannon-1.6-lite

# The context window of the session model
export CLAUDE_CODE_MAX_CONTEXT_TOKENS=131072

claude

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.shannon-ai.com",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY",
    "ANTHROPIC_MODEL": "shannon-coder-1",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "shannon-coder-1",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "shannon-coder-1",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "shannon-1.6-lite",
    "CLAUDE_CODE_MAX_CONTEXT_TOKENS": "131072"
  }
}

• Set all three ANTHROPIC_DEFAULT_…_MODEL variables. Subagents and some commands ask for a model by its built-in name, and each name must resolve to a Shannon id.
• The sample points background requests at shannon-1.6-lite, which is counted in tokens. Session titles and similar requests then do not use Coder calls.
• Claude Code asks POST /v1/messages/count_tokens for the size of the context. The endpoint counts for the hosted open-weight models. With a Shannon id it answers 400; Claude Code treats token counting as optional and estimates the size itself. Token counting

To check the address, the key and a model id before you start the tool, send one request by hand:

curl https://api.shannon-ai.com/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "shannon-1.6-lite",
    "max_tokens": 16,
    "messages": [{"role": "user", "content": "Say OK."}]
  }'

Codex CLI

Codex CLI talks to the Responses API. Describe Shannon as a model provider in ~/.codex/config.toml, select a Shannon model id there, and put your API key in the environment variable the provider names.

model = "shannon-coder-1"
model_provider = "shannon"
model_context_window = 131072

[model_providers.shannon]
name = "Shannon"
base_url = "https://api.shannon-ai.com/v1"
env_key = "SHANNON_API_KEY"
wire_api = "responses"

# Install Codex CLI
npm install -g @openai/codex

# Your Shannon API key, under the name given as env_key
export SHANNON_API_KEY=YOUR_API_KEY

# Start it; --model selects another Shannon id for one run
codex
codex --model shannon-1.6-pro

• /v1/responses keeps no conversation on the server: each request carries the conversation in input. previous_response_id is accepted for compatibility.
• Function tools (type: "function") are offered to the model on /v1/responses.
• On /v1/responses, shannon-coder-1 is counted in tokens from your balance, not in Coder calls.

The same check for the Responses endpoint:

curl https://api.shannon-ai.com/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "shannon-1.6-lite",
    "input": "Say OK."
  }'

The coding model and how it is counted

shannon-coder-1 is the Shannon model for coding agents. GET /v1/models reports it with a context window of 131,072 tokens, tool calls, reasoning and text input. It is counted in one of two ways, depending on the endpoint a tool uses.

A call is one request, whatever its size. It is counted when the request is accepted, before the model answers. An agent session sends one request for every step it takes, so a long task uses many calls. The allowance depends on your plan and starts again every 4 hours, at 00:00, 04:00, 08:00, 12:00, 16:00 and 20:00 UTC.

The plan page shows the current numbers. Plans

When the calls of a window are used up, the request is answered with 429. On /v1/messages the same error comes in the Anthropic shape.

{
  "error": {
    "type": "rate_limit_error",
    "message": "Shannon Coder call quota reached. Upgrade your plan at shannon-ai.com/plan"
  }
}

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "Shannon Coder call quota reached. Upgrade your plan at shannon-ai.com/plan"
  }
}

Context overflow

When a conversation is larger than the context window of the model, /v1/chat/completions and /v1/messages answer with 400, the type invalid_request_error, the code context_length_exceeded and a message that starts with prompt is too long. Coding tools read this error to compact the session and send the request again. It is produced by shannon-coder-1, shannon-1.6-lite and shannon-1.6-pro.

{
  "error": {
    "type": "invalid_request_error",
    "code": "context_length_exceeded",
    "message": "prompt is too long: 140211 tokens > 131072 maximum",
    "param": null
  }
}

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "code": "context_length_exceeded",
    "message": "prompt is too long: 140211 tokens > 131072 maximum",
    "param": null
  }
}

The message is prompt is too long: <sent> tokens > <limit> maximum. When the two numbers are not known it is prompt is too long. Please compact the conversation and try again.

On a stream the status is already 200, so the error arrives as an event and the stream then closes in the normal way:

data: {"error":{"message":"prompt is too long: 140211 tokens > 131072 maximum","type":"invalid_request_error","code":"context_length_exceeded","param":null}}

data: {"id":"chatcmpl-…","object":"chat.completion.chunk","created":…,"model":"shannon-coder-1","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{…}}

data: [DONE]

event: error
data: {"type":"error","error":{"type":"invalid_request_error","message":"prompt is too long: 140211 tokens > 131072 maximum"}}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{…}}

event: message_stop
data: {"type":"message_stop"}

What an agent loop can rely on

Troubleshooting

Your key and your balance are on the Keys & usage page. Keys & usage