> For the complete documentation index, see [llms.txt](https://docs.nexos.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexos.ai/gateway-api/integrations/claude-code.md).

# Claude Code

### What is Claude Code?

Claude Code is an AI-powered coding assistant designed to help developers write, understand, and improve code more efficiently. Built on Anthropic's Claude models, it provides interactive coding support directly within your development workflow. Claude Code can generate code, explain existing logic, refactor functions, create tests, and assist with debugging through natural-language interactions. It is commonly used to accelerate development, improve code quality, and support engineers in navigating complex codebases.

**Key features:**

* **Intelligent Code Generation** Produces high-quality code snippets, functions, and modules based on natural-language prompts, helping developers move faster.
* **Code Explanation & Understanding** Provides clear explanations of complex code blocks, libraries, or architectural patterns to improve comprehension and onboarding.
* **Refactoring & Optimization** Suggests cleaner, more efficient, or more idiomatic implementations while preserving existing functionality.
* **Automated Test Creation** Generates unit tests, integration tests, and edge-case scenarios to improve code reliability and coverage.
* **Debugging Assistance** Helps identify potential bugs, logic issues, or problematic patterns and proposes fixes.
* **Documentation Support** Creates or updates documentation, docstrings, READMEs, and comments directly from code.
* **Multi-Language Support** Works across a wide range of programming languages, adapting to ecosystem conventions and best practices.
* **Context-Aware Development** Uses project context files, codebase structure, and error logs to deliver highly relevant responses.
* **Interactive Cooperative Workflow** Works like a coding partner. Developers can iterate, review, and refine code through conversational interactions.

nexos.ai now exposes an endpoint compatible with the Anthropic Messages API, so Claude Code talks to the gateway directly. You no longer need a local proxy or the Claude Code Router. To connect your nexos.ai **API** and **Claude Code**, follow these steps:

#### 1. Install Claude Code

**macOS, Linux, WSL:**

```bash
curl -fsSL https://claude.ai/install.sh | bash
```

**Windows PowerShell:**

```powershell
irm https://claude.ai/install.ps1 | iex
```

Or install it with npm:

```bash
npm install -g @anthropic-ai/claude-code
```

#### 2. Connect Claude Code to nexos.ai

Instead of logging in with Anthropic directly, point Claude Code at the nexos.ai gateway. This is done with a few environment variables.

**Requirements:**

1. Use `https://api.nexos.ai` as the base URL. Claude Code appends `/v1/messages` automatically.
2. Provide your API key as the auth token.
3. **Important:** Explicitly blank out the Anthropic API key to avoid conflicts.

Add these lines to your shell profile such as `~/.zshrc`, `~/.bashrc`, or `~/.config/fish/config.fish`:

```bash
export ANTHROPIC_BASE_URL="https://api.nexos.ai"
export ANTHROPIC_AUTH_TOKEN="{YOUR_API_KEY}"
export ANTHROPIC_API_KEY=""   # Important: must be explicitly empty
```

After saving, restart your terminal so the changes take effect.

{% hint style="warning" %}
Do not put these values in a project-level `.env` file. The native Claude Code installer does not read standard `.env` files.
{% endhint %}

#### 3. Clear any cached Anthropic login

If you were previously logged in to Claude Code with an Anthropic account, run `/logout` once to remove the cached session. Then quit and relaunch `claude`. A leftover cached login together with `ANTHROPIC_AUTH_TOKEN` can cause confusing model-not-found errors on startup.

```
> /logout
```

If you have never logged in to Claude Code with Anthropic, skip this step.

#### 4. Start your session

```bash
cd /path/to/your/project
claude
```

You are now connected. Every prompt is routed through nexos.ai.

#### 5. Verify

Run `/status` inside Claude Code to confirm the connection:

```
> /status
Auth token: ANTHROPIC_AUTH_TOKEN
Anthropic base URL: https://api.nexos.ai
```

### Configuring models

Claude Code uses several environment variables to decide which model to use for each task. Point each role at any model available in your nexos.ai workspace. Use either the model UUID or model name.

```bash
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-1-20250805"
export ANTHROPIC_DEFAULT_SONNET_MODEL="anthropic.claude-sonnet-4@20250514"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="c958982f-4301-4576-bfd8-b5a83f1f4232"
export CLAUDE_CODE_SUBAGENT_MODEL="claude-opus-4-1-20250805"
```

| Variable                         | Description                                                |
| -------------------------------- | ---------------------------------------------------------- |
| `ANTHROPIC_DEFAULT_OPUS_MODEL`   | Model used for Opus-class tasks such as complex reasoning  |
| `ANTHROPIC_DEFAULT_SONNET_MODEL` | Model used for Sonnet-class tasks such as general coding   |
| `ANTHROPIC_DEFAULT_HAIKU_MODEL`  | Model used for Haiku-class tasks such as quick completions |
| `CLAUDE_CODE_SUBAGENT_MODEL`     | Model used for sub-agent tasks spawned by Claude Code      |

Add these to the same shell profile where you set `ANTHROPIC_BASE_URL` and `ANTHROPIC_AUTH_TOKEN`. Claude Code is optimized for Anthropic models and may not behave correctly with other providers.

### Troubleshooting

* **Model-not-found errors:** Usually this is a credential conflict. If you have a cached Anthropic OAuth login, run `/logout`, then quit and relaunch `claude`. If your shell still has a real `ANTHROPIC_API_KEY` set, `/logout` will not help. Make sure `ANTHROPIC_API_KEY=""` is set as shown above and restart your terminal. Verify with `/status`.
* **Auth errors:** Ensure `ANTHROPIC_API_KEY` is set to an empty string `""`. If it is unset, Claude Code may fall back to authenticating against Anthropic's servers.
* **Context length errors:** Break the task into smaller chunks or start a new session.


---

# 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.nexos.ai/gateway-api/integrations/claude-code.md?ask=<question>&goal=<endgoal>
```

`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.