Версия Claude Code на момент написания: 2.1.105+

У нас в команде AWS 9 человек: решения в AWS, 150+ аккаунтов в AWS Organizations. Один из нас работает на macOS, шестеро на Linux, двое на Windows (включая меня).

За год работы с Claude Code выработались правила: как поставить и что настроить. Правила менялись по мере выхода новых версий: появлялись новые возможности, отваливались старые костыли. Этот документ отражает актуальное состояние на апрель 2026.

На Linux не пересаживаюсь намеренно. Мои Windows-компетенции в команде востребованы: я единственный, кто имеет солидный опыт с Microsoft, кто отладит Lambda-парсер для обработки Windows Events, кто напишет и будет поддерживать большой PowerShell скрипт или SSM-документ с ним.

Claude Code у меня под Windows должен работать без ошибок и с максимально возможной производительностью, несмотря на то, что большую часть времени я работаю на linux-специфичное окружение.

Обычная установка

Установка прямо в Windows — правильный выбор в случаях, когда:

• Нужно просто попробовать Code на Windows, без сложной настройки окружения

• Задача на .NET, WPF, WinForms — всё завязано на Windows API, WMI, реестр

• Работа только с PowerShell скриптами, DSC-конфигурациями или SSM-документами с PowerShell

• Azure, различные корпоративные Windows-инструменты

• Либо нужно поймать баг, который воспроизводится только на Windows платформе

У чистой Windows установки есть ограничения — они разобраны в конце этого раздела.

Claude Code использует Git Bash для запуска команд в терминале — без него установщик откажет (но обычно git уже установлен):

winget install Git.Git

Если даже winget отсутствует — надо скачать Git с https://git-scm.com/install/windows. При установке — все галочки по умолчанию: Git Bash, интеграция с Explorer, добавление в PATH.

В Windows уже идет с powershell.exe — это Windows PowerShell 5.1, построенный на .NET Framework. Последний релиз был в 2017 году; развитие остановлено. pwsh — это PowerShell 7+: open-source, кросс-платформенный, на .NET Core. Именно его Microsoft развивает и рекомендует для новых проектов. Устанавливается отдельно, перезагрузки после установки не требует, сосуществует с 5.1 без конфликтов:

winget install Microsoft.PowerShell

Для PowerShell 7+ надо запускать pwsh, а не powershell. Все дальнейшие команды рассчитаны на pwsh. Очень рекомендую Windows Terminal (но это дело вкуса) — в соседних табах работают и powershell и linux.

Установка Claude Code:

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

Установщик скачает бинарник, пропишет PATH, настроит автообновление. Node.js и npm не нужны. Альтернативный способ — через WinGet: winget install Anthropic.ClaudeCode (но тогда надо будет обновлять Claude Code вручную, через winget upgrade).

При необходимости можно указать версию:

# Стабильная версия
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) stable

# Конкретная версия
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 2.1.105

Проверка:

claude --version   # 2.1.105 (Claude Code)
claude update      # если нужно обновиться
claude doctor      # полная диагностика

Если claude не находится — установщик не прописал PATH или консоль не перезапущена. Исправляется вручную:

# Добавить в текущую сессию
$env:PATH += ";$env:USERPROFILE\.local\bin"

# Сохранить навсегда — читать только User PATH, не смешивать с System
$userPath = [Environment]::GetEnvironmentVariable("PATH", "User")
[Environment]::SetEnvironmentVariable("PATH", `
  "$userPath;$env:USERPROFILE\.local\bin", `
  "User")

Бесплатный план Claude не включает Claude Code. Нужен один из:

• Claude Pro или Max — личная подписка на claude.ai

• Claude for Teams или Enterprise — корпоративный аккаунт

• Claude Console — аккаунт разработчика с API-биллингом

• Amazon Bedrock, Google Vertex AI, Microsoft Foundry — через инфраструктуру облачного провайдера

• В России в 2026 официально недоступен, но есть варианты

Большинству пользователей API-ключ не нужен. Запустить claude — откроется браузер, войти с аккаунтом claude.ai. Если браузер не открывается — в терминале нажать c, URL скопируется в буфер обмена. Вставить в браузер, войти, скопировать полученный код обратно в терминал.

API-ключ нужен только при работе через Console (API-биллинг вместо подписки). Задаётся через /config или переменной окружения:

