Before you start
Complete organization setup, make sure your account has inference credit, and create a key on the API Keys page. Most coding agents need a tool-capable chat model; Aider’s basic edit workflow does not require native tool calling. Image input and reasoning support depend on the model. These terminal examples use Bash or Zsh on macOS, Linux, or Windows through WSL. Install the Claude Code CLI using the official installation guide, then confirm it is available in this terminal:Get your connection settings
Open Integrations, select a model, then choose Claude Code. The screen uses your organization’s region. The examples below use the public global endpoint; replace it with your regional endpoint and replaceYOUR_MODEL_ID with the full model ID shown there. Choose one of the models listed for this integration.
Set your Pearl API key in the terminal where you run Claude Code:
Configure Claude Code
Start Claude Code in this shell
/status to confirm the URL and model. The Anthropic base URL has no trailing /v1; the client adds /v1/messages. The model overrides keep the main session, configured model aliases, and subagents on the selected Pearl model. This command is process-scoped; rerun it for each new session. Check existing Claude settings for conflicting gateway or cloud-provider overrides.
Keep your existing Claude setup
You do not need to sign out. The launch command starts a Pearl session using a separate settings and history directory at~/.config/pearl/claude. Your usual Claude login and saved model stay in their existing directory. MCP servers, plugins, and settings from that directory are not automatically copied into the Pearl session.
Start each Pearl session with the command above. Running plain claude uses your normal configuration, unless you have other gateway settings in your shell or project. In a Pearl session, /status shows your endpoint and model.
Use the exact Pearl model ID from Integrations, including its original prefix. The command selects that model directly, even if it is absent from Claude’s model picker. When context information is available, the generated command also includes your model’s context window. It caps each response at the displayed output limit.
Start using Claude Code
Open a project folder and start a new conversation. Ask Claude Code to explain a file or make a small change, then approve the file operations you want it to perform. You can review your usage and costs on the Analytics page.Troubleshooting
401: check the key and allow time for a newly created key to reach the inference gateway.404: copy the endpoint and exact model ID from Integrations. OpenAI base URLs end in/v1; the Anthropic SDK and Claude Code use the URL without that suffix.402: check your organization’s credit and billing status.429or Anthropic529: respect retry instructions and reduce concurrency.- For truncated output, check the output limit and reasoning budget. Increase limits only within the model’s maximum output length.