Documentation 2026-01-11 18:02 UTC to 2026-01-12 21:02 UTC

77 before_script:77 before_script:

78 - apk update78 - apk update

79 - apk add --no-cache git curl bash79 - apk add --no-cache git curl bash

80 - npm install -g @anthropic-ai/claude-code80 - curl -fsSL https://claude.ai/install.sh | bash

81 script:81 script:

82 # Optional: start a GitLab MCP server if your setup provides one82 # Optional: start a GitLab MCP server if your setup provides one

83 - /bin/gitlab-mcp-server || true83 - /bin/gitlab-mcp-server || true

255 before_script:255 before_script:

256 - apk update256 - apk update

257 - apk add --no-cache git curl bash257 - apk add --no-cache git curl bash

258 - npm install -g @anthropic-ai/claude-code258 - curl -fsSL https://claude.ai/install.sh | bash

259 script:259 script:

260 - /bin/gitlab-mcp-server || true260 - /bin/gitlab-mcp-server || true

261 - >261 - >

289 before_script:289 before_script:

290 - apk add --no-cache bash curl jq git python3 py3-pip290 - apk add --no-cache bash curl jq git python3 py3-pip

291 - pip install --no-cache-dir awscli291 - pip install --no-cache-dir awscli

292 - npm install -g @anthropic-ai/claude-code292 - curl -fsSL https://claude.ai/install.sh | bash

293 # Exchange GitLab OIDC token for AWS credentials293 # Exchange GitLab OIDC token for AWS credentials

294 - export AWS_WEB_IDENTITY_TOKEN_FILE="${CI_JOB_JWT_FILE:-/tmp/oidc_token}"294 - export AWS_WEB_IDENTITY_TOKEN_FILE="${CI_JOB_JWT_FILE:-/tmp/oidc_token}"

295 - if [ -n "${CI_JOB_JWT_V2}" ]; then printf "%s" "$CI_JOB_JWT_V2" > "$AWS_WEB_IDENTITY_TOKEN_FILE"; fi295 - if [ -n "${CI_JOB_JWT_V2}" ]; then printf "%s" "$CI_JOB_JWT_V2" > "$AWS_WEB_IDENTITY_TOKEN_FILE"; fi

339 rules:339 rules:

340 - if: '$CI_PIPELINE_SOURCE == "web"'340 - if: '$CI_PIPELINE_SOURCE == "web"'

341 before_script:341 before_script:

342 - apt-get update && apt-get install -y git nodejs npm && apt-get clean342 - apt-get update && apt-get install -y git && apt-get clean

343 - npm install -g @anthropic-ai/claude-code343 - curl -fsSL https://claude.ai/install.sh | bash

344 # Authenticate to Google Cloud via WIF (no downloaded keys)344 # Authenticate to Google Cloud via WIF (no downloaded keys)

345 - >345 - >