[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-api03-...", "User")

Важно: если ANTHROPIC_API_KEY задан, он имеет приоритет над подпиской. Если ключ устарел или отозван — аутентификация сломается. Проверить активный метод аутентификации: команда /status внутри Claude Code.

По умолчанию Claude Code выполняет команды через Git Bash. Для PowerShell-проектов это неудобно: переменные $_, $?, конвейеры — всё ломается. Начиная с версии 2.1.84 есть решение — добавить настройки в файл %USERPROFILE%\.claude\settings.json:

{
  "env": {
    "CLAUDE_CODE_USE_POWERSHELL_TOOL": "1",
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  },
  "defaultShell": "powershell"
}

Две разных настройки делают разные вещи:

• CLAUDE_CODE_USE_POWERSHELL_TOOL=1 регистрирует PowerShell как отдельный инструмент наряду с Bash. Claude Code автоматически определит pwsh.exe (7+); при его отсутствии — проверит наличие powershell.exe (5.1).

• "defaultShell": "powershell" направляет интерактивные ! команды Claude Code через PowerShell. Работает только при настройках выше.

Git Bash при этом остаётся обязательным — Claude Code использует его для собственного запуска. Если Git установлен не в Program Files, надо указать реальный путь в CLAUDE_CODE_GIT_BASH_PATH.

Для глобальных инструкций надо записать в %USERPROFILE%\.claude\CLAUDE.mdпримерно такое:

# Environment
- OS: Windows 11, PowerShell 7+
- Shell: pwsh (PowerShell Core)

# File paths
- Use Windows paths: C:\Users\<user>\projects\...
- Do NOT use Unix paths (/c/Users/...) or ~ shortcuts

# Available tools
- Use pwsh for PowerShell commands
- Use gh for GitHub operations
- Use aws CLI for AWS operations

# Conventions
- Projects are in C:\Users\<user>\projects\

Claude Code написан под POSIX-окружение. Пути к файлам, shell-команды, IPC между процессами, хуки — всё это по умолчанию предполагает Unix. На нативном Windows часть этого работает через прослойки и эмуляцию, часть не работает совсем.

По умолчанию Claude Code выполняет команды через Git Bash — даже если запущен из PowerShell или CMD. Git Bash. Это MinGW-порт bash, адаптация под Windows, у которой:

• нет полной поддержки extglob (расширенный синтаксис паттернов для сопоставления имён файлов в bash. Включается командой shopt -s extglob. Стандартный glob знает только *,?,[abc]. extglob добавляет +,@,!. Например, удалить всё кроме .js файлов: rm !(*.js).

• переменные $_, $?, $! ведут себя иначе, чем в настоящем bash (подробнее ниже)

• нет systemd, cron, inotify

• нет управления процессами и приложениями Windows. В Linux kill -HUP заставляет nginx перечитать конфиг без перезапуска: мастер-процесс проверяет синтаксис, поднимает новые воркеры и плавно завершает старые. Для ротации логов nginx использует другой сигнал — SIGUSR1 (закрыть и переоткрыть дескрипторы файлов). SIGUSR1 с этой целью применяют также MongoDB, MySQL и ряд других демонов — это устойчивое соглашение в Unix-экосистеме, хотя и не формальный стандарт POSIX: некоторые программы для тех же целей используют SIGHUP. В Git Bash сигналы до Windows процессов не доходят, потому, что Windows не имеет поддержки POSIX-сигналов на уровне ядра.

Насчет переменных типа $_ : когда Claude Code пытается выполнить PowerShell-команды через Git Bash, bash перехватывает и раскрывает переменные до того, как PowerShell их получает:

# Claude пытается выполнить:
Get-Service | Where-Object {$_.Status -ne 'Running'}

# Bash раскрывает $_ как свою переменную.
# PowerShell получает уже сломанную строку:
# "extglob.Status is not recognized as cmdlet..."

Claude Code не распознавал эту ошибку как признак неправильного окружения и повторял тот же сломанный запрос по кругу. В версии 2.1.84 (наконец!) добавили opt-in PowerShell-инструмент — он включён в settings.json выше.

Shell integration, хуки для bash и zsh, которые дают возможность Claude Code видеть текущую директорию и exit code команд в реальном времени, на Windows недоступна. Переменные окружения, заданные в одной команде, не переживают следующую: каждый вызов инструмента, это новый процесс. Для постоянных переменных надо определить SetEnvironmentVariable или settings.json.

Claude Code на Windows ожидает Windows-пути с обратными слэшами. Инструменты Read, Edit, Write не понимают Unix-пути вида /c/Users/... или ~/projects:

# работает
C:\Users\<user>\projects\my-app\src\main.ts

# не работает
/c/Users/<user>/projects/my-app/src/main.ts
~/projects/my-app/src/main.ts

С файловой системой — своя история:

Нечувствительность к регистру — это, мягко говоря, неудобство. Claude Code создаёт путь в неправильном регистре, NTFS молча принимает его как тот же файл, затем Claude Code удаляет «дубликат», и вместе с ним оригинал.

C переносами строк в Windows отдельный головняк. Windows использует CRLF (\r\n), Linux — LF (\n). Bash-скрипт, созданный Claude Code в Windows, может оказаться с \r (если не используется специальный редактор) в конце каждой строки:

# Скрипт выглядит нормально в редакторе, но при запуске:

# cleanup-check.sh: line 2: $'\r': command not found

Суть проблемы не в самих окончаниях строк, а в том, что Claude Code не применяет правила из CLAUDE.md последовательно между вызовами инструментов. Частичные фиксы выходили в v2.1.88-89, проблема до конца не решена. Под Windows мне приходится подменять переносы строк функцией на лету, иначе AWS не выполняет .sh файл с \r\n переносами строк.

MCP использует Unix domain sockets для IPC. На Windows их эквивалент — Named Pipes, но это другой API с другой логикой обнаружения. getSocketPaths() возвращает только Unix-пути вида /tmp/... и никогда не включает путь Named Pipe. Клиент пробует найти сокет, не находит, и не пытается переключиться на Named Pipes. Соединение не устанавливается без каких-либо явных ошибок.

Отдельная проблема возникает, если MCP-сервер внутри использует /home/user или os.tmpdir() и не учитывает Windows. Такой MCP-сервер крашнется при попытке создать файл. На Unix os.tmpdir() возвращает /tmp, на Windows — C:\Users\...\AppData\Local\Temp, и многие MCP-серверы это не обрабатывают.

Решение — заворачивать команды в cmd /c. Это позволяет запустить npx и другие Node-инструменты, но не решает проблему MCP серверов с Unix-путями в их коде:

{
  "mcpServers": {
    "filesystem": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "C:/Projects"]
    }
  }
}

