# Claude Code Claude Code is the terminal agent from Anthropic. It uses the Anthropic Messages format and reads its endpoint from environment variables. The quickest way is the Liquid CLI. Use the manual steps only when you must keep the settings in your own files. ## Start with the Liquid CLI The [Liquid CLI](https://inference.ai.exchange/docs/cli.md) starts Claude Code with the exchange as its provider. It sets the base URL, the key and the model for that process only. It writes no file of yours. ```bash curl -fsSL https://inference.ai.exchange/cli/install.sh | bash liquid login liquid claude ``` By default, Opus runs the main agent and `liquid.auto` runs subagents and background calls. | To do this | Run this | | ------------------------------------------- | ------------------------------------------------ | | Pick other models | `liquid claude fable/auto` | | Use one model for all work, ranked by price | `liquid claude --model liquid.auto:cheapest` | | Limit what one request can cost | `liquid claude --cap 0.50` | | Start Claude Code in its auto mode | `liquid claude opus/auto --permission-mode auto` | `liquid claude` reads `--model`, `--cap` and `--filter`. It sends all other arguments to Claude Code. ### A separate config directory `liquid claude` sets `CLAUDE_CONFIG_DIR` to `~/.config/liquid/claude`. That directory holds the settings, history and MCP servers of the Liquid sessions. - A `/model` choice in a Liquid session stays there, so a plain `claude` keeps its own model. - When the session ends, `liquid claude` saves the choice as `liquid model`. The next Liquid session starts with it. At its first start at a terminal, `liquid claude` asks which parts of `~/.claude` to share: | Part | What the Liquid sessions get | | -------------- | ------------------------------------------------------------------------------------------------------------------ | | `instructions` | Links to `CLAUDE.md`, `skills/`, `agents/`, `commands/` and `output-styles/`. | | `plugins` | A link to `plugins/`. Each setup turns plugins on in its own settings. | | `settings` | Your `settings.json` through `--settings`: hooks, permissions and effort. The model of the exchange still applies. | Without a terminal, it shares `instructions`. To change the answer, run one of these commands: ```bash liquid config claude-share instructions,plugins liquid config claude-share none ``` ### The MCP server of the exchange Each `liquid claude` session has the [Liquid MCP server](https://inference.ai.exchange/docs/connect-mcp-server.md) with the key of the session. Claude can buy images, speech and video within the limits of the key. - `liquid mcp claude` adds the server to both directories, with a key that you approve in the browser. - To add another MCP server to the Liquid sessions, run `liquid claude mcp add …`. ## Before you start - A workspace with a balance and a `spend` key. See [API keys](https://inference.ai.exchange/docs/keys.md). - The key exported in your shell, so it never appears in a file: ```bash export LIQUID_API_KEY=sk-liquid-... ``` - Claude Code installed. Install it with the native installer or with npm: ```bash # native installer (macOS, Linux, WSL) curl -fsSL https://claude.ai/install.sh | bash # or with npm npm install -g @anthropic-ai/claude-code ``` ## 1. Point it at the exchange Set these variables in the shell that starts Claude Code. To keep them, add them to `~/.zshrc` or `~/.bashrc`. The second block has the same variables in `.claude/settings.json`, for one project. **Shell** ```bash export ANTHROPIC_AUTH_TOKEN=$LIQUID_API_KEY export ANTHROPIC_BASE_URL=https://router.inference.ai.exchange export ANTHROPIC_DEFAULT_HAIKU_MODEL=cc.anthropic/liquid.auto export ANTHROPIC_DEFAULT_OPUS_MODEL=cc.anthropic/liquid.auto export ANTHROPIC_DEFAULT_SONNET_MODEL=cc.anthropic/liquid.auto export ANTHROPIC_MODEL=cc.anthropic/liquid.auto export CLAUDE_CODE_ATTRIBUTION_HEADER=0 export CLAUDE_CODE_AUTO_MODE_SERVER=0 export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 export CLAUDE_CODE_MAX_OUTPUT_TOKENS=16384 export CLAUDE_CODE_SUBAGENT_MODEL=cc.anthropic/liquid.auto ``` **.claude/settings.json** ```json { "env": { "ANTHROPIC_AUTH_TOKEN": "sk-liquid-...", "ANTHROPIC_BASE_URL": "https://router.inference.ai.exchange", "ANTHROPIC_DEFAULT_HAIKU_MODEL": "cc.anthropic/liquid.auto", "ANTHROPIC_DEFAULT_OPUS_MODEL": "cc.anthropic/liquid.auto", "ANTHROPIC_DEFAULT_SONNET_MODEL": "cc.anthropic/liquid.auto", "ANTHROPIC_MODEL": "cc.anthropic/liquid.auto", "CLAUDE_CODE_ATTRIBUTION_HEADER": "0", "CLAUDE_CODE_AUTO_MODE_SERVER": "0", "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1", "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "16384", "CLAUDE_CODE_SUBAGENT_MODEL": "cc.anthropic/liquid.auto" } } ``` | Variable | Why it is set | | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | `ANTHROPIC_BASE_URL` | The exchange origin, with no `/v1`. A URL that ends in `/v1` makes the client request `/v1/v1/messages`. | | `ANTHROPIC_AUTH_TOKEN` | Your key, sent as a bearer token. Use this, not `ANTHROPIC_API_KEY` (see [below](#2-keep-your-existing-login)). | | `ANTHROPIC_MODEL` | The model for the main agent. It needs the `cc.anthropic/` prefix (see [Model discovery](#model-discovery)). | | `ANTHROPIC_DEFAULT_OPUS_MODEL` | The model for the `opus` alias. | | `ANTHROPIC_DEFAULT_SONNET_MODEL` | The model for the `sonnet` alias. Claude Code sends some side calls to it. | | `ANTHROPIC_DEFAULT_HAIKU_MODEL` | The model for background work such as session titles. See [A different model per task](#a-different-model-per-task). | | `CLAUDE_CODE_SUBAGENT_MODEL` | The model for subagents. Without it, a subagent asks for a `claude-*` model that the exchange does not list. | | `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | Loads the model list of the exchange into the picker. | | `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | Caps the output tokens that Claude Code requests. See [Output token limit](#output-token-limit). | | `CLAUDE_CODE_AUTO_MODE_SERVER` | Stops a notice about auto mode. See [Auto mode checks](#auto-mode-checks). | | `CLAUDE_CODE_ATTRIBUTION_HEADER` | Leaves the version block out of the prompt. See [The attribution block](#the-attribution-block). | Set `LIQUID_API_KEY` before this block. If a profile sets the key on a later line, the token is empty and each request fails with `401`. The project file holds the key in plain text. Use `.claude/settings.local.json` and keep it out of version control. ## 2. Keep your existing login Do not sign out of Claude Code. The variables apply only to the process that you start with them. A plain `claude` in another shell still uses Anthropic. `ANTHROPIC_API_KEY` has priority over `ANTHROPIC_AUTH_TOKEN`. Clear it in the shell that starts Claude Code: ```bash unset ANTHROPIC_API_KEY ``` To keep the variables out of your normal shell, use a wrapper: ```bash claude-liquid() { ANTHROPIC_BASE_URL=... ANTHROPIC_AUTH_TOKEN="$LIQUID_API_KEY" \ CLAUDE_CONFIG_DIR="$HOME/.config/liquid/claude" \ env -u ANTHROPIC_API_KEY claude "$@" } ``` Add the other variables from step 1 to the same line. Keep `CLAUDE_CONFIG_DIR`, the directory that `liquid claude` uses. Without it, Claude Code saves a `/model` choice of the exchange in `~/.claude`, and a plain `claude` uses it. ## 3. Run it ```bash claude ``` ## 4. Check it works 1. Run `/status`. The API base URL and the model must be the values that you set. 2. Send one message. 3. Read the receipt on the **Overview** or **Credits** page of the console. See [Quickstart](https://inference.ai.exchange/docs/quickstart.md). ## Model discovery Claude Code drops each model id that does not contain "claude" or "anthropic". The `cc.anthropic/` prefix keeps the models of the exchange in the picker. Add the `[1m]` suffix if the input window of the model is one million tokens or more: ```bash export ANTHROPIC_MODEL=cc.anthropic/liquid.auto[1m] ``` Use any model, router model or preset on the book. For names, use `GET /v1/models`. See [Market data](https://inference.ai.exchange/docs/market.md). ## Output token limit At high effort, Claude Code asks for 32,000 output tokens by default. - If no offer allows that many, the exchange lowers the request to the largest limit of the offers that can take it. See [Errors](https://inference.ai.exchange/docs/errors.md). - The exchange does not halve the limit to fit your balance. If the balance does not cover 32,000 tokens, the request gets `402 insufficient_balance`. Add funds or lower `CLAUDE_CODE_MAX_OUTPUT_TOKENS`. - An answer that reaches the limit stops with `stop_reason: "max_tokens"`. The block in step 1 sets `16384`. A lower value gives a lower cap for each request. ## A different model per task Claude Code has a model variable for each type of work. The block in step 1 sets all of them to one model. Background work and subagents send many requests, so you can send them to `liquid.auto:economy`: ```bash export ANTHROPIC_DEFAULT_HAIKU_MODEL=cc.anthropic/liquid.auto:economy export CLAUDE_CODE_SUBAGENT_MODEL=cc.anthropic/liquid.auto:economy ``` To pick the ranking, add an axis to the name, such as `cc.anthropic/liquid.auto:fastest`. With the CLI, run `liquid claude --model liquid/auto:fastest`. See [Axis routing](https://inference.ai.exchange/docs/axis-routing.md). ## The cap `liquid.auto` has a cap of its own, so Claude Code needs to send nothing. `GET /v1/exchange/routers` shows its `cap_usd`. To set your own cap, send it as a header, because Claude Code cannot send the `exchange` object. Set this variable, then start Claude Code again: ```bash export ANTHROPIC_CUSTOM_HEADERS="x-liquid-cap-usd: 1.00" ``` In a settings file, add `"ANTHROPIC_CUSTOM_HEADERS": "x-liquid-cap-usd: 1.00"` to the `env` object. The header sets a cap on each request, for all models. Auto buys only from offers whose worst-case charge is within the cap. You can link the key to a preset that sets a price bound instead (see [Purchasing rules](https://inference.ai.exchange/docs/rules.md)). ## Purchasing rules Send the cost cap, the first-token limit and the Auto preference as headers in `ANTHROPIC_CUSTOM_HEADERS`. Put a newline between two headers. ```bash export ANTHROPIC_CUSTOM_HEADERS="x-liquid-cap-usd: 0.50 x-liquid-policy: economy" ``` - If the estimated charge is more than the cap, the exchange refuses the request. It does not shrink it. - `x-liquid-policy` applies only to requests that Auto ranks. It needs Claude Code v2.1.227 or later. For any other rule, such as `exchange.privacy.regions`, send the `exchange` block as JSON in one header: ```bash export ANTHROPIC_CUSTOM_HEADERS='x-liquid-rules: {"privacy":{"regions":["eu"]}}' ``` With the CLI, run `liquid config rules '{"region_policy":["eu"]}'`. See [Rules in one header](https://inference.ai.exchange/docs/rules.md#rules-in-one-header). No header sets the models. Save a preset on the **Presets** page and set a model variable to it: ```bash export CLAUDE_CODE_SUBAGENT_MODEL=cc.anthropic/background ``` See [Purchasing rules](https://inference.ai.exchange/docs/rules.md) for each rule. ## Zero retention If nothing sets `exchange.privacy.retention`, Auto can send your prompt to its classifier. To stop this, send the rule as a header. Only providers that agree not to retain a request can then take it. ```bash export ANTHROPIC_CUSTOM_HEADERS="x-liquid-retention: none" ``` To set the rule for every client of the key, use a preset with `exchange.privacy.retention: "none"`. See [Data handling](https://inference.ai.exchange/docs/data-handling.md). ## Auto mode checks Set `CLAUDE_CODE_AUTO_MODE_SERVER=0`. Without it, the first action of each session stops with a notice that the session is not eligible for no-charge classifier requests. Auto mode works in both cases. The `auto` in `opus/auto` is the [Auto Router](https://inference.ai.exchange/docs/auto.md), not this mode. In auto mode, Claude Code checks an action, such as a shell command, before it runs. With Anthropic, the server does that check at no charge. The exchange works differently: - It returns no verdict. It ignores the `safeguards` field, because a provider could otherwise allow any action. - Claude Code checks the action with its own request. The exchange auctions, caps and charges it like any other request. ## The attribution block Set `CLAUDE_CODE_ATTRIBUTION_HEADER=0`. Claude Code adds a version block to the start of the system prompt. Anthropic removes it by position. The exchange does not, so the block goes to the provider and you pay for its tokens. ## Troubleshooting | Symptom | Cause and fix | | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | The model picker shows only built-in Claude models. | `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` is not `1`, or the shell started before you set it. | | Requests still go to Anthropic. | `ANTHROPIC_API_KEY` has priority. Run `unset ANTHROPIC_API_KEY`, restart, and confirm with `/status`. | | `401` or an authentication error. | Run `echo $ANTHROPIC_AUTH_TOKEN`. If it is empty, a profile sets `LIQUID_API_KEY` too late. Otherwise confirm that the key has the `spend` scope. | | `400 the Auto strategy requires a price bound, …` | `auto_requires_price_bound`. Set the header from [The cap](#the-cap). | | `400 invalid_header`. | A rule in `ANTHROPIC_CUSTOM_HEADERS` cannot be parsed. See [Purchasing rules](#purchasing-rules). | | Answers stop with `stop_reason: "max_tokens"`. | The output limit of the offers is below the request. Choose a model that allows more. | | A plain `claude` reports a problem with the model `cc.anthropic/…`. | A `/model` choice was saved in `~/.claude`. Run `/model` in the plain `claude`. To prevent it, use `liquid claude` or set `CLAUDE_CONFIG_DIR` (see [step 2](#2-keep-your-existing-login)). | | `model_not_found`. | The name is not on the book, or you dropped the `cc.anthropic/` prefix. Check `GET /v1/models`. | | A request is refused for lack of funds. | The balance cannot cover the cap. Add funds on the **Credits** page. | | A notice about auto mode classifier requests. | Set `CLAUDE_CODE_AUTO_MODE_SERVER=0`. See [Auto mode checks](#auto-mode-checks). | | `liquid claude` stops: the saved API key spends from another workspace. | Run `liquid login` to switch to a key for your workspace. See [One key for each workspace](https://inference.ai.exchange/docs/cli.md). | | `liquid claude` stops: a settings file sets `ANTHROPIC_AUTH_TOKEN`. | Remove the variable from the `env` of the file that the error names. | See also [Codex](https://inference.ai.exchange/docs/connect-codex.md) and [Prompt caching](https://inference.ai.exchange/docs/caching.md).