> For the complete documentation index, see [llms.txt](https://docs.avis.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avis.xyz/integrations/coding/claude-code.md). # Claude Code ## Claude Code Integration Guide This document explains how to integrate [Claude Code](https://claude.com/product/claude-code) — Anthropic's official terminal coding agent — with the AVIS Anthropic-compatible API. ### What is Claude Code Claude Code is a CLI coding agent that runs in your terminal, reads/edits files, and executes shell commands as part of an agentic loop. It speaks the native Anthropic Messages API, so it works against AVIS through the Anthropic-compatible surface with no code changes — only base URL and auth. ### 1) Install Claude Code ```bash # macOS / Linux / WSL curl -fsSL https://claude.ai/install.sh | bash # Windows PowerShell irm https://claude.ai/install.ps1 | iex # Homebrew brew install --cask claude-code ``` If the native installer hangs or never completes (common on networks that throttle/block `claude.ai` directly — seen in practice on at least one corporate network), install via npm instead, which pulls from the npm registry rather than Anthropic's CDN: ```bash node -v # requires Node 18+ npm install -g @anthropic-ai/claude-code ``` Verify: ```bash claude --version ``` ### 2) Get an AVIS API key See Authentication — sign in at [avis.xyz](https://avis.xyz), go to **Settings → API Keys**, and create one. ### 3) Point Claude Code at AVIS Claude Code reads three environment variables for a custom Anthropic-compatible provider: | Variable | Value | | ---------------------- | ------------------------------------- | | `ANTHROPIC_BASE_URL` | `https://api.avis.xyz/api/anthropic` | | `ANTHROPIC_AUTH_TOKEN` | your AVIS API key | | `ANTHROPIC_API_KEY` | `""` (must be blank — see note below) | `ANTHROPIC_AUTH_TOKEN` is sent as `Authorization: Bearer `, which AVIS accepts as an alternative to `x-api-key` (see Authentication). If `ANTHROPIC_API_KEY` is also set (e.g. left over from a real Anthropic account), Claude Code sends `x-api-key` using that instead of your AVIS token — leaving it non-empty is the most common cause of AVIS returning `401` even though `ANTHROPIC_AUTH_TOKEN` looks correct. #### Option A — Shell profile (applies to every project) Add to `~/.zshrc` / `~/.bashrc` / `~/.config/fish/config.fish`: ```bash export AVIS_API_KEY="" export ANTHROPIC_BASE_URL="https://api.avis.xyz/api/anthropic" export ANTHROPIC_AUTH_TOKEN="$AVIS_API_KEY" export ANTHROPIC_API_KEY="" ``` `ANTHROPIC_AUTH_TOKEN` must be defined **after** `AVIS_API_KEY` in the file — if the reference resolves before the variable it points to is set, it silently expands to an empty token and every request 401s. Re-open the terminal (or `source` the file) after editing. #### Option B — Project-level, `.claude/settings.local.json` ```json { "env": { "ANTHROPIC_BASE_URL": "https://api.avis.xyz/api/anthropic", "ANTHROPIC_AUTH_TOKEN": "", "ANTHROPIC_API_KEY": "" } } ``` Scoped to the current project only — use this if you only want AVIS active for a specific repo rather than every `claude` session. > The native installer does **not** read `.env` files — use one of the two options above, not a project `.env`. #### Clear a cached Anthropic login first If this machine has ever run `claude login` (a real Anthropic/Claude Pro or Max account), that cached OAuth session takes priority over the env vars above. Run `/logout` inside a `claude` session once before switching to AVIS, otherwise requests keep going to the real Anthropic API and silently ignore your AVIS config. ### 4) Pick a model Query the live catalog for exact current IDs: ```bash curl https://api.avis.xyz/api/anthropic/v1/models \ -H "x-api-key: $AVIS_API_KEY" | jq '.data[].id' ``` Claude Code's `/model` menu and background-task routing can be pointed at AVIS model IDs via: ```bash export ANTHROPIC_MODEL="anthropic/claude-sonnet-5" export ANTHROPIC_SMALL_FAST_MODEL="anthropic/claude-haiku-4-5" export ANTHROPIC_DEFAULT_OPUS_MODEL="anthropic/claude-opus-5" export ANTHROPIC_DEFAULT_SONNET_MODEL="anthropic/claude-sonnet-5" export ANTHROPIC_DEFAULT_HAIKU_MODEL="anthropic/claude-haiku-4-5" ``` `ANTHROPIC_SMALL_FAST_MODEL` and `ANTHROPIC_DEFAULT_*` control which model backs Claude Code's built-in Opus/Sonnet/Haiku tiers and background subagent calls — without them, selecting a tier by name in a custom-provider setup has nothing valid to resolve to. ### 5) Run Claude Code ```bash cd your-project claude ``` Inside the session, confirm AVIS is actually wired up: ``` /status ``` This opens a panel with **Config** fields including: ``` Auth token: ANTHROPIC_AUTH_TOKEN Anthropic base URL: https://api.avis.xyz/api/anthropic Model: Default () ``` ### 6) Troubleshooting * Native installer (`curl claude.ai/install.sh | bash`) hangs indefinitely, or `curl` alone shows `speed: 0 bytes/s` with no error * The network is silently dropping traffic to `claude.ai` (no connection-refused/timeout message, just no data) — confirm with `curl -o /dev/null -w "%{speed_download}\n" https://registry.npmjs.org` returning a normal speed while the same against `claude.ai` returns `0`. * Install via npm instead (§1) — it uses the npm registry, not Anthropic's CDN, and isn't affected by the same block. * `401 Unauthorized` * `ANTHROPIC_API_KEY` is non-empty and shadowing `ANTHROPIC_AUTH_TOKEN` (see §3). * `ANTHROPIC_AUTH_TOKEN` referenced `AVIS_API_KEY` before it was defined in the shell profile. * A cached `claude login` session is still active — run `/logout` (see §3). * AVIS key is invalid or revoked — verify with `curl` directly against `/api/anthropic/v1/models`. * `403` with a valid key * Account balance is depleted — see Errors. * `404` / model not found * The model ID doesn't match AVIS's catalog — re-check against `GET /api/anthropic/v1/models` (§4), not a hardcoded example. * Requests still hitting the real Anthropic API instead of AVIS * `/status` (§5) will show this immediately — usually a leftover `claude login` session (see §3) or env vars set in a shell profile that isn't the one actually loaded (e.g. `.bashrc` edited but running `zsh`). * `.env` file changes have no effect * The native installer doesn't read `.env` — use shell profile exports or `.claude/settings.local.json` (§3). ### 7) Minimal End-to-End Checklist 1. AVIS API key created (§2). 2. `ANTHROPIC_BASE_URL` / `ANTHROPIC_AUTH_TOKEN` / `ANTHROPIC_API_KEY=""` set via shell profile or `.claude/settings.local.json` (§3). 3. No stale `claude login` session (`/logout` run if one existed). 4. Model IDs confirmed against `GET /api/anthropic/v1/models` (§4). 5. `claude` starts, `/status` shows the AVIS base URL, and a message returns model output. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.avis.xyz/integrations/coding/claude-code.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.