C:/Projects - не ошибка. Пути в JSON-конфиге работают и C:\\Projects (двойной обратный слэш), и C:/Projects (прямой слеш). Одиночный обратный слеш (\) сломает JSON-парсер. MCP серверы с прошитыми Unix-путями (/tmp, /home), на Windows не запустятся.

Sandboxing — это изоляция Claude Code на уровне ядра ОС: ограничивает доступ к файлам и сети для всех дочерних процессов, включая terraform, kubectl, npm.

На Windows Claude Code работает с полными правами текущего пользователя и есть риск изменения или удаления файлов вне разрешённой папки.

Если эти ограничения критичны — в следующем разделе дальше разобран альтернативный подход.

Claude Code в WSL2

WSL2, Windows Subsystem for Linux 2 — встроенный в Windows 10/11 слой совместимости, который запускает настоящее Linux-ядро внутри лёгкой виртуальной машины. Не эмуляцию, и не прослойку типа Git Bash, а именно Linux-ядро, то же самое, что работает на серверах и в Docker-контейнерах.

Для разработчика это означает, что рядом с Windows появляется полноценная Linux-среда: bash, apt, systemd, inotify, Unix-сокеты и всё остальное. Два окружения сосуществуют — файлы открываются из проводника Windows, код выполняется в Linux.

Для Claude Code WSL2 решает все проблемы нативной установки, описанные выше:

• Git Bash заменяется реальным bash — shell integration работает, переменные не перехватываются

• Unix-сокеты доступны — все MCP-серверы подключаются штатно

• bubblewrap доступен — sandboxing включается (нужна установка bubblewrap и socat)

• файловая система Linux (~/projects/) на порядок быстрее NTFS для npm install, ripgrep

• POSIX-права, симлинки, inotify — всё работает без обходных путей

Я использую WSL2 для всего, что связано с Linux-инфраструктурой. PowerShell при этом никуда не девается — он доступен и из WSL, и отдельным окном в Windows Terminal.

Установка из PowerShell с правами администратора:

wsl --install -d Ubuntu-24.04

Команда устанавливает WSL2 и дистрибутив Ubuntu 24.04. wsl --install ставит Ubuntu по умолчанию, но лучше указать версию явно. После установки — перезагрузка. При первом запуске Ubuntu попросит создать суперпользователя и пароль.

Если WSL уже был установлен, на всякий случай обновляем:

wsl --update

Проверка — какая версия WSL у дистрибутива:

wsl --list --verbose
#   NAME      STATE           VERSION
# * Ubuntu    Running         2

В столбце VERSION должна стоять именно 2. Если стоит 1 — обновить:

wsl --set-version Ubuntu-24.04 2

После изменений надо перезапустить WSL:

wsl --shutdown