346 gcloud auth login --cred-file=<(cat <<EOF346 gcloud auth login --cred-file=<(cat <<EOF

191* Background tasks have unique IDs for tracking and output retrieval191* Background tasks have unique IDs for tracking and output retrieval

192* Background tasks are automatically cleaned up when Claude Code exits192* Background tasks are automatically cleaned up when Claude Code exits

193 193 

194To disable all background task functionality, set the `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` environment variable to `1`. See [Environment variables](/en/settings#environment-variables) for details.

195 

194**Common backgrounded commands:**196**Common backgrounded commands:**

195 197 

196* Build tools (webpack, vite, make)198* Build tools (webpack, vite, make)

39 ```39 ```

40 </Tab>40 </Tab>

41 41 

42 <Tab title="NPM">42 <Tab title="WinGet">

43 If you have [Node.js 18 or newer installed](https://nodejs.org/en/download/):43 ```powershell theme={null}

44 44 winget install Anthropic.ClaudeCode

45 ```sh theme={null}

46 npm install -g @anthropic-ai/claude-code

47 ```45 ```

48 </Tab>46 </Tab>

49</Tabs>47</Tabs>

322/plugin marketplace add https://gitlab.com/company/plugins.git322/plugin marketplace add https://gitlab.com/company/plugins.git

323```323```

324 324 

325### Private repositories

326 

327Claude Code supports installing plugins from private repositories. Set the appropriate authentication token in your environment, and Claude Code will use it when authentication is required.

328 

329| Provider | Environment variables | Notes |

330| :-------- | :--------------------------- | :---------------------------------------- |

331| GitHub | `GITHUB_TOKEN` or `GH_TOKEN` | Personal access token or GitHub App token |

332| GitLab | `GITLAB_TOKEN` or `GL_TOKEN` | Personal access token or project token |

333| Bitbucket | `BITBUCKET_TOKEN` | App password or repository access token |

334 

335Set the token in your shell configuration (for example, `.bashrc`, `.zshrc`) or pass it when running Claude Code:

336 

337```bash theme={null}

338export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

339```

340 

341Authentication tokens are only used when a repository requires authentication. Public repositories work without any tokens configured, even if tokens are present in your environment.

342 

343<Note>

344 For CI/CD environments, configure the token as a secret environment variable. GitHub Actions automatically provides `GITHUB_TOKEN` for repositories in the same organization.

345</Note>

346 

325### Test locally before distribution347### Test locally before distribution

326 348 

327Test your marketplace locally before sharing:349Test your marketplace locally before sharing:

491* For GitHub sources, ensure repositories are public or you have access513* For GitHub sources, ensure repositories are public or you have access

492* Test plugin sources manually by cloning/downloading514* Test plugin sources manually by cloning/downloading

493 515 

516### Private repository authentication fails

517 

518**Symptoms**: Authentication errors when installing plugins from private repositories, even with tokens configured

519 

520**Solutions**:

521 

522* Verify your token is set in the current shell session: `echo $GITHUB_TOKEN`

523* Check that the token has the required permissions (read access to the repository)

524* For GitHub, ensure the token has the `repo` scope for private repositories

525* For GitLab, ensure the token has at least `read_repository` scope

526* Verify the token hasn't expired

527* If using multiple git providers, ensure you've set the token for the correct provider

528 

494### Plugins with relative paths fail in URL-based marketplaces529### Plugins with relative paths fail in URL-based marketplaces

495 530 

496**Symptoms**: Added a marketplace via URL (such as `https://example.com/marketplace.json`), but plugins with relative path sources like `"./plugins/my-plugin"` fail to install with "path not found" errors.531**Symptoms**: Added a marketplace via URL (such as `https://example.com/marketplace.json`), but plugins with relative path sources like `"./plugins/my-plugin"` fail to install with "path not found" errors.

43 ```43 ```

44 </Tab>44 </Tab>

45 45 

46 <Tab title="NPM">46 <Tab title="WinGet">

47 If you have [Node.js 18 or newer installed](https://nodejs.org/en/download/):47 ```powershell theme={null}

48 48 winget install Anthropic.ClaudeCode

49 ```sh theme={null}

50 npm install -g @anthropic-ai/claude-code

51 ```49 ```

52 </Tab>50 </Tab>

53</Tabs>51</Tabs>

692| `CLAUDE_CODE_CLIENT_KEY_PASSPHRASE` | Passphrase for encrypted CLAUDE\_CODE\_CLIENT\_KEY (optional) |692| `CLAUDE_CODE_CLIENT_KEY_PASSPHRASE` | Passphrase for encrypted CLAUDE\_CODE\_CLIENT\_KEY (optional) |

693| `CLAUDE_CODE_CLIENT_KEY` | Path to client private key file for mTLS authentication |693| `CLAUDE_CODE_CLIENT_KEY` | Path to client private key file for mTLS authentication |

694| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | Set to `1` to disable Anthropic API-specific `anthropic-beta` headers. Use this if experiencing issues like "Unexpected value(s) for the `anthropic-beta` header" when using an LLM gateway with third-party providers |694| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | Set to `1` to disable Anthropic API-specific `anthropic-beta` headers. Use this if experiencing issues like "Unexpected value(s) for the `anthropic-beta` header" when using an LLM gateway with third-party providers |

695| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | Set to `1` to disable all background task functionality, including the `run_in_background` parameter on Bash and subagent tools, auto-backgrounding, and the Ctrl+B shortcut |

695| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | Equivalent of setting `DISABLE_AUTOUPDATER`, `DISABLE_BUG_COMMAND`, `DISABLE_ERROR_REPORTING`, and `DISABLE_TELEMETRY` |696| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | Equivalent of setting `DISABLE_AUTOUPDATER`, `DISABLE_BUG_COMMAND`, `DISABLE_ERROR_REPORTING`, and `DISABLE_TELEMETRY` |

696| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | Set to `1` to disable automatic terminal title updates based on conversation context |697| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | Set to `1` to disable automatic terminal title updates based on conversation context |

697| `CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS` | Override the default token limit for file reads. Useful when you need to read larger files in full |698| `CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS` | Override the default token limit for file reads. Useful when you need to read larger files in full |

6 6 

7* **Operating Systems**: macOS 10.15+, Ubuntu 20.04+/Debian 10+, or Windows 10+ (with WSL 1, WSL 2, or Git for Windows)7* **Operating Systems**: macOS 10.15+, Ubuntu 20.04+/Debian 10+, or Windows 10+ (with WSL 1, WSL 2, or Git for Windows)

8* **Hardware**: 4 GB+ RAM8* **Hardware**: 4 GB+ RAM

9* **Software**: [Node.js 18+](https://nodejs.org/en/download) (only required for npm installation)9* **Network**: Internet connection required (see [network configuration](/en/network-config#network-access-requirements))

10* **Network**: Internet connection required for authentication and AI processing10* **Shell**: Works best in Bash or Zsh

11* **Shell**: Works best in Bash, Zsh or Fish

12* **Location**: [Anthropic supported countries](https://www.anthropic.com/supported-countries)11* **Location**: [Anthropic supported countries](https://www.anthropic.com/supported-countries)

13 12 

14### Additional dependencies13### Additional dependencies

15 14 

16* **ripgrep**: Usually included with Claude Code. If search fails, see [search troubleshooting](/en/troubleshooting#search-and-discovery-issues).15* **ripgrep**: Usually included with Claude Code. If search fails, see [search troubleshooting](/en/troubleshooting#search-and-discovery-issues).

16* **[Node.js 18+](https://nodejs.org/en/download)**: Only required for [deprecated npm installation](#npm-installation-deprecated)

17 17 

18## Standard installation18## Installation

19 19 

20To install Claude Code, use one of the following methods:20To install Claude Code, use one of the following methods:

21 21 

46 ```46 ```

47 </Tab>47 </Tab>

48 48 

49 <Tab title="NPM">49 <Tab title="WinGet">

50 If you have [Node.js 18 or newer installed](https://nodejs.org/en/download/):50 ```powershell theme={null}

51 51 winget install Anthropic.ClaudeCode

52 ```sh theme={null}

53 npm install -g @anthropic-ai/claude-code

54 ```52 ```

55 </Tab>53 </Tab>

56</Tabs>54</Tabs>

57 55 

58<Note>

59 Some users may be automatically migrated to an improved installation method.

60</Note>

61 

62After the installation process completes, navigate to your project and start Claude Code:56After the installation process completes, navigate to your project and start Claude Code:

63 57 

64```bash theme={null}58```bash theme={null}

66claude60claude

67```61```

68 62 

69## Windows setup63If you encounter any issues during installation, consult the [troubleshooting guide](/en/troubleshooting).

70 

71**Option 1: Claude Code within WSL**

72 

73* Both WSL 1 and WSL 2 are supported

74 

75**Option 2: Claude Code on native Windows with Git Bash**

76 

77* Requires [Git for Windows](https://git-scm.com/downloads/win)

78* For portable Git installations, specify the path to your `bash.exe`:

79 ```powershell theme={null}

80 $env:CLAUDE_CODE_GIT_BASH_PATH="C:\Program Files\Git\bin\bash.exe"

81 ```

82 

83## Alternative installation methods

84 

85Claude Code offers multiple installation methods to suit different environments.

86 

87If you encounter any issues during installation, consult the [troubleshooting guide](/en/troubleshooting#linux-permission-issues).

88 64 

89<Tip>65<Tip>

90 Run `claude doctor` after installation to check your installation type and version.66 Run `claude doctor` after installation to check your installation type and version.

91</Tip>67</Tip>

92 68 

93### Native installation options69<Note>

70 **Alpine Linux and other musl/uClibc-based distributions**: The native installer requires `libgcc`, `libstdc++`, and `ripgrep`. For Alpine: `apk add libgcc libstdc++ ripgrep`. Set `USE_BUILTIN_RIPGREP=0`.

71</Note>

94 72 

95The native installation is the recommended method and offers several benefits:73### Authentication

96 74 

97* One self-contained executable75#### For individuals

98* No Node.js dependency

99* Improved auto-updater stability

100 76 

101If you have an existing installation of Claude Code, use `claude install` to migrate to the native binary installation.771. **Claude Pro or Max plan** (recommended): Subscribe to Claude's [Pro or Max plan](https://claude.ai/pricing) for a unified subscription that includes both Claude Code and Claude on the web. Manage your account in one place and log in with your Claude.ai account.

782. **Claude Console**: Connect through the [Claude Console](https://console.anthropic.com) and complete the OAuth process. Requires active billing in the Anthropic Console. A "Claude Code" workspace is automatically created for usage tracking and cost management. You can't create API keys for the Claude Code workspace; it's dedicated exclusively for Claude Code usage.

102 79 

103For advanced installation options with the native installer:80#### For teams and organizations

81 

821. **Claude for Teams or Enterprise** (recommended): Subscribe to [Claude for Teams](https://claude.com/pricing#team-&-enterprise) or [Claude for Enterprise](https://anthropic.com/contact-sales) for centralized billing, team management, and access to both Claude Code and Claude on the web. Team members log in with their Claude.ai accounts.

832. **Claude Console with team billing**: Set up a shared [Claude Console](https://console.anthropic.com) organization with team billing. Invite team members and assign roles for usage tracking.

843. **Cloud providers**: Configure Claude Code to use [Amazon Bedrock, Google Vertex AI, or Microsoft Foundry](/en/third-party-integrations) for deployments with your existing cloud infrastructure.

85 

86### Install a specific version

87 

88To install a specific version of Claude Code with the native installer:

104 89 

105**macOS, Linux, WSL:**90**macOS, Linux, WSL:**

106 91 

115curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58100curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

116```101```

117 102 

118<Note>

119 **Alpine Linux and other musl/uClibc-based distributions**: The native build requires `libgcc`, `libstdc++`, and `ripgrep`. For Alpine: `apk add libgcc libstdc++ ripgrep`. Set `USE_BUILTIN_RIPGREP=0`.

120</Note>

121 

122**Windows PowerShell:**103**Windows PowerShell:**

123 104 

124```powershell theme={null}105```powershell theme={null}

145curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd 1.0.58 && del install.cmd126curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd 1.0.58 && del install.cmd

146```127```

147 128 

148<Tip>129### Binary integrity and code signing

149 Make sure that you remove any outdated aliases or symlinks before installing.

150</Tip>

151 

152**Binary integrity and code signing**

153 130 

154* SHA256 checksums for all platforms are published in the release manifests, currently located at `https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases/{VERSION}/manifest.json` (example: replace `{VERSION}` with `2.0.30`)131* SHA256 checksums for all platforms are published in the release manifests, currently located at `https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases/{VERSION}/manifest.json` (example: replace `{VERSION}` with `2.0.30`)

155* Signed binaries are distributed for the following platforms:132* Signed binaries are distributed for the following platforms:

156 * macOS: Signed by "Anthropic PBC" and notarized by Apple133 * macOS: Signed by "Anthropic PBC" and notarized by Apple

157 * Windows: Signed by "Anthropic, PBC"134 * Windows: Signed by "Anthropic, PBC"

158 135 

159### NPM installation136## NPM installation (deprecated)

160 137 

161For environments where NPM is preferred or required:138NPM installation is deprecated. Use the [native installation](#installation) method when possible. To migrate an existing npm installation to native, run `claude install`.

139 

140**Global npm installation**

162 141 

163```sh theme={null}142```sh theme={null}

164npm install -g @anthropic-ai/claude-code143npm install -g @anthropic-ai/claude-code

169 If you encounter permission errors, see [configure Claude Code](/en/troubleshooting#linux-permission-issues) for recommended solutions.148 If you encounter permission errors, see [configure Claude Code](/en/troubleshooting#linux-permission-issues) for recommended solutions.

170</Warning>149</Warning>

171 150 

172## Authentication options151## Windows setup

173 

174### For individuals

175 

1761. **Claude Pro or Max plan** (recommended): Subscribe to Claude's [Pro or Max plan](https://claude.ai/pricing) for a unified subscription that includes both Claude Code and Claude on the web. Manage your account in one place and log in with your Claude.ai account.

1772. **Claude Console**: Connect through the [Claude Console](https://console.anthropic.com) and complete the OAuth process. Requires active billing in the Anthropic Console. A "Claude Code" workspace is automatically created for usage tracking and cost management. You can't create API keys for the Claude Code workspace; it's dedicated exclusively for Claude Code usage.

178 

179### For teams and organizations

180 

1811. **Claude for Teams or Enterprise** (recommended): Subscribe to [Claude for Teams](https://claude.com/pricing#team-&-enterprise) or [Claude for Enterprise](https://anthropic.com/contact-sales) for centralized billing, team management, and access to both Claude Code and Claude on the web. Team members log in with their Claude.ai accounts.

1822. **Claude Console with team billing**: Set up a shared [Claude Console](https://console.anthropic.com) organization with team billing. Invite team members and assign roles for usage tracking.

1833. **Cloud providers**: Configure Claude Code to use [Amazon Bedrock, Google Vertex AI, or Microsoft Foundry](/en/third-party-integrations) for deployments with your existing cloud infrastructure.

184 152 

185<Note>153**Option 1: Claude Code within WSL**

186 Claude Code securely stores your credentials. See [Credential Management](/en/iam#credential-management) for details.

187</Note>

188 154 

189## Running on AWS or GCP155* Both WSL 1 and WSL 2 are supported

190 156 

191By default, Claude Code uses the Claude API.157**Option 2: Claude Code on native Windows with Git Bash**

192 158 

193For details on running Claude Code on AWS or GCP, see [third-party integrations](/en/third-party-integrations).159* Requires [Git for Windows](https://git-scm.com/downloads/win)

160* For portable Git installations, specify the path to your `bash.exe`:

161 ```powershell theme={null}

162 $env:CLAUDE_CODE_GIT_BASH_PATH="C:\Program Files\Git\bin\bash.exe"

163 ```

194 164 

195## Update Claude Code165## Update Claude Code

196 166 

203* **Notifications**: You'll see a notification when updates are installed173* **Notifications**: You'll see a notification when updates are installed

204* **Applying updates**: Updates take effect the next time you start Claude Code174* **Applying updates**: Updates take effect the next time you start Claude Code

205 175 

176<Note>

177 Homebrew and WinGet installations do not auto-update. Use `brew upgrade claude-code` or `winget upgrade Anthropic.ClaudeCode` to update manually.

178 

179 **Known issue:** Claude Code may notify you of updates before the new version is available in these package managers. If an upgrade fails, wait and try again later.

180</Note>

181 

206**Disable auto-updates:**182**Disable auto-updates:**

207 183 

208Set the `DISABLE_AUTOUPDATER` environment variable in your shell or [settings.json file](/en/settings):184Set the `DISABLE_AUTOUPDATER` environment variable in your shell or [settings.json file](/en/settings):

252brew uninstall --cask claude-code228brew uninstall --cask claude-code

253```229```

254 230 

231### WinGet installation

232 

233```powershell theme={null}

234winget uninstall Anthropic.ClaudeCode

235```

236 

255### NPM installation237### NPM installation

256 238 

257```bash theme={null}239```bash theme={null}

206| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------- |206| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------- |

207| `allowed-tools` | List of tools the command can use | Inherits from the conversation |207| `allowed-tools` | List of tools the command can use | Inherits from the conversation |

208| `argument-hint` | The arguments expected for the slash command. Example: `argument-hint: add [tagId] \| remove [tagId] \| list`. This hint is shown to the user when auto-completing the slash command. | None |208| `argument-hint` | The arguments expected for the slash command. Example: `argument-hint: add [tagId] \| remove [tagId] \| list`. This hint is shown to the user when auto-completing the slash command. | None |

209| `context` | Set to `fork` to run the command in a forked sub-agent context with its own conversation history. | Inline (no fork) |

210| `agent` | Specify which [agent type](/en/sub-agents#built-in-subagents) to use when `context: fork` is set. Only applicable when combined with `context: fork`. | `general-purpose` |

209| `description` | Brief description of the command | Uses the first line from the prompt |211| `description` | Brief description of the command | Uses the first line from the prompt |

210| `model` | Specific model string (see [Models overview](https://docs.claude.com/en/docs/about-claude/models/overview)) | Inherits from the conversation |212| `model` | Specific model string (see [Models overview](https://docs.claude.com/en/docs/about-claude/models/overview)) | Inherits from the conversation |

211| `disable-model-invocation` | Whether to prevent the `Skill` tool from calling this command | false |213| `disable-model-invocation` | Whether to prevent the `Skill` tool from calling this command | false |

382## `Skill` tool384## `Skill` tool

383 385 

384<Note>386<Note>

385 In earlier versions of Claude Code, slash command invocation was provided by a separate `SlashCommand` tool. This has been merged into the `Skill` tool. If you have existing permission rules using `SlashCommand`, update them to use `Skill`.387 In earlier versions of Claude Code, slash command invocation was provided by a separate `SlashCommand` tool. This has been merged into the `Skill` tool.

386</Note>388</Note>

387 389 

388The `Skill` tool allows Claude to programmatically invoke both [custom slash commands](/en/slash-commands#custom-slash-commands) and [Agent Skills](/en/skills) during a conversation. This gives Claude the ability to use these capabilities on your behalf when appropriate.390The `Skill` tool allows Claude to programmatically invoke both [custom slash commands](/en/slash-commands#custom-slash-commands) and [Agent Skills](/en/skills) during a conversation. This gives Claude the ability to use these capabilities on your behalf when appropriate.

433 435 

434The permission rules support:436The permission rules support:

435 437 

436* **Exact match**: `Skill(/commit)` (allows only `/commit` with no arguments)438* **Exact match**: `Skill(commit)` (allows only `commit` with no arguments)

437* **Prefix match**: `Skill(/review-pr:*)` (allows `/review-pr` with any arguments)439* **Prefix match**: `Skill(review-pr:*)` (allows `review-pr` with any arguments)

438 440 

439### Character budget limit441### Character budget limit

440 442 

414* Ask Claude to "run this in the background"414* Ask Claude to "run this in the background"

415* Press **Ctrl+B** to background a running task415* Press **Ctrl+B** to background a running task

416 416 

417To disable all background task functionality, set the `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` environment variable to `1`. See [Environment variables](/en/settings#environment-variables).

418 

417### Common patterns419### Common patterns

418 420 

419#### Isolate high-volume operations421#### Isolate high-volume operations