Настройки производительности WSL2 пишутся в файл C:\Users\<имя_пользователя>\.wslconfig (создаётся вручную):

[wsl2]

# Память: 50-75% от общей RAM
memory=16GB

# Процессоры: количество логических ядер
processors=8

# Swap
swap=4GB

# Зеркальная сеть (IDE лучше видит localhost)
# ВНИМАНИЕ: ломает Docker Desktop — убрать обе строки если используется Docker Desktop
# dnsTunneling полезен только вместе с mirrored, без него бесполезен
networkingMode=mirrored
dnsTunneling=true

autoProxy=true

[experimental]

# Возврат неиспользуемой памяти Windows
# gradual — плавно, dropCache — агрессивно (режим по умолчанию в новых версиях WSL)
autoMemoryReclaim=gradual

# Экономия места на диске
sparseVhd=true

.wslconfig чувствителен к пробелам — здесь пробелы вокруг = ломают парсинг. Число и единица пишутся слитно: 16GB, не 16 GB.

/etc/wsl.conf — настройки дистрибутива, читаются при каждом старте WSL2. Редактировать надо внутри уже Ubuntu:

sudo nano /etc/wsl.conf

Многие предпочитают редактор vi или vim, но мой выбор — nano; что-то вроде терминального notepad. Дело вкуса и привычки — я работаю в Windows всю свою карьеру.

[boot]

# systemd нужен для служб (ssh, docker без Docker Desktop, snap)
systemd = true

[automount]

# metadata — Linux-права на файлах Windows-дисков (/mnt/c/)
# umask/fmask — права по умолчанию для смонтированных файлов
options = "metadata,umask=22,fmask=11"

После изменения — перезапустить WSL2:

wsl --shutdown

Внутри Ubuntu — надо сразу обновить систему и поставить необходимые пакеты:

sudo apt update && sudo apt upgrade -y

sudo apt install -y \
  build-essential \
  git \
  curl \
  wget \
  unzip \
  gnupg \
  ca-certificates \
  lsb-release \
  ripgrep \
  jq \
  direnv \
  bubblewrap \
  socat

build-essential нужен для компиляции нативных модулей Node.js. ripgrep Claude Code использует для поиска по файлам — лучше иметь системный, не полагаясь на встроенный. direnv — для переменных окружения на уровне проекта. bubblewrap и socat — зависимости sandboxing: без них Claude Code на Linux и WSL2 работает без изоляции файловой системы и сети.

Как работает direnv: при входе в директорию он автоматически загружает .envrc. Удобно для задания ANTHROPIC_API_KEY, AWS_ACCOUNT, различных токенов и других переменных под конкретный проект и приложение. Его надо подключить к bash, чтобы запускался при смене директории:

echo 'eval "$(direnv hook bash)"' >> ~/.bashrc
source ~/.bashrc

Пример .envrc в корне проекта:

export ANTHROPIC_API_KEY=sk-ant-...
export AWS_PROFILE=dev
...

Первый раз в директории — разрешить:

direnv allow

Node.js через apt лучше не ставить — там старые версии и проблемы с правами npm. NVM позволяет держать несколько версий и переключаться между ними без sudo. Актуальную версию NVM смотреть на nvm-sh/nvm: Node Version Manager. На момент написания — v0.40.4:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
source ~/.bashrc
nvm install --lts
nvm use --lts
nvm alias default node

node --version
npm --version

Установка Claude Code — установщик не требует Node.js и автообновляется в фоне:

curl -fsSL https://claude.ai/install.sh | bash
export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

Установка через npm install -g @anthropic-ai/claude-code официально устарела — это объявила Anthropic.

Claude Code уже обучен в bash использовать некоторые команды при работе с файлами и процессами. Например:

• bun — замена node/npm: запуск JS/TS, управление пакетами, быстрее npm в 4-25x

• fd — замена find: поиск файлов по имени

• sd — замена sed: замена текста с нормальным синтаксисом регулярок

• gh — GitHub CLI

ripgrep и jq уже установлены выше, через apt install

# Bun — менеджер пакетов и рантайм для JS/TS
curl -fsSL https://bun.sh/install | bash

# fd — на Ubuntu называется fd-find, нужен алиас
sudo apt install -y fd-find
ln -s "$(which fdfind)" ~/.local/bin/fd

# sd — замена sed с синтаксисом регулярок
sudo apt install sd

# gh - GitHub CLI
# В WSL2 браузер не откроется — надо скопировать URL из терминала
sudo apt install -y gh
gh auth login

По умолчанию Claude Code использует встроенную копию ripgrep. Переключить на системный через ~/.claude/settings.json:

{
  "env": {
    "USE_BUILTIN_RIPGREP": "0"
  }
}

~/.claude/CLAUDE.md — правильное место для описания окружения и личных предпочтений. Один раз, для всех проектов:

# Environment
- OS: Ubuntu 24.04 on WSL2 (Windows 11)
- Shell: bash/zsh

# Available CLI Tools
- Use rg (ripgrep) instead of grep — faster, respects .gitignore
- Use fd instead of find
- Use bun instead of npm where possible
- Use jq for JSON processing in shell pipelines
- Use gh for GitHub operations

# Conventions
- Projects are stored in ~/projects/
- Always use Linux paths, not Windows paths (/mnt/c/)

Кстати, для нового проекта CLAUDE.md можно сгенерировать автоматически. Запустить в репозитории:

claude
# внутри claude
/init

Claude проанализирует кодовую базу и создаст .claude/CLAUDE.md с командами сборки, тестирования и найденными конвенциями. Лимит: 200 строк на файл: если файл большой, некоторые правила могут игнорироваться.

Стандартные лимиты Ubuntu слишком малы для больших репозитариев с тысячами файлов. Claude Code и файловые вотчеры (Vite, webpack, TypeScript) упираются в inotify при большом дереве. Определяем большие лимиты:

# inotify — лимиты на файловые вотчеры
# по умолчанию: max_user_watches=8192, max_user_instances=128
sudo tee /etc/sysctl.d/99-wsl.conf > /dev/null <<EOF
fs.inotify.max_user_watches=524288
fs.inotify.max_user_instances=1024
EOF
sudo sysctl -p /etc/sysctl.d/99-wsl.conf

# лимит открытых файлов (по умолчанию 1024 — мало для Node.js)
sudo tee /etc/security/limits.d/99-nofile.conf > /dev/null <<EOF
* soft nofile 65535
* hard nofile 65535
EOF

Изменения sysctl применяются сразу. Лимиты nofile — после перезапуска WSL2 (wsl --shutdown из PowerShell).

Правило одно: проекты и репы держать в Linux-файловой системе, не в /mnt/c/.

# правильно — нативная Linux fs
mkdir -p ~/projects/my-app && cd ~/projects/my-app
claude

# тоже работает, но медленно — /mnt/c/ 
# работает через 9P-мост, для npm install разница в скорости в разы
cd /mnt/c/Users/<user>/projects/my-app
claude

Windows видит Linux-файлы через протокол 9P — это виртуальная сетевая шара, которую WSL2 монтирует автоматически. Читать из Windows Explorer нормально, активно редактировать — медленно. Для разработки оптимальный вариант — VSCode с WSL extension: файлы в Linux, интерфейс на Windows.

\\wsl.localhost\Ubuntu\home\<user>\projects

net use не работает!

9P (Plan 9 Filesystem Protocol) — протокол доступа к файловой системе из Bell Labs. Разработан для ОС Plan 9, где все ресурсы системы (файлы, устройства, сеть) представлены единым файловым деревом. WSL2 использует его в обе стороны: Linux видит Windows-диски через /mnt/c/ — это 9P-сервер на стороне Windows; Windows видит Linux-файлы через \\wsl.localhost\ — 9P-сервер на стороне Linux.

Почему не SMB? SMB проектировался для корпоративных сетей — там есть аутентификация (NTLM, Kerberos) и шифрование. Всё это не нужно для локального IPC внутри одной машины. 9P — протокол без лишних слоёв, идеально подходит для локальной среды. net use — это SMB-клиент; он не поддерживает 9P, поэтому и не работает с WSL-шарами.

Но пространство WSL2 замаппить на диск (например, W:) все-таки можно:

New-PSDrive -Name W -PSProvider FileSystem -Root \\wsl.localhost\Ubuntu\home\<user>\projects

На типичном проекте (10k+ файлов, активный git) разница между нативным Windows и WSL2 ощутима. Цифры ниже приблизительные, не бенчмарки: значения зависят от железа и проекта.

WSL2 с файлами в ~/projects/ в разы быстрее Windows. Причины: NTFS накладывает расходы на антивирусное сканирование каждой операции, Windows Defender сканирует каждый новый файл при npm install, а мелкие файлы (node_modules, .git) — узкое место NTFS.

У меня оба варианта, Claude Code в Windows и в WSL2 с Ubuntu, установлены и настроены (и используются постоянно). В терминале доступны оба одновременно. Часто приходится удачные находки или обновления в скилах и MCP, перебрасывать из одного окружения в другое. Заниматься холиварами контрпродуктивно, лучше выбирать инструмент, подходящий для конкретной задачи.