Przewodnik po Claude Code CLI: instalacja, konfiguracja, polecenia, zmienne środowiskowe

TL;DR: Claude Code to agentowy CLI, który czyta bazę kodu, wykonuje polecenia i modyfikuje pliki przez warstwowy system uprawnień, hooks, integracji MCP i subagents. Opanowanie 5 podstawowych systemów (konfiguracji, uprawnień, hooks, MCP i subagents) odblokowuje produktywność o charakterze mnożnika siły. Należy wybrać poziom modelu dopasowany do zadania — Opus do złożonego rozumowania, Sonnet do pracy ogólnej, Haiku do szybkiej eksploracji — albo ustandaryzować pracę na Opus, jeśli jakość jest jedyną zmienną. Do wszystkiego, co musi wykonywać się zawsze, należy używać hooks (nie promptów). Od v2.1.174–176 (12 czerwca 2026) lista dozwolonych availableModels może teraz ograniczać model Default przez nowe zarządzane ustawienie enforceAvailableModels (ustawienia użytkownika/projektu nie mogą rozszerzyć zarządzanej listy), tytuły sesji są generowane w języku rozmowy (można przypiąć jeden za pomocą ustawienia language), a nowe ustawienia footerLinksRegexes i wheelScrollAccelerationEnabled, okno dialogowe atrybucji VSCode /usage oraz poprawka sprawiająca, że warunki hook if dopasowują wzorce ścieżek Read/Edit/Write, dopełniają wydanie.¹⁷² Od v2.1.173 (11 czerwca 2026) nazwa modelu Fable 5 z sufiksem [1m] jest automatycznie normalizowana/usuwana — Fable 5 już domyślnie zawiera kontekst 1M, więc sufiks jest zbędny (miał znaczenie wyłącznie w Opus/Sonnet). Od v2.1.172 (10 czerwca 2026) sub-agents mogą rekurencyjnie uruchamiać własnych sub-agents, do 5 poziomów głębokości, Bedrock odczytuje region z ~/.aws, gdy AWS_REGION nie jest ustawione (/status pokazuje źródło), /plugin dodaje pasek wyszukiwania marketplace, a metryka OTEL claude_code.lines_of_code.count zyskuje atrybut model. Od v2.1.170 (9 czerwca 2026) Claude Fable 5 — nowy poziom modelu powyżej Opus — można wybrać w Claude Code przez /model fable po claude update (obsługuje pełną skalę wysiłku low–max, ale nie pozwala wyłączyć thinking); Opus 4.8 pozostaje domyślnym modelem agentowym. Od v2.1.169 (8 czerwca 2026) --safe-mode (oraz CLAUDE_CODE_SAFE_MODE) uruchamia czystą sesję z wyłączonymi wszystkimi personalizacjami na potrzeby diagnostyki, /cd przenosi sesję do nowego katalogu roboczego bez naruszania pamięci podręcznej promptu, a disableBundledSkills ukrywa przed modelem wbudowane skills i slash commands. Od v2.1.166 (6 czerwca 2026) ustawienie fallbackModel łączy do 3 modeli zapasowych, gdy model podstawowy jest przeciążony, glob "*" działa w regułach odmowy MCP, a MAX_THINKING_TOKENS=0 / --thinking disabled całkowicie wyłączają thinking w modelach domyślnie używających thinking. Od v2.1.154 (28 maja 2026) Opus 4.8 jest nowym modelem domyślnym z domyślnie wysokim wysiłkiem i poziomem /effort xhigh, dynamic workflows orkiestrują w tle dziesiątki lub setki agentów przez /workflows, tryb Fast w Opus 4.8 kosztuje 2× stawkę standardową za 2,5× większą szybkość, lean system prompt jest teraz domyślny dla wszystkich modeli z wyjątkiem Haiku/Sonnet/Opus 4.7 i wcześniejszych, /simplify wróciło do przeglądu wyłącznie porządkowego (oddzielnie od /code-review --fix), claude agents akceptuje ! <command> do uruchamiania sesji powłoki w tle, plugins mogą deklarować defaultEnabled: false, streaming tool execution jest zawsze włączone, a serwery stdio MCP otrzymują w env CLAUDE_CODE_SESSION_ID oraz CLAUDECODE=1. v2.1.153 dodało skipLfs do marketplace plugins, sprawiło, że /model zapisuje wybór jako domyślny (należy nacisnąć s dla trybu tylko dla sesji), oraz umieściło COLUMNS/LINES w env paska statusu. v2.1.152 wprowadziło /code-review --fix (stosuje ustalenia do drzewa roboczego), disallowed-tools we frontmatter skills, /reload-skills, nowe zdarzenie hook MessageDisplay, wyjścia reloadSkills/sessionTitle hook SessionStart, zarządzane ustawienie pluginSuggestionMarketplaces, przełączanie --fallback-model w trakcie sesji oraz usunęło opt-in dla auto-mode.^{162 163 164 165 166 167 168 169 170 180 171}

Claude Code działa jako system agentowy, a nie interfejs czatu z wiedzą programistyczną. CLI czyta bazę kodu, wykonuje polecenia, modyfikuje pliki, zarządza workflow git, łączy się z usługami zewnętrznymi przez MCP i deleguje złożone zadania wyspecjalizowanym subagents. Wszystko przechodzi przez interfejs command-line, który integruje się ze sposobem, w jaki programiści faktycznie pracują. Według stanu na luty 2026, 4% publicznych commitów GitHub (około 135 000 dziennie) jest autorstwa Claude Code — to wzrost 42 896× w ciągu 13 miesięcy od research preview — a 90% własnego kodu Anthropic jest napisane przez AI.¹⁰³

Różnica między okazjonalnym a skutecznym użyciem Claude Code sprowadza się do 5 podstawowych systemów. Po ich opanowaniu Claude Code staje się mnożnikiem siły:

1. Hierarchia konfiguracji: kontroluje zachowanie
2. System uprawnień: bramkuje operacje
3. System hooks: umożliwia deterministyczną automatyzację
4. Protokół MCP: rozszerza możliwości
5. System subagents: obsługuje złożone zadania wieloetapowe

Najważniejsze wnioski

• 5 systemów decyduje o skuteczności: hierarchia konfiguracji, uprawnienia, hooks, MCP i subagents kontrolują wszystko od zachowania po automatyzację.
• Pracę warto przesuwać do warstwy delegowania: subagents zapobiegają puchnięciu kontekstu, izolując eksplorację w czystych oknach kontekstu i zwracając tylko podsumowania.
• Hooks gwarantują wykonanie; prompty nie: hooks należy stosować do lintowania, formatowania i kontroli bezpieczeństwa, które muszą uruchamiać się za każdym razem niezależnie od zachowania modelu.
• Poziomy modeli pozwalają obniżyć koszt bez utraty jakości: eksplorację subagents można kierować do tańszych modeli, a Opus rezerwować dla rzeczywistego rozumowania architektonicznego — albo ustandaryzować pracę na Opus, jeśli jakość jest jedyną zmienną.
• MCP łączy Claude z toolchainem: bazy danych, GitHub, Sentry i ponad 3 000 integracji rozszerzają Claude poza czytanie plików i polecenia bash.

Przez miesiące testowałem Claude Code do granic możliwości w produkcyjnych bazach kodu, pipeline’ach CI/CD i wdrożeniach enterprise. Ten przewodnik destyluje to doświadczenie do kompletnego źródła odniesienia, którego brakowało mi na początku. Każda funkcja zawiera rzeczywistą składnię, prawdziwe przykłady konfiguracji i przypadki brzegowe, o które potykają się doświadczeni użytkownicy.

Proszę wybrać ścieżkę

Jak korzystać z tego przewodnika

To źródło odniesienia liczące ponad 5 000 wierszy — nie trzeba czytać go od deski do deski. Najlepiej zacząć tam, gdzie pasuje poziom doświadczenia:

Do wyszukiwania konkretnych flag, poleceń lub kluczy konfiguracji można użyć w przeglądarce Ctrl+F / Cmd+F. Karta szybkiego odniesienia na końcu zawiera łatwe do przeskanowania podsumowanie wszystkich głównych poleceń.

Powiązane pogłębione omówienia

Te wpisy na blogu szczegółowo omawiają konkretne aspekty Claude Code:

Szybki start w 60 sekund

Jeśli celem jest tylko uruchomienie Claude Code i zobaczenie wyniku, należy wykonać po kolei te kroki:

# 1. Install (pick one)
npm install -g @anthropic-ai/claude-code          # npm users
brew install anthropic/claude/claude              # macOS + Homebrew
curl -sL claude.ai/install.sh | sh                # native installer

# 2. Launch in any project directory
cd ~/your-project && claude

# 3. Authenticate (browser opens automatically on first run)
/login

# 4. Ask your first question
> What does this repo do? Read the key files and summarize.

To wszystko. Wszystko poniżej tej sekcji rozwija opcje instalacji, konfiguruje uprawnienia i hooks, podłącza serwery MCP oraz omawia wdrożenie w przedsiębiorstwie, ale żadna z tych rzeczy nie jest wymagana, aby zacząć.

Wymagania wstępne: Node 18+ jest potrzebny tylko w starszej ścieżce npm; zalecany natywny instalator nie ma zależności od Node. Obsługiwane są macOS / Linux / Windows 10+. Użycie obejmuje subskrypcja Claude Pro, Max, Team albo Enterprise bądź klucz Anthropic API rozliczany za tokeny. Szczegóły dla poszczególnych platform, rozwiązywanie problemów i ścieżkę natywnego pliku binarnego (domyślną od v2.1.113) opisuje sekcja Jak zainstalować Claude Code?. Dowody dotyczące najnowszego wydania w tym przewodniku sprawdzono względem v2.1.154.¹⁸⁰

Jak działa Claude Code: model mentalny

Zanim przejdzie się do funkcji, warto zrozumieć, jak architektura Claude Code kształtuje wszystko, co się z nim robi. System działa w trzech warstwach:

┌─────────────────────────────────────────────────────────┐
│                    CLAUDE CODE LAYERS                    │
├─────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                         │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐    │
│  │   MCP   │  │  Hooks  │  │ Skills  │  │ Plugins │    │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘    │
│  External tools, deterministic automation, domain       │
│  expertise, packaged extensions                          │
├─────────────────────────────────────────────────────────┤
│  DELEGATION LAYER                                        │
│  ┌─────────────────────────────────────────────────┐    │
│  │              Subagents (up to 10 parallel)       │    │
│  │   Explore | Plan | General-purpose | Custom      │    │
│  └─────────────────────────────────────────────────┘    │
│  Isolated contexts for focused work, returns summaries  │
├─────────────────────────────────────────────────────────┤
│  CORE LAYER                                              │
│  ┌─────────────────────────────────────────────────┐    │
│  │         Main Conversation Context                │    │
│  │   Tools: Read, Edit, Bash, Glob, Grep, etc.     │    │
│  └─────────────────────────────────────────────────┘    │
│  Your primary interaction; limited context; costs money │
└─────────────────────────────────────────────────────────┘

Warstwa podstawowa: Główna rozmowa. Każda wiadomość, odczyt pliku i wynik narzędzia zużywa kontekst ze współdzielonego okna (standardowo 200K tokenów⁹¹, 1M tokenów z Opus 4.6 lub modelami o rozszerzonym kontekście). Gdy kontekst się zapełnia, Claude traci z oczu wcześniejsze decyzje, a jakość spada. Ta warstwa generuje koszt za token.

Warstwa delegowania: Subagents uruchamiają się z czystymi kontekstami, wykonują ukierunkowaną pracę i zwracają podsumowania. Wyniki eksploracji nie rozdymają głównej rozmowy; wracają tylko wnioski. Do eksploracji można kierować subagents do tańszych poziomów modeli albo używać przez cały czas modelu głównego, jeśli jakość jest ważniejsza niż koszt.

Warstwa rozszerzeń: MCP łączy usługi zewnętrzne (bazy danych, GitHub, Sentry). Hooks gwarantują wykonanie poleceń shell niezależnie od zachowania modelu. Skills kodują wiedzę domenową, którą Claude stosuje automatycznie. Plugins pakują wszystkie te elementy do dystrybucji.

Kluczowa obserwacja: Większość użytkowników pracuje wyłącznie w warstwie podstawowej, obserwując puchnięcie kontekstu i rosnące koszty. Zaawansowani użytkownicy przenoszą eksplorację i pracę specjalistyczną do warstwy delegowania, utrzymują warstwę rozszerzeń skonfigurowaną pod własny workflow, a warstwy podstawowej używają tylko do orkiestracji i decyzji końcowych.

Spis treści

1. Jak zainstalować Claude Code?
2. Szybki start: pierwsza sesja
3. Podstawowe tryby interakcji
4. Dogłębny opis systemu konfiguracji
5. Który model wybrać?
6. Ile kosztuje Claude Code?
7. Ramy decyzyjne
8. Jak działa system uprawnień?
9. Jak działają hooks?
10. Czym jest MCP (Model Context Protocol)?
11. Czym są subagents?
12. Czym jest tryb rozszerzonego myślenia?
13. Style wyjścia
14. Slash Commands
15. Jak działają skills?
16. System plugins
17. Jak działa pamięć?
18. Obraz i wejście multimodalne
19. Tryb głosowy
20. Jak działa integracja z Git?
21. Jak używać Claude Code w IDE?
22. Zaawansowane wzorce użycia
23. Agenci zdalni i działający w tle [RESEARCH PREVIEW]
24. Claude w Chrome
25. Claude Code w Slack [RESEARCH PREVIEW]
26. Claude Code w przeglądarce [RESEARCH PREVIEW]
27. Optymalizacja wydajności
28. Jak debugować problemy?
29. Wdrożenie w przedsiębiorstwie
30. Skróty klawiaturowe
31. Najlepsze praktyki
32. Przepisy workflow
33. Przewodnik migracji
34. Wskazówki dla konkretnych grup odbiorców
35. Szybka ściąga
36. Changelog
37. Źródła

Jak zainstalować Claude Code?

Wymagania systemowe

Claude Code działa na macOS 13+, Ubuntu 20.04+/Debian 10+ oraz Windows 10+ (natywnie lub WSL). System wymaga co najmniej 4 GB pamięci RAM oraz aktywnego połączenia internetowego.⁹² Najlepszą kompatybilność powłoki zapewniają Bash, Zsh lub Fish.

W przypadku systemu Windows działają zarówno WSL 1, jak i WSL 2. Git Bash również działa, jeśli preferowane jest natywne środowisko Windows. Alpine Linux i inne systemy oparte na musl wymagają dodatkowych pakietów:

apk add libgcc libstdc++ ripgrep
export USE_BUILTIN_RIPGREP=0

Macierz wsparcia platform

Instalacja, aktualizacja i odinstalowanie w skrócie

Skanowalna ściąga — każda metoda, każde polecenie, sprawdzenie wersji na jednym ekranie. Poniższe podsekcje obejmują szczegóły dotyczące poszczególnych metod oraz rozwiązywanie problemów.

Od v2.1.113 kanoniczne CLI uruchamia natywny plik binarny Claude Code poprzez opcjonalną zależność dla danej platformy zamiast dołączonego JavaScript — należy używać natywnego instalatora dla testowanej dystrybucji. Ścieżka npm nadal działa, ale otrzymuje powiadomienie o wycofaniu wprowadzone w v2.1.15.

Metody instalacji

Natywna instalacja (zalecana)

Natywny plik binarny zapewnia najczystsze doświadczenie bez zależności od Node.js:

# macOS and Linux
curl -fsSL https://claude.ai/install.sh | bash

# Homebrew alternative
brew install --cask claude-code

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Instalacja konkretnej wersji:

# Install specific version
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

# Install latest explicitly
curl -fsSL https://claude.ai/install.sh | bash -s latest

# Windows PowerShell - specific version
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58

Instalacja przez NPM (przestarzała)

Uwaga: Od v2.1.15 instalacje npm wyświetlają powiadomienie o wycofaniu. Natywny plik binarny jest obecnie zalecaną metodą instalacji. Migrację można wykonać poleceniem claude install.

W przypadku środowisk legacy, w których nadal potrzebny jest npm:

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

Nigdy nie należy używać sudo przy instalacji npm. Powoduje to problemy z uprawnieniami, które komplikują wszystko w dalszej kolejności.

Migracja z istniejącej instalacji

Jeśli posiada się starszą instalację opartą na npm, można wykonać migrację do natywnego pliku binarnego:

claude install

Opcje uwierzytelniania

Claude Code obsługuje trzy ścieżki uwierzytelniania, każda z innymi kompromisami:

Claude Console (rozliczenia API)

Łączy się bezpośrednio z API firmy Anthropic przez platform.claude.com (wcześniej console.anthropic.com). Należy utworzyć konto, skonfigurować rozliczenia i uwierzytelnić się przez CLI. Console zapewnia rozliczenia oparte na zużyciu z pełnym dostępem do API. Dedykowany obszar roboczy „Claude Code” jest tworzony automatycznie; nie można utworzyć kluczy API dla tego obszaru roboczego, ale można monitorować zużycie.

Subskrypcja Claude Pro lub Max

Należy użyć danych logowania konta claude.ai. Subskrypcja pokrywa zarówno interfejs webowy, jak i użycie CLI w ramach jednego miesięcznego planu. Subskrypcja upraszcza rozliczenia dla użytkowników indywidualnych, którzy oczekują przewidywalnych kosztów.

Platformy korporacyjne

AWS Bedrock, Google Vertex AI i Microsoft Foundry zapewniają dostęp klasy korporacyjnej z istniejącymi relacjami rozliczeniowymi w chmurze. Kreator konfiguracji Bedrock (v2.1.92+): Interaktywny kreator na ekranie logowania prowadzi przez uwierzytelnianie AWS, wybór regionu, weryfikację poświadczeń oraz przypinanie modelu.¹³⁷ Kreator konfiguracji Vertex AI (v2.1.98+): Pasujący kreator dla Google Cloud, prowadzący przez uwierzytelnianie GCP, konfigurację projektu i regionu, weryfikację poświadczeń oraz przypinanie modelu.¹⁴² Vertex AI mTLS Workload Identity Federation (v2.1.121+): Vertex AI akceptuje teraz Workload Identity Federation oparte na certyfikatach X.509 (mTLS Application Default Credentials) — krótkotrwałe tokeny GCP wybijane z certyfikatu klienta, bez wymogu JSON konta usługi.¹⁵⁴ Zaufanie do certyfikatu CA systemu operacyjnego (v2.1.101+): Korporacyjne proxy TLS działają teraz domyślnie — Claude Code ufa magazynowi certyfikatów systemu operacyjnego. Należy ustawić CLAUDE_CODE_CERT_STORE=bundled, aby używać tylko dołączonych urzędów CA.¹⁴³

# AWS Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
export AWS_PROFILE=your-profile

# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=your-project

# Microsoft Foundry
export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_RESOURCE=your-resource-name
# Optional: API key auth (otherwise uses Entra ID)
export ANTHROPIC_FOUNDRY_API_KEY=your-key

# Amazon Bedrock via Mantle (v2.1.94+)
export CLAUDE_CODE_USE_MANTLE=1

W przypadku wdrożeń korporacyjnych za serwerami proxy lub przez bramy LLM:

# Corporate proxy
export HTTPS_PROXY='https://proxy.example.com:8080'

# LLM gateway (skip native auth)
export CLAUDE_CODE_USE_BEDROCK=1
export ANTHROPIC_BEDROCK_BASE_URL='https://your-gateway.com/bedrock'
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1

Weryfikacja

claude doctor

Polecenie raportuje typ instalacji, wersję, konfigurację systemu oraz wszelkie wykryte problemy.

Zarządzanie uwierzytelnianiem (v2.1.41+)

Zarządzanie uwierzytelnianiem bez wchodzenia do REPL:⁹⁰

claude auth login          # Log in or switch accounts
claude auth status         # Check current auth state (account, plan, expiry)
claude auth logout         # Clear stored credentials

Typowy przepływ pracy przy przełączaniu między kontami lub organizacjami:

claude auth logout && claude auth login

Patrz także: Jak debugować problemy?, aby uzyskać informacje o rozwiązywaniu problemów z uwierzytelnianiem.

Aktualizacje

Claude Code aktualizuje się automatycznie domyślnie, sprawdzając przy uruchomieniu i okresowo podczas sesji. Aktualizacje pobierają się w tle i są stosowane przy następnym uruchomieniu.

Wyłączanie automatycznych aktualizacji:

export DISABLE_AUTOUPDATER=1

Lub w settings.json:

{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}

Aktualizacja ręczna:

claude update

Odinstalowanie

Natywna instalacja (macOS/Linux/WSL):

rm -f ~/.local/bin/claude
rm -rf ~/.claude-code

Natywna instalacja (Windows PowerShell):

Remove-Item -Path "$env:LOCALAPPDATA\Programs\claude-code" -Recurse -Force
Remove-Item -Path "$env:LOCALAPPDATA\Microsoft\WindowsApps\claude.exe" -Force

Czysta konfiguracja (usuwa wszystkie ustawienia):

rm -rf ~/.claude
rm ~/.claude.json
rm -rf .claude
rm -f .mcp.json

Szybki start: Pierwsza sesja

1. Instalacja i uruchomienie:

claude                           # Launch in current directory

2. Przejście do projektu:

cd ~/my-project && claude        # Or launch from any git repo

3. Proszę poprosić Claude o wykonanie czegoś:

> "Explain the architecture of this project"
> "Find all TODO comments and create a summary"
> "Add input validation to the signup form"

4. Używanie kluczowych skrótów podczas sesji:

/cost                            # Check token usage and cost
/compact                         # Free up context when it gets large
Alt+T                            # Toggle extended thinking for hard problems
Ctrl+C                           # Cancel current response

5. Kontynuacja później:

claude -c                        # Resume your most recent session
claude --resume                  # Pick from session list

Wskazówka eksperta: Warto utworzyć plik CLAUDE.md w katalogu głównym projektu, zawierający polecenia kompilacji, konwencje kodowania oraz notatki o architekturze. Claude odczytuje go w każdej sesji — to najbardziej skuteczna pojedyncza czynność, jaką można wykonać dla jakości pracy.

Główne tryby interakcji

Interaktywny REPL

Aby wejść w interaktywną pętlę read-eval-print, należy uruchomić Claude Code bez argumentów:

cd your-project
claude

REPL utrzymuje kontekst rozmowy między kolejnymi turami. Można wpisywać zapytania bezpośrednio, otrzymywać odpowiedzi i kontynuować, aż do zakończenia poleceniem /exit lub Ctrl+D.

Aby ukierunkować sesję, warto rozpocząć od początkowego promptu:

claude "explain the authentication flow in this project"

Wskazówka eksperta: REPL zachowuje stan podczas zdarzeń kompaktowania. Gdy kontekst staje się zbyt duży, Claude automatycznie podsumowuje wcześniejszą rozmowę, zachowując kluczowe decyzje i fragmenty kodu. Można uruchomić ten proces ręcznie poleceniem /compact lub dodać własne instrukcje określające, co ma zostać zachowane.

Tryb nieinteraktywny

Tryb wydruku (-p) wykonuje pojedyncze zapytanie i kończy działanie:

# Direct query
claude -p "list all TODO comments in this project"

# Process piped input
cat error.log | claude -p "identify the root cause of these failures"

# Chain with other tools
claude -p "generate a README" > README.md

Aby uzyskać uporządkowany wynik nadający się do parsowania w skryptach:

claude -p "count lines by file type" --output-format json

Wynik JSON zawiera wszystko, co jest potrzebne do automatyzacji:

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.0034,
  "is_error": false,
  "duration_ms": 2847,
  "duration_api_ms": 1923,
  "num_turns": 4,
  "result": "Response text here...",
  "session_id": "abc-123-def"
}

Do przetwarzania strumieniowego wyjścia w czasie rzeczywistym:

claude -p "build the application" --output-format stream-json | while read line; do
  echo "$line" | jq -r 'select(.result) | .result'
done

Opcje formatu wyjścia:

Kody wyjścia:

Sterowanie zachowaniem agentowym w trybie -p:

# Limit autonomous turns (prevents runaway loops)
claude -p "refactor the auth module" --max-turns 10

# Allow specific tools without prompting
claude -p "fix lint errors" --allowedTools "Edit,Bash(npm run lint)"

# Use with a specific model
claude -p "explain this code" --model claude-sonnet-4-5-20250929

# Bare mode: skip hooks, LSP, plugin sync, skill walks (v2.1.81+)
claude -p "count files" --bare

# Channel permission relay: send approval prompts to Telegram/Discord (v2.1.81+)
claude --channels

Wzorzec integracji CI/CD:

# In a GitHub Action or CI pipeline
result=$(claude -p "review this diff for security issues" --output-format json 2>/dev/null)
is_error=$(echo "$result" | jq -r '.is_error')
if [ "$is_error" = "true" ]; then
  echo "Review failed"
  exit 1
fi
echo "$result" | jq -r '.result'

Zarządzanie sesjami

Sesje zachowują historię rozmowy w celu kontynuacji. Trwałość sesji jest niezbędna w przypadku złożonej pracy obejmującej wiele sesji:

# Continue most recent session
claude -c

# Continue with additional prompt
claude -c -p "now add error handling"

# Resume specific session by ID
claude -r "abc123" "implement the remaining tests"

# Fork a session for parallel exploration
claude -r "base-session" --fork-session "try a different approach"

Sesje powiązane z PR (v2.1.27+, rozszerzone v2.1.119+): Można rozpocząć sesję powiązaną z konkretnym pull lub merge requestem. Od wersji v2.1.119 --from-pr akceptuje URL-e GitLab MR, Bitbucket PR oraz GitHub Enterprise PR oprócz github.com:⁷⁴¹⁵²

claude --from-pr 123                                                # GitHub PR number (assumes current repo's remote)
claude --from-pr https://github.com/org/repo/pull/123               # GitHub URL
claude --from-pr https://gitlab.com/org/repo/-/merge_requests/45    # GitLab MR (v2.1.119+)
claude --from-pr https://bitbucket.org/org/repo/pull-requests/67    # Bitbucket PR (v2.1.119+)
claude --from-pr https://ghe.example.com/org/repo/pull/89           # GitHub Enterprise (v2.1.119+)

Sesje są również automatycznie powiązywane z PR-ami, gdy są tworzone za pomocą gh pr create w trakcie sesji. Dzięki temu można łatwo wznowić pracę nad konkretnym PR-em w późniejszym czasie. Plakietka PR w stopce może wskazywać własny URL przeglądu kodu poprzez ustawienie prUrlTemplate (v2.1.119+) — co jest przydatne, gdy zespół tworzy odnośniki z PR-ów do osobnego narzędzia przeglądu.¹⁵²

/resume akceptuje URL-e PR (v2.1.122+). Wklejenie URL-a PR do pola wyszukiwania /resume znajduje teraz sesję, która pierwotnie utworzyła ten PR — działa to dla github.com, GitHub Enterprise, gitlab.com (i samodzielnie hostowanego GitLab) oraz bitbucket.org.¹⁵⁴

Nazwane sesje: Sesje można nazywać przy uruchomieniu lub w trakcie sesji:

# Name session at startup (v2.1.76+)
claude -n "auth-refactor"                  # --name flag sets display name[^125]

# Name current session
> /rename auth-refactor

# Resume by name or number
> /resume 1                    # Resume first session
> /resume auth-refactor        # Resume by name
claude --resume auth-refactor  # Resume from terminal
claude -r 3                    # Resume by number from terminal

# Fork for parallel exploration
claude --resume auth-refactor --fork-session

Uwaga: --session-id wymaga prawidłowego UUID (np. 550e8400-e29b-41d4-a716-446655440000). Aby uzyskać czytelne dla człowieka nazewnictwo sesji, należy zamiast tego używać /rename oraz --resume.

Claude Code przechowuje sesje jako transkrypty JSONL. Wykonanie agenta przypisuje unikalne wartości agentId, a transkrypty są zapisywane jako agent-{agentId}.jsonl. Wznowienie zachowuje pełny kontekst z poprzednich rozmów.

Tryb planowania

Tryb planowania ogranicza Claude do eksploracji w trybie tylko do odczytu — bez edycji plików, bez wykonywania bash, bez działań destrukcyjnych. Claude projektuje podejście do implementacji, zapisuje je w pliku planu i czeka na zatwierdzenie przed wykonaniem czegokolwiek.

Wejście w tryb planowania:

# Cycle through modes during a session
Shift+Tab           # Cycles: normal → plan → auto-accept

# Or use the /plan command with an optional description (v2.1.72+)
/plan                                     # Enter plan mode
/plan refactor the auth module            # Enter plan mode with a description

# Or ask Claude directly
"Plan how to refactor the auth module"   # Claude may enter plan mode automatically

Jak to działa:

1. Claude wchodzi w tryb planowania (automatycznie dla złożonych zadań lub poprzez Shift+Tab)
2. Eksploruje bazę kodu używając narzędzi tylko do odczytu: Read, Glob, Grep, WebSearch, WebFetch
3. Zapisuje plan do .claude/plans/{session-slug}.md
4. Wychodzi z trybu planowania poprzez ExitPlanMode, prezentując plan do przeglądu
5. Można zatwierdzić, poprosić o zmiany lub odrzucić

Narzędzia dostępne w trybie planowania: Read, Glob, Grep, LS, WebSearch, WebFetch, AskUserQuestion. Narzędzia edycyjne (Edit, Write, Bash, NotebookEdit) są zablokowane.

Po zatwierdzeniu planu (v2.1.32+): Claude oferuje trzy opcje: - „Yes, clear context and auto-accept edits” (Shift+Tab) — rozpoczyna od nowa z pełnym kontekstem dla planu - „Yes, and manually approve edits” — zachowuje kontekst, ręczne zatwierdzanie każdej zmiany - „Yes, auto-accept edits” — zachowuje kontekst, Claude wykonuje bez zatwierdzania każdej edycji

Automatyczne czyszczenie kontekstu przy zatwierdzeniu to zalecany przepływ pracy. Daje on planowi świeże okno kontekstowe, co znacząco poprawia trzymanie się planu — Claude pozostaje na właściwym torze dłużej, bez ingerencji starszej rozmowy.

Kiedy używać trybu planowania: - Implementacje nowych funkcji wymagające decyzji architektonicznych - Refaktoryzacje obejmujące wiele plików, gdy najpierw chce się przejrzeć podejście - Nieznane bazy kodu, w których eksploracja powinna poprzedzać modyfikację - Każde zadanie, w którym istnieje wiele prawidłowych podejść i pożądany jest wkład

Wskazówka eksperta: Im więcej czasu spędza się w trybie planowania, tym większe prawdopodobieństwo, że Claude powiedzie się przy implementacji. Tryb planowania to praktycznie darmowa eksploracja — bez ryzykownych wywołań narzędzi, bez zmarnowanych edycji. Warto z niego korzystać szeroko.

dogłębna analiza systemu konfiguracji

Claude Code korzysta z warstwowego systemu konfiguracji. Zrozumienie hierarchii jest kluczowe, ponieważ wyższe poziomy zastępują niższe, a ustawień enterprise nie można w ogóle ominąć.

hierarchia konfiguracji

Wskazówka ekspercka: W projektach współdzielonych warto używać .claude/settings.local.json do osobistych preferencji (i dodać ten plik do .gitignore). .claude/settings.json należy stosować do konfiguracji całego zespołu, która trafia do systemu kontroli wersji.

pełna dokumentacja settings.json

Pełna konfiguracja pokazująca wszystkie główne opcje:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-4-5-20250929",
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(npm run:*)",
      "Bash(git:*)",
      "Bash(make:*)",
      "Edit(src/**)",
      "Write(src/**)",
      "mcp__github"
    ],
    "deny": [
      "Read(.env*)",
      "Read(secrets/**)",
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Edit(package-lock.json)",
      "Edit(.git/**)"
    ],
    "ask": [
      "WebFetch",
      "Bash(curl:*)",
      "Bash(docker:*)"
    ],
    "additionalDirectories": [
      "../shared-lib",
      "../docs"
    ],
    "defaultMode": "acceptEdits"
  },
  "env": {
    "NODE_ENV": "development",
    "DEBUG": "app:*"
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$FILE_PATH\""
          }
        ]
      }
    ]
  },
  "sandbox": {
    "enabled": false,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"]
  },
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  },
  "includeCoAuthoredBy": true,
  "cleanupPeriodDays": 30,
  "outputStyle": "Explanatory",
  "language": "en",
  "respectGitignore": true,
  "showTurnDuration": true,
  "plansDirectory": ".claude/plans",
  "spinnerVerbs": ["Thinking", "Processing", "Analyzing"],
  "spinnerTipsOverride": {
    "tips": ["Custom tip 1", "Custom tip 2"],
    "excludeDefault": true
  },
  "skillOverrides": {
    "legacy-skill": "off",
    "manual-only-skill": "user-invocable-only",
    "compact-skill": "name-only"
  },
  "includeGitInstructions": false,
  "modelOverrides": {
    "bedrock": "us.anthropic.claude-opus-4-6-20260312-v1:0",
    "vertex": "claude-opus-4-6@20260312",
    "foundry": "anthropic.claude-opus-4-6"
  },
  "autoMemoryDirectory": ".claude/memory",
  "sandbox": {
    "enableWeakerNetworkIsolation": true
  }
}

skillOverrides przydaje się, gdy zespół ma dużą bibliotekę skills, ale chce ściślej ograniczyć ich dostępność w czasie działania. off ukrywa skill zarówno przed modelem, jak i selektorem slash, user-invocable-only pozwala nadal wywołać go po nazwie, usuwając go z wyboru modelu, a name-only pozostawia widoczną tylko nazwę skill bez pełnego opisu.¹⁵⁶

Nowsze ustawienia (v2.1.174–176):

• availableModels / enforceAvailableModels (zarządzane, v2.1.175+): lista dozwolonych availableModels ogranicza modele, które może wybrać sesja. Przy enforceAvailableModels: true lista dozwolonych modeli ogranicza także model Default — jeśli Default wskazywałby model niedozwolony, następuje powrót do pierwszego dozwolonego modelu — a ustawienia użytkownika/projektu nie mogą już rozszerzać zarządzanej listy availableModels. Towarzysząca poprawka (v2.1.176) zamyka lukę, w której wybór aliasu mógł przekierować do zablokowanego modelu przez ANTHROPIC_DEFAULT_*_MODEL, a /fast odmawia teraz przełączenia na model spoza listy dozwolonych.¹⁷²
• language (doprecyzowanie v2.1.176): oprócz ustawiania języka odpowiedzi tytuły sesji są teraz domyślnie generowane w języku rozmowy; aby przypiąć konkretny język tytułów, należy ustawić language.¹⁷²
• footerLinksRegexes (v2.1.176): plakietki linków dopasowywane regexem w wierszu stopki, konfigurowalne przez ustawienia użytkownika lub ustawienia zarządzane.¹⁷²
• wheelScrollAccelerationEnabled (v2.1.174): ustawienie false wyłącza przyspieszenie przewijania kółkiem myszy w trybie pełnoekranowym.¹⁷²

dokumentacja zmiennych środowiskowych

Uwierzytelnianie i API:

ANTHROPIC_API_KEY=sk-ant-...                    # Direct API authentication
ANTHROPIC_AUTH_TOKEN=token                      # Custom authorization header
ANTHROPIC_CUSTOM_HEADERS="X-Key: val"           # Additional request headers

Konfiguracja modelu:

ANTHROPIC_MODEL=claude-opus-4-7                 # Override default model (Apr 16, 2026)
ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-7    # Opus 4.7 (Max/Team Premium default)
ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6
ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5-20251001
CLAUDE_CODE_SUBAGENT_MODEL=sonnet               # Model for subagents
CLAUDE_CODE_WORKFLOWS=1                         # Enable Workflow tool for deterministic multi-agent orchestration (v2.1.147+)
MAX_THINKING_TOKENS=10000                       # (Opus 4.6 and Sonnet 4.6 only — removed in Opus 4.7)
CLAUDE_CODE_MAX_OUTPUT_TOKENS=4000              # Limit output length
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1          # Enable agent teams (v2.1.32+)

Konfiguracja dostawcy chmurowego:

CLAUDE_CODE_USE_BEDROCK=1                       # Use AWS Bedrock
CLAUDE_CODE_USE_VERTEX=1                        # Use Google Vertex AI
CLAUDE_CODE_USE_FOUNDRY=1                       # Use Microsoft Foundry
ANTHROPIC_BEDROCK_BASE_URL=https://...          # Custom Bedrock endpoint
ANTHROPIC_BEDROCK_SERVICE_TIER=priority         # Bedrock service tier (v2.1.122+): 'default', 'flex', or 'priority'; sent as X-Amzn-Bedrock-Service-Tier header[^162]
CLAUDE_CODE_SKIP_BEDROCK_AUTH=1                 # Skip Bedrock auth (for gateways)
CLAUDE_CODE_SKIP_VERTEX_AUTH=1                  # Skip Vertex auth
AWS_BEARER_TOKEN_BEDROCK=token                  # Bedrock bearer token
VERTEX_REGION_CLAUDE_3_7_SONNET=us-west1        # Override Vertex region
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1    # Opt in gateway /v1/models discovery for /model picker (v2.1.129+)[^164]

Sterowanie zachowaniem:

DISABLE_AUTOUPDATER=1                           # Prevent automatic background updates
DISABLE_UPDATES=1                               # Block ALL update paths including manual `claude update` (v2.1.118+, stricter than DISABLE_AUTOUPDATER)[^160]
CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1       # Homebrew/WinGet installs run package-manager upgrade in background, then prompt restart (v2.1.129+)[^164]
DISABLE_TELEMETRY=1                             # Opt out of usage telemetry
DISABLE_ERROR_REPORTING=1                       # Disable Sentry
DISABLE_BUG_COMMAND=1                           # Disable /bug command
DISABLE_COST_WARNINGS=1                         # Hide cost warnings
DISABLE_PROMPT_CACHING=1                        # Disable prompt caching globally
DISABLE_PROMPT_CACHING_SONNET=1                 # Disable for Sonnet only
DISABLE_PROMPT_CACHING_OPUS=1                   # Disable for Opus only
DISABLE_NON_ESSENTIAL_MODEL_CALLS=1             # Skip non-critical API calls
ENABLE_PROMPT_CACHING_1H=1                      # Opt into 1-hour prompt cache TTL (v2.1.108+, API/Bedrock/Vertex/Foundry)
ENABLE_PROMPT_CACHING_1H_BEDROCK=1              # Deprecated alias for the above; v2.1.108+ still honors it on Bedrock but logs a deprecation notice
FORCE_PROMPT_CACHING_5M=1                       # Force 5-minute cache TTL (v2.1.108+)
ENABLE_TOOL_SEARCH=true                         # Re-enable tool search on Vertex AI (disabled by default v2.1.119+ to avoid unsupported beta header). Valid values: true, false, auto, auto:N[^160]
CLAUDE_CODE_HIDE_CWD=1                          # Hide the working directory in the startup logo (v2.1.119+)[^160]
CLAUDE_CODE_FORK_SUBAGENT=1                     # Enable forked subagents on external builds (v2.1.117+)[^160]
CLAUDE_CODE_FORCE_SYNC_OUTPUT=1                 # Force synchronized terminal output when auto-detection misses it, such as Emacs eat (v2.1.129+)[^164]
CLAUDE_CODE_SESSION_ID=...                      # Read-only: present in the Bash tool subprocess; matches the session_id passed to hooks (v2.1.132+)[^168]
CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1          # Skip the fullscreen alternate-screen renderer; keep the conversation in the terminal's native scrollback (v2.1.132+)[^168]
CLAUDE_EFFORT=...                               # Read-only: current effort level inside hooks and Bash tool subprocess (v2.1.133+)[^169]

Konfiguracja narzędzi:

BASH_DEFAULT_TIMEOUT_MS=30000                   # Bash command timeout (30s)
BASH_MAX_TIMEOUT_MS=600000                      # Maximum bash timeout (10min)
BASH_MAX_OUTPUT_LENGTH=50000                    # Bash output limit
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1     # Reset CWD after each bash
MCP_TIMEOUT=5000                                # MCP server startup timeout
MCP_TOOL_TIMEOUT=30000                          # MCP tool execution timeout
MAX_MCP_OUTPUT_TOKENS=25000                     # MCP output limit
SLASH_COMMAND_TOOL_CHAR_BUDGET=15000            # Slash command context limit

Sieć i proxy:

HTTP_PROXY=http://proxy:8080                    # HTTP proxy
HTTPS_PROXY=https://proxy:8080                  # HTTPS proxy
NO_PROXY=localhost,example.com                  # Bypass proxy for domains
CLAUDE_CODE_CLIENT_CERT=/path/to/cert           # mTLS certificate
CLAUDE_CODE_CLIENT_KEY=/path/to/key             # mTLS private key
CLAUDE_CODE_CLIENT_KEY_PASSPHRASE=pass          # mTLS passphrase

UI i terminal:

CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1            # Don't update terminal title
CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL=1             # Skip IDE extension install
CLAUDE_CODE_SHELL=/bin/zsh                      # Override shell detection
USE_BUILTIN_RIPGREP=1                           # Use included ripgrep (default)
CLAUDE_CONFIG_DIR=~/.myconfig                   # Custom config directory
IS_DEMO=1                                       # Hide sensitive UI elements[^37]
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1          # Disable background tasks and Ctrl+B[^46]
CLAUDE_CODE_TMPDIR=/path/to/tmp                 # Override temp directory[^50]
CLAUDE_CODE_DISABLE_1M_CONTEXT=1               # Disable 1M context window (use standard 200K)[^103]
CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=120000       # Plugin marketplace git timeout (default 120s, was 30s)[^105]
CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=1        # Remove built-in commit/PR instructions[^117]
CLAUDE_CODE_DISABLE_CRON=1                    # Stop scheduled cron jobs mid-session[^121]
CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=30000 # SessionEnd hooks timeout (default varies)[^123]
CLAUDE_CODE_USE_POWERSHELL_TOOL=1             # Enable Windows PowerShell tool on Linux/macOS (requires pwsh on PATH; v2.1.111+)[^153]
CLAUDE_CODE_ENABLE_AWAY_SUMMARY=1             # Force Session Recap when telemetry disabled (v2.1.108+)[^153]
OTEL_LOG_RAW_API_BODIES=1                     # Emit full API request/response bodies as OTel log events (v2.1.111+)[^153]
TRACEPARENT=00-...                            # W3C Trace Context parent (v2.1.110+, SDK/headless)[^153]
TRACESTATE=vendor=value                       # W3C Trace Context state (v2.1.110+, SDK/headless)[^153]

Eksportery OpenTelemetry + bramkowanie pól wrażliwych:¹⁸¹

OTEL_LOGS_EXPORTER=none                       # OTel logs exporter (supports 'none' for disable; v2.1.85 fixed crash)
OTEL_METRICS_EXPORTER=none                    # OTel metrics exporter (supports 'none'; v2.1.85 fixed crash)
OTEL_TRACES_EXPORTER=none                     # OTel traces exporter (supports 'none'; v2.1.85 fixed crash)
OTEL_LOG_TOOL_CONTENT=1                       # Opt in to emitting tool content in OTel spans (v2.1.101+, sensitive by default)
OTEL_LOG_TOOL_DETAILS=1                       # Opt in to tool_parameters in OTel tool_result events (v2.1.85+)
OTEL_LOG_USER_PROMPTS=1                       # Opt in to emitting user prompts in OTel traces (v2.1.101+, sensitive by default)
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1    # Disable release-notes fetch (v2.0.17+); v2.1.110 also stopped the auto-title Haiku request in headless/SDK when set

Atrybuty spanów żądań LLM w v2.1.121+: stop_reason, gen_ai.response.finish_reasons oraz user_system_prompt są teraz emitowane w spanach żądań LLM. user_system_prompt jest bramkowany przez OTEL_LOG_USER_PROMPTS=1, ponieważ może zawierać PII.¹⁵⁴

Zmiany na poziomie zdarzeń w v2.1.122+: Atrybuty numeryczne w zdarzeniach logów api_request i api_error są teraz emitowane jako liczby (wcześniej były stringami) — rozwiązuje to problemy z dalszymi kolektorami OTel, które ściśle typowały schemat. Nowe zdarzenie logów claude_code.at_mention jest wyzwalane, gdy Claude Code rozwiązuje wzmiankę @.¹⁵⁴

API / sterowanie modelem:¹⁸¹

CLAUDE_CODE_EXTRA_BODY='{...}'                # Inject extra body fields into API calls; v2.1.113 fixed 400 errors with output_config.effort on Vertex/subagent calls
CLAUDE_CODE_MAX_CONTEXT_TOKENS=200000         # Override max context tokens (pre-existing var; v2.1.98 fixed handling of DISABLE_COMPACT when both are set)
CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS=25000 # Override default token limit for file read operations (v2.1.0+)
CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1   # Do not fall back to non-streaming API on streaming failures (v2.1.83+)
ANTHROPIC_BETAS=beta1,beta2                   # Enable beta API headers; v2.1.78 fixed silent ignore on Haiku models
ANTHROPIC_SMALL_FAST_MODEL=arn:...            # Fast model ID (Bedrock ARN supported; v0.2.125 stopped escaping slashes in ARN)

Plugins / MCP:¹⁸¹

CLAUDE_CODE_PLUGIN_CACHE_DIR=~/.claude/plugins # Plugin cache directory (v2.1.72 fixed literal '~' dir on some shells)
CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 # Preserve plugin marketplace cache when git pull fails (offline-friendly; v2.1.90+)
CLAUDE_CODE_MCP_SERVER_NAME=server1           # Passed to MCP headersHelper scripts so one helper can serve multiple servers (v2.1.85+)
CLAUDE_CODE_MCP_SERVER_URL=https://...        # Passed to MCP headersHelper scripts alongside the name (v2.1.85+)

Shell / IDE:¹⁸¹

CLAUDE_CODE_SHELL_PREFIX="time "              # Wrap every Claude-invoked shell command with a prefix (v1.0.61+)
CLAUDE_CODE_GIT_BASH_PATH=C:\Program\ Files\Git\bin\bash.exe  # Custom Git Bash path on Windows (v2.1.98+)
CLAUDE_CODE_EXIT_AFTER_STOP_DELAY=60000       # SDK: exit after N ms idle (v2.0.35+)
CLAUDE_CODE_AUTO_CONNECT_IDE=false            # Disable IDE auto-connection (v1.0.61+)

Enterprise / auth:¹⁸¹

CLAUDE_CODE_PROXY_RESOLVES_HOSTS=1            # Opt into proxy-side DNS resolution (v2.0.55 moved this from default-on to opt-in)
CLAUDE_CODE_API_KEY_HELPER_TTL_MS=300000      # TTL for dynamically generated API keys via apiKeyHelper (apiKeyHelper refresh added v0.2.74 with 5-min default; env var added v0.2.117)

Zmienne skills (v2.1.69+):

${CLAUDE_SKILL_DIR}                            # Self-reference for skills to locate their own directory[^117]

Tożsamość wywołującego SDK (v2.1.51+):

CLAUDE_CODE_ACCOUNT_UUID=uuid                  # Provide account UUID synchronously for SDK callers
CLAUDE_CODE_USER_EMAIL=[email protected]        # Provide user email for SDK callers
CLAUDE_CODE_ORGANIZATION_UUID=uuid             # Provide organization UUID for SDK callers

Debugowanie:

ANTHROPIC_LOG=debug                             # Enable API request logging

Który model wybrać?

Wybór odpowiedniego modelu do każdego zadania znacząco wpływa zarówno na koszt, jak i jakość. Claude Code zapewnia elastyczne przełączanie modeli na wielu poziomach.

Dostępne modele

Claude Fable 5 (9 czerwca 2026): Nowy poziom modelu powyżej Opus — najmocniejszy i najbardziej inteligentny model Anthropic, osiągający wyniki state-of-the-art w niemal każdym benchmarku, w którym był testowany, oraz zaprojektowany tak, aby zachowywać spójność przez miliony tokenów kontekstu. Fable 5 to frontier model klasy „Mythos” zabezpieczony do ogólnego użytku: zawiera klasyfikatory bezpieczeństwa, które wracają do Opus 4.8 przy zapytaniach z obszaru cyber, bio-chem oraz model-distillation (Claude Mythos 5 to ten sam model z usuniętymi zabezpieczeniami dla autoryzowanych badaczy). W Claude Code stał się możliwy do wyboru w v2.1.170 (9 czerwca 2026) — należy uruchomić claude update, następnie /model fable (krótki alias; /model claude-fable-5 oraz alias best także go wybierają) — i jest stopniowo udostępniany planom subskrypcyjnym do 22 czerwca 2026. ID modelu: claude-fable-5. Fable 5 domyślnie zawiera okno kontekstu 1M, więc sufiks [1m] jest zbędny — a od v2.1.173 (11 czerwca 2026) nazwa modelu claude-fable-5[1m] jest automatycznie normalizowana/usuwana do claude-fable-5 (sufiks miał znaczenie wyłącznie dla Opus/Sonnet, gdzie 1M jest bramkowane przez [1m]); maksymalny output to 128K. Cena wynosi $10/MTok input i $50/MTok output — około 2× Opus 4.8 — dlatego warto rezerwować go na naprawdę trudne rozumowanie, a nie rutynowe edycje. Dzieli powierzchnię żądań Opus 4.8 (tylko adaptive thinking; usunięte temperature/top_p/top_k oraz budget_tokens) z jednym nowym niuansem: jawne thinking: {type: "disabled"} zwraca 400, więc aby uruchomić bez thinking, należy całkowicie pominąć parametr thinking.¹⁷⁴

Konkretnie w Claude Code: Fable 5 obsługuje pełną skalę effort (low/medium/high/xhigh/max, domyślnie high), tak samo jak Opus 4.8. Thinking nie można wyłączyć w Fable 5 — przełącznik thinking w sesji, ustawienie alwaysThinkingEnabled oraz MAX_THINKING_TOKENS=0 nie mają żadnego efektu; model zawsze rozumuje adaptacyjnie. Pełna powierzchnia konfiguracji rodziny fable odzwierciedla przełączniki Opus: ANTHROPIC_DEFAULT_FABLE_MODEL przypina model, do którego rozwiązuje się alias fable (przydatne na Bedrock/Vertex/Foundry), DISABLE_PROMPT_CACHING_FABLE wyłącza prompt caching dla Fable, a content-based automatic fallback działa na bramkach enterprise. Opus 4.8 pozostaje agentic default w Claude Code (domyślnie high effort, /effort xhigh dla najtrudniejszych zadań); Fable 5 należy wybierać świadomie przez /model fable, gdy potrzebny jest absolutny sufit możliwości.¹⁷⁴

Opus 4.7 (16 kwietnia 2026): Flagowy model poprzedniej generacji, nadal w pełni dostępny. Okno kontekstu 1M tokenów w standardowej cenie — bez dopłaty za długi kontekst. Maksymalny output 128K, tylko adaptive thinking (extended thinking usunięte) oraz nowy poziom effort xhigh, rekomendowany jako punkt startowy dla kodowania i obciążeń agentic.¹⁴⁵ Wiarygodna granica wiedzy: styczeń 2026. Granica danych treningowych: styczeń 2026. ID modelu: claude-opus-4-7. Cena odpowiada Opus 4.6: $5/$25 za MTok, z 5-min cache write $6.25, 1-hr cache write $10 oraz cache read $0.50 za MTok.¹⁴⁴ Opus 4.7 rozwiązuje 3× więcej zadań produkcyjnych w SWE-Bench niż Opus 4.6, osiąga 70% w CursorBench (wobec 58% dla 4.6) i podnosi rozwiązywalność o 13% w wewnętrznym benchmarku kodowania Anthropic obejmującym 93 zadania.¹⁴⁴ Używa nowego tokenizera — należy oczekiwać około 1×–1,35× liczby tokenów dla tego samego tekstu; warto zwiększyć zapas max_tokens i progi kompaktowania.¹⁴⁵ Vision obsługuje obrazy do 2 576 px / 3,75 MP ze współrzędnymi pikseli 1:1.¹⁴⁵

Benchmarki kodowania Opus 4.7 (kwiecień 2026):¹⁵¹

Opus 4.7 prowadzi w SWE-bench Verified o 12,7 punktu nad szeroko cytowanym baseline GPT-5-Codex oraz w SWE-bench Pro o 6,6 punktu nad GPT-5.4 (57,7%). W Terminal-Bench 2.0 GPT-5.3-Codex nadal nieznacznie wyprzedza GPT-5.4 (77,3% wobec 75,1%), a oba prowadzą przed Opus 4.7 (69,4%). Pozycja lidera w benchmarkach jest zmienna; przed wyborem na kilka kwartałów warto sprawdzić strony dostawców.

Domyślny model według planu (Claude Code):¹⁴⁷

Opus 4.7 wymaga Claude Code v2.1.111 lub nowszej; aby zaktualizować, należy uruchomić claude update.¹⁴⁷ Bedrock, Vertex i Foundry udostępniają Opus 4.7 przez jawne pełne nazwy modeli albo przypięcia ANTHROPIC_DEFAULT_OPUS_MODEL, a nie domyślnie przez alias opus.¹⁴⁷

Zmiany łamiące w Messages API w Opus 4.7 (widoczne dla wywołującego):¹⁴⁵

• Usunięto extended thinking budget_tokens. Zamiast tego należy użyć thinking: {type: "adaptive"}. Adaptive thinking jest domyślnie wyłączony; żądania bez pola thinking działają bez thinking.
• Ustawienie temperature, top_p albo top_k na wartość inną niż domyślna zwraca HTTP 400. Należy pominąć te parametry i sterować modelem przez prompt.
• Treść thinking jest domyślnie pomijana w odpowiedziach. Aby przywrócić widoczne rozumowanie, należy ustawić thinking.display: "summarized" (wymagane, jeśli produkt streamuje thinking do użytkowników).

Budżety zadań (beta header task-budgets-2026-03-13) pozwalają zasugerować modelowi docelową liczbę tokenów dla pełnej pętli agentic przez output_config.task_budget; minimum to 20K tokenów.¹⁴⁵

Opus 4.6 (legacy): Nadal dostępny jako claude-opus-4-6 z kontekstem 1M i maksymalnym output 128K. Warto rozważyć migrację do Opus 4.7 dla lepszego agentic coding. Opus 4.6 pierwotnie wydano 5 lutego 2026.⁷⁹¹⁴⁴ Od v2.1.117 (22 kwietnia 2026) subskrybenci Pro i Max domyślnie korzystają z effort high w Opus 4.6 i Sonnet 4.6 (wcześniej medium); Opus 4.7 pozostaje przy xhigh. Ta zmiana przywróciła inteligencję po obniżeniu effort z 4 marca → 7 kwietnia, opisanym w postmortem z 23 kwietnia.¹⁵²¹⁵³

Sonnet 4.6 (17 lutego 2026): Model zrównoważony; zastąpił Sonnet 4.5 jako domyślny w claude.ai i Claude Cowork.⁹³ Taka sama cena jak Sonnet 4.5 ($3/$15 za MTok). Lepsza wydajność agentic search przy niższym zużyciu tokenów. Obsługuje extended thinking, adaptive thinking oraz okno kontekstu 1M tokenów (beta). Maksymalny output 64K (górna granica 128K w v2.1.77).¹¹⁹ Granica wiedzy: sierpień 2025 (wiarygodna), styczeń 2026 (dane treningowe). ID modelu: claude-sonnet-4-6.

Claude Mythos Preview (7 kwietnia 2026): Frontier model w wersji research-preview do defensywnej pracy z cyberbezpieczeństwem, oferowany w ramach Project Glasswing.¹³⁹ Tylko na zaproszenie; nie jest ogólnie dostępny. Anthropic przedstawia Opus 4.7 jako celowo mniej zdolny niż Mythos w wymiarach cyber — to kompromis bezpieczeństwa — i otworzył Cyber Verification Program pod adresem https://claude.com/form/cyber-use-case dla uprawnionych badaczy bezpieczeństwa, którzy potrzebują podwyższonego dostępu.¹⁴⁶

Dlaczego te różnice cenowe mają znaczenie: Typowa sesja kodowania zużywa 50K–200K tokenów input i 10K–50K tokenów output. Z Haiku kosztuje to $0.10–$0.45 za sesję. Z Opus ta sama sesja kosztuje $0.50–$2.25, czyli 5× więcej. Opus warto rezerwować na naprawdę trudne problemy.¹

Kiedy używać którego modelu

Haiku: Używać dla subagents wykonujących eksplorację, proste wyszukiwania plików i szybkie pytania. Jest ~5× tańszy niż Opus i odpowiada szybciej. Idealny do zadań w tle, gdzie głębokie rozumowanie nie jest potrzebne.

Sonnet: Koń roboczy do codziennego developmentu, gdy koszt ma znaczenie. Obsługuje większość zadań kodowania: implementację funkcji, naprawianie błędów, pisanie testów, code review. Sonnet 4.6 zapewnia lepszy agentic search i wyższą efektywność tokenów w porównaniu z Sonnet 4.5, z obsługą adaptive thinking oraz oknem kontekstu 1M w standardowej cenie.⁹³ Od Opus 4.7 (16 kwietnia 2026) Claude Code domyślnie używa Opus tylko w planach Max i Team Premium; konta Pro, Team Standard, Enterprise oraz API zachowują Sonnet 4.6 jako domyślny model do czasu przejścia Enterprise i API na Opus 4.7 23 kwietnia 2026.¹⁴⁷ Sonnet warto wybierać, gdy potrzebne są tańsze tokeny, niższe opóźnienie albo ekonomia subagent.

Opus: Flagowy poziom od 16 kwietnia 2026 i domyślny model w planach Max oraz Team Premium.¹⁴⁴¹⁴⁷ Droższe rozumowanie warto rezerwować tam, gdzie się opłaca: decyzje architektoniczne, trudne debugowanie, rozumienie złożonych systemów, analiza bezpieczeństwa, praca agentic o długim horyzoncie. Opus 4.7 rozwiązuje 3× więcej zadań produkcyjnych w SWE-Bench niż Opus 4.6, osiąga 70% w CursorBench (wobec 58%) i podnosi rozwiązywalność o 13% w wewnętrznym benchmarku kodowania obejmującym 93 zadania.¹⁴⁴ Claude Code domyślnie ustawia effort xhigh dla Opus 4.7, możliwy do strojenia przez /effort (v2.1.111+).¹⁴⁶¹⁴⁷ Auto Mode jest dostępny dla subskrybentów Max w Opus 4.7 przez Anthropic API bez wymagania --enable-auto-mode; inne plany/dostawcy mają dostępność zależną od planu i kontroli administratora.¹⁴⁶ Kontekst 1M w standardowej cenie — bez dopłaty za długi kontekst. Zmiany zachowania, które warto znać: Opus 4.7 bardziej dosłownie wykonuje instrukcje, kalibruje długość odpowiedzi do złożoności zadania, domyślnie uruchamia mniej subagents i przyjmuje bardziej bezpośredni ton z mniejszą ilością sformułowań walidujących. Jeśli prompty zawierają rusztowanie wymuszające komunikaty o postępie pośrednim albo zachowanie typu double-check, warto spróbować je usunąć.¹⁴⁵

Opusplan: Tryb hybrydowy, który używa Opus do planowania (tam, gdzie jakość rozumowania ma największe znaczenie) i Sonnet do wykonania (tam, gdzie liczy się szybkość). Znakomity do złożonej refaktoryzacji, gdy potrzebny jest najlepszy plan, ale reasoning na poziomie Opus nie jest wymagany dla każdej pojedynczej edycji.

Przełączanie modeli

Podczas sesji:

> /model opus
> /model sonnet
> /model haiku

Przy starcie:

claude --model opus

Przez środowisko:

export ANTHROPIC_MODEL=opus

W settings.json:

{
  "model": "claude-sonnet-4-5-20250929"
}

Konkretnie dla subagents:

export CLAUDE_CODE_SUBAGENT_MODEL=haiku

Łańcuch modeli fallback (v2.1.166+): ustawienie fallbackModel konfiguruje do trzech modeli fallback, próbowanych po kolei, gdy model główny jest przeciążony lub niedostępny. Flaga --fallback-model (wcześniej tylko przełącznik w trakcie sesji) teraz działa także dla sesji interaktywnych od startu.¹⁷⁶

{
  "model": "claude-opus-4-8",
  "fallbackModel": ["claude-sonnet-4-6", "claude-haiku-4-5"]
}

Gdy API zwraca nieoczekiwany błąd non-retryable, Claude Code teraz ponawia także turę raz na modelu fallback, zanim pokaże awarię, dzięki czemu przejściowy problem modelu głównego degraduje się łagodnie zamiast porzucać turę.¹⁷⁶

Od v2.1.178 kompaktowanie również respektuje łańcuch fallback — jeśli model główny jest przeciążony lub niedostępny w trakcie kompaktowania, krok kompaktowania przechodzi na skonfigurowany łańcuch fallbackModel/--fallback-model zamiast powodować niepowodzenie tury. Dla długiego autonomicznego uruchomienia zamyka to lukę, w której możliwe do odzyskania kompaktowanie mogło zrzucić sesję przez przejściowy błąd modelu.¹⁷³

Rozszerzony kontekst

Dla dużych baz kodu albo długich sesji należy włączyć kontekst 1M tokenów:

claude --model sonnet[1m]
claude --model opus[1m]           # Opus 4.7 with 1M context

Albo w ramach sesji:

> /model sonnet[1m]
> /model opus[1m]

Opus 4.7, Opus 4.6 i Sonnet 4.6 zawierają pełne okno kontekstu 1M tokenów w standardowej cenie — bez dopłaty za długi kontekst.¹⁴⁸ Żądanie 900K tokenów jest rozliczane według tej samej stawki za token co żądanie 9K tokenów. Rabaty za prompt caching i batch processing obowiązują według standardowych stawek w całym oknie kontekstu.

W subskrypcjach Max, Team i Enterprise Opus z kontekstem 1M jest uwzględniony automatycznie — sufiks [1m] nie jest potrzebny (włączone domyślnie od v2.1.75, 13 marca 2026).¹¹⁷¹⁴⁷ W Pro kontekst 1M jest dostępny przez extra usage. Użytkownicy API i pay-as-you-go mają pełny dostęp 1M przy standardowych stawkach za token.¹⁴⁷

Aby wyłączyć warianty kontekstu 1M w selektorze modeli, należy ustawić CLAUDE_CODE_DISABLE_1M_CONTEXT=1.

Sprawdzanie bieżącego modelu

> /status

Polecenie pokazuje bieżący model, informacje o koncie, zastosowane ustawienia i inny stan sesji.

Etykiety selektora modeli (v2.1.51+): Selektor /model pokazuje teraz czytelne dla człowieka etykiety (np. „Sonnet 4.6”) zamiast surowych ID modeli dla przypiętych wersji, z podpowiedziami aktualizacji, gdy dostępne są nowsze wersje.⁹⁸

Fast Mode (v2.1.36+)

Fast mode zapewnia znacznie szybszy output z tego samego modelu; nie przełącza na tańszy model. Można go przełączyć podczas sesji poleceniem /fast.⁸⁶

> /fast            # Toggle fast mode on/off

Cennik (Opus 4.6 fast mode):

Fast mode jest research preview, działa tylko z Opus 4.6 i zapewnia ~2,5× szybszy output przy 6× cenie bazowej.¹⁴⁹ Włączenie /fast automatycznie przełącza sesję na Opus 4.6, jeśli używany był inny model; wyłączenie /fast pozostawia sesję na Opus 4.6 do czasu przełączenia przez /model. Fast mode nie jest dostępny w Opus 4.7, Sonnet, Haiku ani przez Bedrock/Vertex/Foundry. Wymaga włączonego extra usage, a w Team/Enterprise także włączenia przez administratora.

Kiedy używać fast mode: - Szybkie iterowanie po małych zmianach, gdy opóźnienie jest wąskim gardłem - Generowanie testów, boilerplate albo powtarzalnego kodu, gdzie szybkość jest ważniejsza niż koszt - Sekwencyjna praca przez listę podobnych zadań

Kiedy NIE używać fast mode: - Długotrwałe zadania agentic (koszt szybko rośnie przy stawkach 6x) - Praca subagent w tle (nikt nie czeka na output) - Sesje z ograniczonym budżetem

Fast mode w Opus 4.6 obejmuje pełne okno kontekstu 1M (v2.1.50+). Cennik fast mode jest płaski w całym kontekście 1M — bez dodatkowej dopłaty za długi kontekst.⁹⁶¹⁴⁹

Wskazówka ekspercka: Fast mode nie łączy się z opusplan (opusplan już miesza Opus i Sonnet; fast mode wpływa tylko na Opus 4.6). Fast mode warto używać bezpośrednio, gdy opóźnienie ma większe znaczenie niż koszt, oraz wyłączać go dla pracy autonomicznej lub wsadowej. /fast wymaga extra usage; administratorzy Team/Enterprise mogą musieć najpierw go włączyć (poprawka v2.1.37).⁸⁶¹⁴⁹

Kontrola effort (v2.1.111+, Opus 4.7)

Opus 4.7 wprowadza nowe pokrętło effort, które stroi kompromis między szybkością a inteligencją. Podczas sesji należy użyć /effort:

> /effort              # opens an interactive slider (arrow keys + Enter)
> /effort xhigh        # set directly

Claude Code domyślnie ustawia teraz effort xhigh dla Opus 4.7. xhigh działa tylko w Opus 4.7 — inne modele wracają do high. Claude Managed Agents obsługuje effort automatycznie; parametr effort jest koncepcją Messages API.¹⁴⁵¹⁴⁶

Auto Mode w Max (v2.1.111+)

Auto Mode — bezpieczniejszy zamiennik --dangerously-skip-permissions — jest dostępny dla subskrybentów Max w Opus 4.7 przez Anthropic API bez --enable-auto-mode.¹⁴⁶ Klasyfikator Sonnet-4.6 sprawdza każdą akcję przed wykonaniem, weryfikując zgodność intencji i bezpieczeństwo. Uwaga (v2.1.111+): flaga --enable-auto-mode została usunięta; sesję w Auto Mode należy uruchamiać przez --permission-mode auto. Auto Mode nie jest dostępny w Pro; według dokumentacji permission modes Anthropic jest bezpośredni w Anthropic API domyślnie. Bedrock/Vertex/Foundry (v2.1.158+): Auto Mode jest teraz opt-in w Opus 4.7 i Opus 4.8 na tych bramkach z CLAUDE_CODE_ENABLE_AUTO_MODE=1.¹⁷⁹

Własne reguły bez utraty domyślnych (v2.1.118+). Wcześniejsze wersje traktowały autoMode.allow, autoMode.soft_deny i autoMode.environment jako wybór albo-albo: zdefiniowanie własnej listy oznaczało utratę wbudowanych reguł bezpieczeństwa. Sentinel $defaults rozwiązuje ten problem — rozwija się inline do wbudowanej listy dokładnie w miejscu, w którym zostanie umieszczony, dzięki czemu można warstwowo dodawać własne reguły wokół nich:¹⁵²

// .claude/settings.json
{
  "autoMode": {
    "allow": [
      "Bash(npm test:*)",        // your additions, prepended
      "$defaults",                // built-in allow list inserted here
      "Bash(git push:origin/feature/*)"  // appended after
    ]
  }
}

Opt-in „Don’t ask again” (v2.1.118+). Prompt opt-in Auto Mode oferuje teraz opcję „Don’t ask again”, dzięki czemu częsti użytkownicy mogą ukryć wyjaśnienie bez skryptowania flagi.¹⁵²

Nowe polecenia w v2.1.105–v2.1.114¹⁴⁶¹⁵⁰

Session Recap (v2.1.108+)

Nowa funkcja na poziomie sesji, która pokazuje kontekst po powrocie do wstrzymanej sesji. Domyślnie włączona i możliwa do wyłączenia przez /config albo CLAUDE_CODE_ENABLE_AWAY_SUMMARY=0. Model może także wywoływać wbudowane slash commands (/init, /review, /security-review) przez narzędzie Skill — rozszerza to wzorzec subagent/skill.¹⁴⁶

Push Notifications (v2.1.110+)

Gdy Remote Control jest skonfigurowany z włączoną opcją „Push when Claude decides”, Claude może teraz według własnego uznania wysyłać mobilne push notifications przez nowe narzędzie push-notification. Łączy się to z istniejącą powierzchnią Remote Control mobile/web.¹⁴⁶ /context, /exit i /reload-plugins działają teraz także z klientów Remote Control.

Windows PowerShell Tool (v2.1.111+, rollout)

Claude Code stopniowo udostępnia natywne narzędzie Windows PowerShell. W Linux/macOS można je włączyć przez CLAUDE_CODE_USE_POWERSHELL_TOOL=1 (wymaga pwsh w PATH). W Windows ta sama zmienna kontroluje opt-in/opt-out podczas rollout.¹⁴⁶

Auto-approval w permission-mode (v2.1.119+). Polecenia narzędzia PowerShell mogą teraz otrzymywać auto-approval w permission mode tak samo jak polecenia Bash. Reguły allow, takie jak PowerShell(Get-*:*), oraz istniejąca składnia wzorców omijają teraz prompt dla operacji read-only, zapewniając ergonomię operatora, którą zespoły mają już w Linux/macOS.¹⁵²

Redukcja uprawnień: read-only Bash (v2.1.111+)

Wzorce read-only Bash z argumentami glob (np. ls *.ts, cat src/*.md) oraz polecenia zaczynające się od cd <project-dir> && nie wywołują już promptu o uprawnienia.¹⁴⁶ W połączeniu z /less-permission-prompts można oczekiwać znacznie mniejszej liczby przerw w codziennych workflow.

Distributed Tracing (v2.1.110+)

Sesje SDK i headless odczytują teraz TRACEPARENT oraz TRACESTATE ze środowiska, łącząc uruchomienia Claude Code z distributed traces. Warto zestawić to z OTEL_LOG_RAW_API_BODIES=1 (v2.1.111+), aby emitować pełne ciała żądań/odpowiedzi API jako zdarzenia logów OpenTelemetry do debugowania.¹⁴⁶

Dystrybucja natywnego binarium (v2.1.113+)¹⁵⁰

v2.1.113 zmienia sposób uruchamiania CLI: claude uruchamia teraz natywne binarium Claude Code przez opcjonalną zależność per platforma, zamiast uruchamiać dołączony JavaScript. Polecenia instalacji i aktualizacji pozostają takie same, a zespoły nie muszą zmieniać skryptów rollout.

Skróty edytora promptów (v2.1.113+)¹⁵⁰

Edytor promptów zyskuje nawigację w stylu readline w wejściu wielowierszowym oraz przewijanie viewportu fullscreen:

Są domyślnie włączone. Konfiguracja keybinding nie jest wymagana.

Timeout zatrzymanego subagent (v2.1.113+)¹⁵⁰

Subagents, które zatrzymają się w połowie streamu, kończą teraz błędem z jasnym komunikatem po 10 minutach zamiast wisieć bezgłośnie. Warto połączyć to z CLAUDE_STREAM_IDLE_TIMEOUT_MS (v2.1.84+) dla szerszego pokrycia zablokowanych procesów w streamujących API.

Poprawka stabilności v2.1.114¹⁵⁰

v2.1.114 (18 kwietnia 2026) zawiera jedną poprawkę: okno dialogowe uprawnień mogło ulec awarii, gdy teammate z agent-teams zażądał uprawnienia narzędzia. Warto zaktualizować, jeśli używane są Agent Teams.

Ile kosztuje Claude Code?

Zrozumienie i kontrolowanie kosztów jest kluczowe dla zrównoważonego korzystania z Claude Code. Patrz również Wybór modelu, aby poznać możliwości modeli, oraz Frameworki decyzyjne, aby wybrać odpowiedni model do danego zadania.

Wyświetlanie kosztów

> /cost

Wynik:

Total cost:            $0.55
Total duration (API):  6m 19.7s
Total duration (wall): 6h 33m 10.2s
Total code changes:    247 lines added, 89 lines removed

Użytkownicy z subskrypcją widzą w /cost szczegółowy podział według modelu i trafień w pamięci podręcznej, co pokazuje dokładnie, które modele zużyły tokeny i ile zostało obsłużone z pamięci podręcznej (v2.1.92+).¹³⁷

Plany subskrypcyjne

Limity szybkości (sierpień 2025): Anthropic wprowadziło tygodniowe limity szybkości dla subskrybentów płatnych planów. Subskrybenci Max mogą dokupić dodatkowy limit ponad standardowe ograniczenia po standardowych stawkach API.¹⁴

Podwojenie limitów szybkości (6 maja 2026): Podczas wydarzenia Code with Claude SF firma Anthropic podwoiła pięciogodzinne limity szybkości Claude Code w planach Pro, Max, Team oraz w planach Enterprise rozliczanych za stanowisko, zniosła ograniczenia w godzinach szczytu na kontach Pro i Max oraz „znacząco” zwiększyła limity szybkości API dla modeli Claude Opus. Zabezpieczeniem mocy obliczeniowej jest umowa SpaceX Colossus 1: „ponad 300 megawatów nowej mocy (ponad 220 000 kart NVIDIA GPU) w ciągu miesiąca.”¹⁵⁷

Cennik tokenów API (kwiecień 2026)¹¹⁴⁴

Dla użytkowników rozliczanych przez API, cennik za milion tokenów:

Cennik kontekstu 1M (kwiecień 2026): Opus 4.7, Opus 4.6, Sonnet 4.6 oraz Mythos Preview obejmują 1M w standardowych stawkach za MTok — bez dopłaty za długi kontekst.¹⁴⁸ Jest to niedawna konsolidacja; wcześniejsze wytyczne dotyczące Opus 4.6 lub Sonnet 4.6 płacących 2× za wejście / 1,5× za wyjście powyżej 200K tokenów wejściowych nie są już aktualne. Starszy Opus 4.5 i wcześniejsze modele zachowują swoją pierwotną strukturę cenową.

Cennik rezydencji danych: Wskazanie wnioskowania wyłącznie w USA przez inference_geo dodaje mnożnik 1,1× do całego cennika tokenów, włącznie z odczytami i zapisami pamięci podręcznej (modele Opus 4.6+).¹⁴⁸

Buforowanie promptów znacząco redukuje koszty powtarzających się danych wejściowych: zapisy do pamięci podręcznej kosztują 1,25× stawki bazowej (pamięć 5-minutowa) lub 2× (pamięć 1-godzinna), ale odczyty z pamięci kosztują tylko 0,1×, co daje 90% oszczędności. W przypadku systemów RAG i asystentów programistycznych z powtarzającym się kontekstem, buforowanie może zredukować koszty o 88-95%.

Wsadowe API oferuje 50% rabatu z czasem realizacji 24 godziny dla zadań niewymagających pilności, takich jak nocne zestawy testów.

Polityka wielu kont⁵²

Czy można posiadać wiele kont Claude? Tak, w uzasadnionych przypadkach. Anthropic wyraźnie zezwala na wiele kont, gdy służą one różnym celom.

Co jest dozwolone:

Limity techniczne: - Do 3 kont można zweryfikować tym samym numerem telefonu - Wiele płatnych subskrypcji z tego samego IP/sieci jest wyraźnie obsługiwane - Konta są całkowicie odrębne; brak przenoszenia rozmów lub projektów między nimi

Co jest zabronione (zgodnie z Polityką użytkowania): - Tworzenie kont w celu obejścia banów po wcześniejszym zablokowaniu - Koordynowanie złośliwej aktywności między kontami w celu uniknięcia wykrycia - Używanie wielu kont w celu obejścia limitów szybkości lub kredytów planu darmowego

Uwaga z praktyki: W styczniu 2026 power user Jeffrey Emanuel (@doodlestein) miał 22 konta Max automatycznie oznaczone i tymczasowo zablokowane. Pracownik Anthropic Thariq (@trq212) rozwiązał sprawę w ciągu 4 godzin po potwierdzeniu uzasadnionego użycia. Jeśli ktoś korzysta z Claude Code intensywnie zarówno do pracy, jak i projektów prywatnych na wielu kontach, to dokładnie do tego usługa została zaprojektowana, ale nie należy próbować oszukiwać systemu.

W razie wątpliwości: Proszę skontaktować się z Wsparciem Anthropic, aby pisemnie potwierdzić swoją konkretną konfigurację.

Czynniki kosztowe

Przykłady kosztów z praktyki

Wskazówka oszczędnościowa: Używanie Haiku do subagentów eksploracyjnych i Sonnet do implementacji zazwyczaj redukuje koszty o 40-50% w porównaniu do używania Sonnet do wszystkiego.

Zarządzanie kosztami zespołu

Zalecane TPM/RPM według wielkości zespołu:

Ukryte opłaty za narzędzia

Poza cennikiem za token, niektóre narzędzia generują osobne opłaty:⁹

W pętlach agenta to się sumuje. 100-iteracyjny cykl debugowania z użyciem Bash kosztuje ~24 500 dodatkowych tokenów wejściowych w samym narzucie.

Strategie oszczędzania kosztów

1. Używać Haiku do subagentów: Większość eksploracji nie wymaga Sonnet
2. Włączyć buforowanie promptów: Domyślne, ale warto sprawdzić, czy nie zostało wyłączone
3. Ustawić maksymalną liczbę tur: claude --max-turns 5 zapobiega niekontrolowanym rozmowom
4. Korzystać z trybu planowania do eksploracji: Brak wykonania = brak przypadkowych kosztownych operacji
5. Kompaktować proaktywnie: Mniejszy kontekst = mniej tokenów
6. Ograniczyć wyjście: export CLAUDE_CODE_MAX_OUTPUT_TOKENS=2000
7. Wsadowe API dla zadań niepilnych: 50% rabatu na tokeny wejściowe i wyjściowe

Monitorowanie zużycia

• Konsola Claude: platform.claude.com (wymaga roli Admin lub Billing)
• Limity przestrzeni roboczej: Ustawianie limitów wydatków na przestrzeń roboczą
• Bedrock/Vertex: Korzystanie z natywnego monitorowania kosztów chmury
• LiteLLM: Do szczegółowego śledzenia per użytkownik z dostawcami zewnętrznymi

Zużycie tokenów w tle

Niektóre operacje zużywają tokeny w tle: - Podsumowywanie rozmów dla /resume - Polecenia /cost i /status - Automatyczne kompaktowanie

Zazwyczaj poniżej $0,04 na sesję.

Claude Code Analytics API (Team/Enterprise)⁴⁶

Programowy dostęp do analityki użycia Claude Code i metryk produktywności organizacji za pośrednictwem Admin API.

Endpoint: GET /v1/organizations/usage_report/claude_code

Wymagania: - Klucz Admin API (sk-ant-admin...) - Plan Team lub Enterprise - Rola Admin, Billing lub Developer

Dostępne metryki:

Przykładowe żądanie:

curl "https://api.anthropic.com/v1/organizations/usage_report/claude_code?starting_at=2026-01-15" \
  -H "x-api-key: sk-ant-admin..." \
  -H "anthropic-version: 2023-06-01"

Przypadki użycia: - Analiza produktywności programistów (sesje, commity, PR) - Metryki użycia narzędzi (wskaźniki akceptacji/odrzucenia dla Edit, Write itp.) - Śledzenie kosztów i alokacja między zespołami - Uzasadnienie ROI dla narzędzi AI do kodowania

Uwaga: Dane pojawiają się w ciągu 1 godziny od zakończenia aktywności. Dla zachowania spójności w odpowiedziach uwzględniane są wyłącznie dane starsze niż 1 godzina.

Ramy decyzyjne

Sama wiedza o istnieniu funkcji nie wystarczy. Trzeba wiedzieć, kiedy użyć każdej z nich. Te drzewa decyzyjne przekształcają wiedzę w działanie.

Którego modelu należy użyć?

START → Czy zadanie jest proste? (wyszukiwanie plików, szybkie pytanie, formatowanie)
         │
         ├── TAK → Użyj Haiku
         │         Koszt: ~$0.03/zadanie
         │         Szybkość: Najwyższa
         │
         └── NIE → Czy wymaga głębokiego rozumowania?
                  (architektura, złożone debugowanie, analiza bezpieczeństwa)
                  │
                  ├── TAK → Użyj Opus 4.7 (domyślnie xhigh effort)
                  │         Koszt: ~$2.00/zadanie
                  │         Jakość: Najwyższa (1M kontekstu w standardowej cenie, adaptacyjne rozumowanie)
                  │
                  └── NIE → Użyj Sonnet
                           Koszt: ~$0.75/zadanie
                           Równowaga: Najlepsza, gdy koszt ma znaczenie

Zasada praktyczna: Opus 4.7 jest domyślny dla Max oraz Team Premium. W planach Pro/Team Standard/Enterprise/API domyślny jest Sonnet 4.6 (Enterprise + Anthropic API przechodzą na Opus 4.7 23 kwietnia 2026).¹⁴⁷ Warto zejść do Haiku dla subagentów. Należy eskalować do Opus, gdy odpowiedź Sonnet wydaje się powierzchowna. Dzięki agent teams (v2.1.32+) Opus może koordynować wiele agentów pracujących równolegle nad różnymi podzadaniami.⁷⁹

Command, Skill, Subagent czy Agent Team?

Czy chcesz mieć jawną kontrolę nad tym, kiedy się uruchomi?
│
├── TAK → Użyj Slash Command
│         Przykład: /deploy, /test, /security-review
│         Ty go wywołujesz. Ty kontrolujesz moment.
│
└── NIE → Czy ekspertyza ma się stosować automatycznie w oparciu o kontekst?
         │
         ├── TAK → Użyj Skill
         │         Przykład: wzorce bezpieczeństwa, reguły domenowe, standardy kodu
         │         Claude rozpoznaje kontekst i stosuje ekspertyzę.
         │
         └── NIE → Czy praca wymaga odizolowanego kontekstu?
                  │
                  ├── TAK → Czy jest jedno podzadanie, czy wiele równoległych?
                  │         │
                  │         ├── JEDNO → Użyj Subagent (narzędzie Task)
                  │         │         Przykład: głęboka eksploracja, analiza równoległa
                  │         │         Zapobiega rozrostowi kontekstu w głównej rozmowie.
                  │         │
                  │         └── WIELE → Użyj Agent Team (v2.1.32+)
                  │                   Przykład: 5 agentów przegląda jednocześnie różne moduły
                  │                   Opus koordynuje; każdy agent pracuje niezależnie.
                  │
                  └── NIE → Po prostu zaprompruj bezpośrednio
                           Nie wszystko wymaga abstrakcji.

Hook czy prompt?

Czy działanie MUSI zawsze nastąpić, niezależnie od oceny Claude?
│
├── TAK → Użyj Hook (deterministyczny)
│         Przykłady:
│         - Formatowanie kodu po każdej edycji
│         - Logowanie wszystkich poleceń bash
│         - Blokowanie dostępu do plików .env
│         Claude nie może pominąć, zapomnieć ani zdecydować inaczej.
│
└── NIE → Użyj Prompt (probabilistyczny)
         Przykłady:
         - „Rozważ dodanie testów"
         - „Pomyśl o przypadkach brzegowych"
         - „Przejrzyj pod kątem bezpieczeństwa, jeśli jest to istotne"
         Claude decyduje na podstawie kontekstu.

Kiedy używać rozszerzonego myślenia (extended thinking)?

Czy to naprawdę trudny problem?
│
├── Decyzja architektoniczna z wieloma kompromisami → TAK, użyj myślenia
├── Złożone debugowanie z niejasną przyczyną źródłową → TAK, użyj myślenia
├── Analiza bezpieczeństwa wymagająca ostrożnego rozumowania → TAK, użyj myślenia
├── Zrozumienie nieznanej bazy kodu → TAK, użyj myślenia
│
├── Rutynowa poprawka błędu → NIE, pomiń myślenie
├── Prosty refaktoring → NIE, pomiń myślenie
├── Formatowanie kodu → NIE, pomiń myślenie
└── Szybkie pytania → NIE, pomiń myślenie

Przełączanie za pomocą Alt+T w trakcie sesji. Wyższe budżety myślenia kosztują więcej; warto zacząć od minimum i zwiększać tylko wtedy, gdy odpowiedzi wydają się pospieszne.

Adaptacyjne myślenie Opus 4.6: Opus 4.6 automatycznie dostosowuje głębokość myślenia do złożoności problemu. Dla większości zadań jawna kontrola budżetu myślenia nie jest konieczna — Opus skaluje się w górę przy trudnych problemach i pozostaje szybki przy prostych. Ręczne przełączanie myślenia jest najbardziej przydatne przy Sonnet, gdy chce się wymusić głębszą analizę.

Który sposób wykonania?

Gdzie powinna odbyć się ta praca?
│
├── Wymaga TWOICH lokalnych plików i narzędzi
│   │
│   ├── Praca interaktywna, iteracyjna → Główna sesja REPL
│   ├── Jednorazowe zadanie skryptowe → claude -p "prompt" (tryb print)
│   ├── Automatyzacja CI/CD → claude -p --json (nieinteraktywny + ustrukturyzowane wyjście)
│   └── Równoległe zadania izolowane → Subagenty przez narzędzie Task
│
├── Wymaga CUDZEGO środowiska
│   │
│   └── Zdalna baza kodu lub serwer → Background agent (chmura)
│
└── Nie wymaga żadnego środowiska
    │
    ├── Badania lub analiza → Subagent typu Explore
    └── Ekstrakcja treści z sieci → narzędzia WebFetch / WebSearch

Agent teams, subagenty czy sesje równoległe?

Czy potrzebujesz wielu agentów pracujących nad powiązanymi podzadaniami?
│
├── TAK → Czy podzadania są niezależne (bez współdzielonego stanu)?
│         │
│         ├── TAK → Czy mogą współdzielić tę samą bazę kodu?
│         │         │
│         │         ├── TAK → Użyj Agent Team (v2.1.32+)
│         │         │         Opus koordynuje. Agenci dzielą dostęp do repo.
│         │         │         Przykład: „Przejrzyj moduły auth, API i DB równolegle"
│         │         │
│         │         └── NIE → Użyj sesji równoległych (osobne terminale)
│         │                  Każda ma własny katalog roboczy.
│         │                  Przykład: „Napraw repo-A i repo-B jednocześnie"
│         │
│         └── NIE → Użyj sekwencyjnych subagentów
│                  Wyniki jednego zasilają następny.
│                  Przykład: „Explore → Plan → Implement"
│
└── NIE → Użyj pojedynczego subagenta lub głównej sesji REPL

Który typ hooka?

Jaki rodzaj automatyzacji jest potrzebny?
│
├── Uruchomienie polecenia powłoki przy określonym zdarzeniu?
│   │
│   └── Użyj Command Hook
│       Wyzwalacz: PreToolUse, PostToolUse, Notification, Stop, SubagentStop
│       Przykład: „Uruchom prettier po każdej edycji pliku"
│       Konfiguracja: hooks.PostToolUse[].command = "prettier --write $FILE"
│
├── Modyfikacja system promptu Claude w oparciu o kontekst?
│   │
│   └── Użyj Prompt Hook (v2.1.35+)
│       Wyzwalacz: Te same zdarzenia
│       Przykład: „Wstrzyknij reguły projektu podczas pracy w /src/auth/"
│       Konfiguracja: hooks.PreToolUse[].prompt = "When editing auth files..."
│
└── Niech Claude dokona oceny, zanim przejdzie dalej?
    │
    └── Użyj Agent Hook (v2.1.35+)
        Wyzwalacz: Te same zdarzenia
        Przykład: „Oceń, czy to polecenie bash jest bezpieczne przed uruchomieniem"
        Konfiguracja: hooks.PreToolUse[].agent = { prompt: "Is this safe?" }

Kiedy używać /fast?

Czy szybkość odpowiedzi jest teraz ważniejsza niż głębia?
│
├── TAK → Użyj /fast
│         Ten sam model Opus 4.6, szybsze wyjście
│         Dobry do: szybkich pytań, prostych edycji, wyjaśnień kodu,
│                   wyszukiwania plików, zadań formatujących
│
└── NIE → Pozostań w trybie normalnym
         Dobry do: decyzji architektonicznych, złożonego debugowania,
                   przeglądów bezpieczeństwa, refaktoringów wielu plików,
                   wszystkiego, co wymaga głębokiego rozumowania

/fast przełącza tryb szybki dla bieżącej sesji. Używa tego samego modelu (Opus 4.6) ze zoptymalizowaną szybkością wyjścia — NIE przełącza na tańszy model.

Jak działa system uprawnień?

System uprawnień Claude Code zapewnia precyzyjną kontrolę nad tym, które operacje mogą zostać wykonane. Zrozumienie go ma kluczowe znaczenie zarówno dla bezpieczeństwa, jak i wydajności pracy. Zobacz także wdrożenie Enterprise, aby poznać zarządzane ustawienia wymuszające uprawnienia w całej organizacji.

Poziomy uprawnień

Narzędzia tylko do odczytu (zatwierdzane automatycznie): - Read - odczyt zawartości plików - Glob - wyszukiwanie plików według wzorca - Grep - przeszukiwanie zawartości plików - WebSearch - wyszukiwanie w sieci - LSP - inteligencja kodu (przejście do definicji, znajdowanie odwołań, dokumentacja po najechaniu kursorem)¹⁸

Możliwości narzędzia LSP (v2.0.74+): narzędzie LSP zapewnia inteligencję kodu podobną do IDE: - Przejście do definicji: skok do miejsca, w którym zdefiniowano symbol - Znajdowanie odwołań: lista wszystkich użyć symbolu w całej bazie kodu - Dokumentacja po najechaniu kursorem: informacje o typie i dokumentacja dowolnego symbolu - Działa z TypeScript, Python, Go, Rust oraz innymi językami z obsługą LSP - Wymaga dostępnego serwera językowego (zwykle instalowanego razem z toolchainem)

Narzędzia modyfikacji (wymagają zatwierdzenia): - Edit - modyfikacja istniejących plików - Write - tworzenie nowych plików - Bash - wykonywanie poleceń powłoki - WebFetch - pobieranie zawartości URL - NotebookEdit - modyfikacja notebooków Jupyter

Przy pierwszym uruchomieniu narzędzia modyfikacji Claude Code prosi o zatwierdzenie. Zatwierdzenia obowiązują przez całą sesję, chyba że wyraźnie skonfigurowano inaczej.

Tryby uprawnień

Pliki konfiguracyjne umożliwiające wykonywanie kodu wymagają teraz potwierdzenia nawet w trybie acceptEdits (v2.1.160). acceptEdits automatycznie zatwierdza zwykłe edycje, ale od v2.1.160 zatrzymuje się i prosi o potwierdzenie przed zapisem plików, które mogą nadawać możliwość cichego wykonywania poleceń: plików startowych powłoki (.zshenv, .zlogin, .bash_login), ~/.config/git/ oraz konfiguracji narzędzi buildowych (.npmrc, .yarnrc*, bunfig.toml, .bazelrc, .pre-commit-config.yaml, .devcontainer/ i podobnych). Powód jest taki, że edycja któregokolwiek z nich zmienia następną powłokę, instalację lub commit w wektor wykonania, dlatego nawet w trybie zaufanego projektu, który poza tym przepuszcza edycje, pojawia się celowa bramka. To ten sam model zagrożeń co istniejące zabezpieczenia zapisu .claude/, .git/ i .vscode/, rozszerzony na szerszą klasę plików typu „edycja staje się wykonaniem”.¹⁷⁸

Auto Mode (v2.1.85+): bezpieczniejszy zamiennik --dangerously-skip-permissions. Osobny model klasyfikujący (Sonnet 4.6) sprawdza każdą akcję przed wykonaniem, weryfikując, czy odpowiada intencji użytkownika i jest bezpieczna.¹²⁴

Jak to działa: - Akcje tylko do odczytu oraz edycje plików w katalogu roboczym są zatwierdzane automatycznie - Niestandardowe reguły allow/deny rozstrzygane są jako pierwsze - Wszystko pozostałe trafia do klasyfikatora w celu oceny - W razie blokady Claude automatycznie próbuje alternatywnego podejścia

Domyślnie automatycznie blokowane są: curl | bash, force-push do main, wdrożenia/migracje produkcyjne, masowe usuwanie w chmurze, zmiany IAM/uprawnień, wysyłanie danych wrażliwych na zewnątrz.¹²⁵

Wyłącznik bezpieczeństwa: 3 kolejne blokady lub 20 blokad łącznie w sesji powoduje powrót do ręcznego proszenia o zatwierdzenie.¹²⁵

# Enable at startup
claude --enable-auto-mode

# Or cycle into it during a session
Shift+Tab  # Cycles through: default → acceptEdits → auto → plan

Dostępność: najpierw użytkownicy planu Team, następnie Enterprise i API. Wymaga Sonnet 4.6 lub Opus 4.6.¹²⁴

YOLO Mode (v2.0.68+): do w pełni autonomicznej pracy bez klasyfikatora bezpieczeństwa należy użyć flagi --dangerously-skip-permissions. Flaga odpowiada „tak” na wszystko: edycje plików, polecenia bash, wszystkie wywołania narzędzi. Słowo „dangerous” jest celowe. Auto Mode jest zalecaną alternatywą dla większości przypadków użycia.⁵⁴

claude --dangerously-skip-permissions

Ustawienie trybu przez CLI:

claude --permission-mode auto  # or acceptEdits, plan, bypassPermissions

Przełączanie w trakcie sesji:

Shift+Tab  # Cycles through modes

W settings.json:

{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

Składnia reguł uprawnień

Precyzyjne reguły kontrolują konkretne operacje. Reguły są oceniane po kolei: wygrywa pierwsze dopasowanie.

Wzorce poleceń Bash:

{
  "allow": [
    "Bash(npm run build)",
    "Bash(npm run test:*)",
    "Bash(git commit:*)",
    "Bash(make:*)"
  ],
  "deny": [
    "Bash(rm -rf:*)",
    "Bash(sudo:*)",
    "Bash(curl|wget:*)"
  ]
}

Gwiazdka zapewnia dopasowanie prefiksu: Bash(npm run test:*) pozwala na npm run test, npm run test:unit i npm run test:integration.

Ważne ograniczenie: wzorce Bash dopasowują tylko prefiksy, nie regex. Wzorzec taki jak Bash(curl http:*) nie dopasuje curl -X GET http://..., ponieważ opcje znajdują się przed URL. Aby blokowanie było niezawodne, należy odmówić całemu poleceniu: Bash(curl:*).

Wzorce operacji na plikach:

{
  "allow": [
    "Edit(src/**)",
    "Write(src/**)",
    "Read(docs/**)"
  ],
  "deny": [
    "Read(.env*)",
    "Read(secrets/**)",
    "Edit(.git/**)",
    "Edit(node_modules/**)"
  ]
}

Składnia ścieżek: - Ścieżki względne: Edit(src/**) - względem katalogu roboczego - Bezwzględne od pliku ustawień: Edit(/build/**) - względem lokalizacji pliku ustawień - Prawdziwie bezwzględne: Edit(//tmp/**) - zaczyna się od // - Katalog domowy: Read(~/.zshrc)

Wzorce narzędzi MCP:

{
  "allow": [
    "mcp__github",
    "mcp__database__query",
    "mcp__myserver__*"
  ],
  "deny": [
    "mcp__dangerous_server",
    "mcp__untrusted__*"
  ]
}

Należy użyć składni wieloznacznej mcp__server__*, aby zezwolić na wszystkie narzędzia z konkretnego serwera MCP albo je zablokować.³² Składnia wieloznaczna przydaje się do szybkiego włączania wszystkich narzędzi z zaufanych serwerów lub blokowania całych serwerów z niezaufanych źródeł.

Od v2.1.166 reguły deny akceptują również glob w pozycji nazwy narzędzia: samo "*" w slocie nazwy narzędzia odmawia dostępu do wszystkich narzędzi, dzięki czemu można zablokować wszystko, a następnie przywrócić zezwolenie dla wąskiego zestawu. Reguły allow natomiast odrzucają globy spoza MCP — nie można w ten sam sposób szeroko zezwolić na wszystko, co utrzymuje domyślnie restrykcyjną postawę.¹⁷⁶

Dopasowywanie na poziomie parametrów — Tool(param:value) (v2.1.178):

Poza nazwą narzędzia reguła może dopasowywać parametry wejściowe narzędzia, z * jako symbolem wieloznacznym dla wartości:

{
  "deny": [
    "Agent(model:opus)"
  ]
}

Agent(model:opus) blokuje każdego subagenta uruchamianego w poziomie Opus — odmówione zostaje samo uruchomienie, a nie tylko prompt z prośbą o unikanie go. Rozszerza to kontrolę uprawnień z poziomu „które narzędzie” do poziomu „jak jest wywoływane”, jako deterministyczna reguła zamiast prośby na poziomie promptu. Łączy się to z zarządzanym ustawieniem enforceAvailableModels: allowlist definiuje, które poziomy modeli istnieją w sesji, a reguły Tool(model:...) ograniczają, jak subagents mogą z nich korzystać.¹⁷³

Wzorce WebFetch:

{
  "allow": [
    "WebFetch(domain:github.com)",
    "WebFetch(domain:api.example.com)"
  ]
}

Dodatkowe katalogi

Rozszerzenie dostępu Claude poza bieżący projekt:

{
  "permissions": {
    "additionalDirectories": [
      "../shared-lib",
      "../docs",
      "~/reference-projects/design-system"
    ]
  }
}

Dodatkowe katalogi są niezbędne w monorepo albo wtedy, gdy Claude musi odwoływać się do kodu w katalogach równorzędnych.

Tryb sandbox

Włączenie izolacji systemu plików i sieci:

> /sandbox

Albo konfiguracja w ustawieniach:

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"],
    "network": {
      "allowUnixSockets": ["~/.ssh/agent-socket"],
      "allowLocalBinding": true,
      "deniedDomains": ["pastebin.com", "transfer.sh", "0x0.st"]
    }
  }
}

W sandboxie: - Dostęp do systemu plików ograniczony do katalogu projektu - Dostęp do sieci kontrolowany - Niektóre polecenia wyłączone z ograniczeń sandboxa - Polecenia Bash zatwierdzane automatycznie, jeśli autoAllowBashIfSandboxed ma wartość true

Wskazówka ekspercka: tryb sandbox świetnie sprawdza się przy uruchamianiu Claude na niezaufanych bazach kodu. Warto go włączyć podczas eksplorowania nieznanych projektów albo gdy potrzebna jest dodatkowa warstwa ochrony. Wewnętrzne testy Anthropic wykazały, że sandboxing zmniejsza liczbę próśb o uprawnienia o 84%.³⁸ Sandbox używa prymitywów na poziomie systemu operacyjnego (macOS seatbelt, Linux bubblewrap) do izolacji systemu plików i sieci, więc nawet skuteczne prompt injection pozostaje w pełni odizolowane. Anthropic udostępnił runtime sandboxa jako open source dla zespołów budujących własnych agentów.⁸²

Uwagi dotyczące bezpieczeństwa (v2.1.34+): polecenia wyłączone z sandboxingu przez sandbox.excludedCommands lub dangerouslyDisableSandbox mogły wcześniej omijać regułę pytania o uprawnienie Bash, gdy włączone było autoAllowBashIfSandboxed; zostało to naprawione w v2.1.34.⁸⁷ Od v2.1.38 zapisy do .claude/skills są blokowane w trybie sandbox, co zapobiega modyfikowaniu definicji skills przez prompt injection.⁸⁸ v2.1.77 dodaje ustawienie systemu plików sandboxa allowRead, które ponownie zezwala na dostęp do odczytu w regionach denyRead — przydatne, gdy trzeba zablokować większość drzewa katalogów, ale dopuścić konkretne podkatalogi.¹¹⁹

Wyjątek konfiguracji agentów .claude/ (v2.1.121+): --dangerously-skip-permissions nie prosi już o zatwierdzenie zapisów do .claude/skills/, .claude/agents/ i .claude/commands/.¹⁵⁴

Rozwiązywanie zagnieżdżonych .claude/ (v2.1.178): skills w zagnieżdżonych katalogach .claude/skills ładują się teraz automatycznie podczas pracy na plikach pod danym katalogiem, a nie tylko z katalogu głównego repo; w razie kolizji nazw zagnieżdżony skill jest dostępny jako <dir>:<name>, więc oba pozostają dostępne. Reszta powierzchni projektu rozwiązywana jest tak samo — gdy nazwa agenta, workflow albo stylu wyjścia koliduje między zagnieżdżonymi katalogami .claude/, wygrywa element najbliższy katalogowi roboczemu, a zapis workflow w zakresie projektu trafia do najbliższego istniejącego .claude/workflows/. W monorepo albo repo-of-repos daje to narzędzia per pakiet, które aktywują się w kontekście zamiast jednej płaskiej powierzchni globalnej.¹⁷³

Niestandardowe ścieżki bubblewrap i socat (v2.1.133+): zarządzane ustawienia sandbox.bwrapPath i sandbox.socatPath pozwalają administratorom wskazać wdrożeniom Linux/WSL niestandardowe lokalizacje binariów bubblewrap i socat. Przydaje się to, gdy dystrybucje instalują te narzędzia poza $PATH albo gdy organizacja dostarcza własne, wzmocnione buildy.¹⁶⁰

Wzmocnienia bezpieczeństwa w v2.1.113:¹⁵⁰

• sandbox.network.deniedDomains blokuje konkretne hosty nawet wtedy, gdy szerszy wildcard allowedDomains normalnie by je dopuścił. Blocklisty warto używać do odcinania pastebinów, miejsc zrzutu plików lub znanych złych hostów bez przepisywania całej polityki allow.
• Reguły deny dla poleceń opakowujących. Reguły deny Bash dopasowują teraz polecenia opakowane w env, sudo, watch, ionice, setsid i podobne wrappery exec. Reguły takie jak Bash(rm:*) wychwytują teraz env rm -rf, sudo rm -rf oraz pokrewne wzorce obejścia.
• Reguły allow Bash(find:*) nie zatwierdzają już automatycznie find -exec ani find -delete. Te flagi wykonują polecenia i usuwają pliki, więc Claude Code kieruje je przez zwykłą ścieżkę uprawnień.
• Ochrona przed usuwaniem w macOS. Reguły allow Bash(rm:*) traktują teraz /private/etc, /private/var, /private/tmp i /private/home jako niebezpieczne cele usuwania. /var, /etc i /tmp są symlinkami do /private/, więc poprzedni kształt reguły pomijał cele kanoniczne.

Jak działają hooks?

Hooks wykonują deterministyczne polecenia shell w określonych punktach przepływu pracy Claude Code. W przeciwieństwie do proszenia Claude o wykonanie działań, hooks gwarantują wykonanie niezależnie od zachowania modelu. Są niezbędne do egzekwowania standardów zespołowych i automatyzowania powtarzalnych zadań. Zobacz ramy decyzyjne, aby zapoznać się z drzewem decyzyjnym „Który typ Hook?” obejmującym command, prompt i agent hooks.

Dlaczego hooks zamiast prompts: Polecenie Claude „zawsze uruchamiaj Prettier po edycji plików” czasem działa. Ale Claude może zapomnieć, nadać priorytet szybkości albo uznać zmianę za „zbyt małą”. Hooks gwarantują wykonanie: każde Edit lub Write uruchamia formatter, za każdym razem, bez wyjątków. W przypadku zgodności, bezpieczeństwa i standardów zespołowych deterministyczne rozwiązania wygrywają z probabilistycznymi.⁴

Dostępne zdarzenia

Konfiguracja Hook

Zdefiniuj hooks w settings.json albo w dedykowanym hooks.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$FILE_PATH\""
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/validate-bash.sh"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/inject-context.sh"
          }
        ]
      }
    ]
  }
}

Matchers

Pole matcher określa, które narzędzia wyzwalają hook:

{"matcher": "*"}              // Match all tools
{"matcher": "Bash"}           // Match Bash only
{"matcher": "Edit|Write"}     // Match Edit or Write
{"matcher": "mcp__github"}    // Match MCP server tools
{"matcher": ""}               // Match for events without tools (like UserPromptSubmit)

Protokół input/output Hook

Hooks otrzymują JSON na stdin:

{
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite"
  },
  "session_id": "abc-123"
}

Wzbogacenie zdarzeń hook (v2.1.69+): Wszystkie zdarzenia hook zawierają teraz pola agent_id i agent_type, gdy są wyzwalane z subagenta lub sesji --agent, a także pole worktree w poleceniach status line hook.¹¹⁰

Hooks Stop/SubagentStop (v2.1.47+) otrzymują dodatkowe pole last_assistant_message zawierające końcowy tekst odpowiedzi Claude, dzięki czemu hooks mogą sprawdzić output bez parsowania plików transkryptu:

{
  "session_id": "abc-123",
  "last_assistant_message": "I've completed the refactoring. Here's what changed..."
}

Miękka informacja zwrotna bez blokady (v2.1.163+): Hooks Stop i SubagentStop mogą zwracać hookSpecificOutput.additionalContext w swoim outputcie JSON, aby przekazać Claude informację zwrotną i utrzymać turę w toku, bez oznaczania odpowiedzi jako błędu hook. Wcześniej jedyną realną dźwignią Stop hook była blokada exit-2 (odczytywana jako błąd i wliczana do limitu kolejnych blokad); additionalContext dodaje kanał sterowania dla wskazówek typu „to zostało pominięte, kontynuuj”, który nie walczy z pętlą.¹⁷⁷

Kody wyjścia kontrolują zachowanie: - 0: Sukces: operacja jest kontynuowana. Stdout widoczny w trybie verbose (Ctrl+O). Dla UserPromptSubmit i SessionStart stdout jest dodawany do kontekstu. - 2: Błąd blokujący: operacja się zatrzymuje. Stderr staje się komunikatem błędu przekazywanym z powrotem do Claude. - 1, 3 itd.: Błąd nieblokujący: operacja jest kontynuowana. Stderr widoczny jako ostrzeżenie w trybie verbose.

Dla zaawansowanej kontroli hooks mogą wypisywać JSON:

{
  "decision": "allow",
  "message": "Command validated and modified",
  "modifications": {
    "tool_input": {
      "command": "npm test -- --coverage"
    }
  }
}

Kontrola decyzji PreToolUse (preferowany format): Hooks PreToolUse używają hookSpecificOutput do bogatszej kontroli: trzy wyniki (allow/deny/ask) oraz możliwość modyfikowania inputu narzędzia i wstrzykiwania kontekstu:⁸⁹

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "Command validated and modified",
    "updatedInput": {
      "command": "npm test -- --coverage --ci"
    },
    "additionalContext": "Note: This database has a 5-second query timeout."
  }
}

Uwaga: Pola najwyższego poziomu decision i reason są przestarzałe dla PreToolUse. Zamiast nich należy używać hookSpecificOutput.permissionDecision i hookSpecificOutput.permissionDecisionReason. Inne zdarzenia (PostToolUse, Stop itd.) nadal używają decision najwyższego poziomu.⁸⁹

Tytuł sesji UserPromptSubmit (v2.1.94+): Hooks UserPromptSubmit mogą ustawiać tytuł sesji przez hookSpecificOutput.sessionTitle.¹⁴⁰

Async Hooks (styczeń 2026)

Hooks mogą teraz działać w tle bez blokowania wykonywania Claude Code. Dodaj async: true do konfiguracji hook:⁸¹

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/notify-slack.sh",
            "async": true
          }
        ]
      }
    ]
  }
}

Kiedy używać async hooks: - Powiadomienia (Slack, email, Pushover), które nie powinny spowalniać sesji - Logowanie i telemetria, które mogą działać w tle - Niekrytyczne przetwarzanie po operacji (analytics, backupy)

Kiedy NIE używać async hooks: - Formatowanie (musi zakończyć się przed kolejną edycją) - Walidacja (musi blokować w razie niepowodzenia) - Każdy hook, który musi modyfikować input/output narzędzia

Hooks oparte na Prompt i Agent (v2.1.32+)

Poza shell command hooks (type: "command"), Claude Code obsługuje dwa typy hooks zasilane przez LLM, które oceniają warunki za pomocą rozumowania AI zamiast skryptów.⁸⁹

Prompt hooks (type: "prompt") wysyłają jednoturowy prompt do szybkiego modelu Claude. Model zwraca { "ok": true }, aby zezwolić, albo { "ok": false, "reason": "..." }, aby zablokować:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Evaluate if Claude should stop: $ARGUMENTS. Check if all requested tasks are complete and tests pass.",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

HTTP hooks (type: "http") wysyłają input zdarzenia JSON jako żądanie POST pod URL i otrzymują JSON z powrotem. Warto ich używać dla webhooks, zewnętrznych usług powiadomień albo walidacji opartej na API (v2.1.63+):¹⁰⁴

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "http",
            "url": "https://api.example.com/notify",
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

HTTP hooks używają tego samego formatu decyzji co command hooks (zwracają JSON z decision i reason). Gdy sandboxing jest włączony, są routowane przez sandbox network proxy. Nieobsługiwane dla zdarzeń SessionStart/Setup.

Agent hooks (type: "agent") uruchamiają subagenta z dostępem do narzędzi (Read, Grep, Glob) na potrzeby wieloturowej weryfikacji. Warto ich używać, gdy sprawdzenie wymaga inspekcji rzeczywistych plików albo outputu testów:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify all unit tests pass. Run the test suite and check results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

Użyj $ARGUMENTS jako placeholdera dla inputu hook JSON. Oba typy obsługują pola model (domyślnie szybki model) i timeout. Obsługiwane zdarzenia: PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, UserPromptSubmit, Stop, SubagentStop, TaskCompleted. TeammateIdle nie obsługuje prompt/agent hooks.

Hooks narzędzi MCP (v2.1.118+)

Hooks mogą teraz wywoływać narzędzie MCP bezpośrednio przez type: "mcp_tool", omijając potrzebę opakowywania podprocesu Bash, który wywołuje serwer.¹⁵²

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "mcp_tool",
            "server": "linear",
            "tool": "create_comment",
            "input": {"issue_id": "ENG-123", "body": "Auto-updated by Claude Code"}
          }
        ]
      }
    ]
  }
}

Dobrze współgra to z serwerami MCP, które użytkownicy mają już skonfigurowane: każde narzędzie osiągalne z /mcp staje się możliwe do wywołania przez hook.

duration_ms w hooks PostToolUse (v2.1.119+)

Inputy hook PostToolUse i PostToolUseFailure zawierają teraz duration_ms, czyli czas wykonania narzędzia z wyłączeniem promptów uprawnień i hooks PreToolUse.¹⁵² Przydatne do wykrywania wolnych narzędzi, logów audytu i metryk opóźnień per narzędzie:

# Stderr-flagged warning when an Edit takes more than 10 seconds
DUR=$(jq -r '.duration_ms')
if [ "$DUR" -gt 10000 ]; then
  echo "[slow-edit] ${DUR}ms — investigate $TOOL_INPUT_FILE_PATH" >&2
fi

updatedToolOutput dla wszystkich narzędzi (v2.1.121+)

W v2.1.118 MCP Tool Hooks zyskały możliwość zastępowania outputu narzędzia przez hookSpecificOutput.updatedToolOutput. Od v2.1.121 to samo pole działa dla dowolnego hook PostToolUse — narzędzi wbudowanych (Bash, Read, Edit, Glob, Grep itd.), narzędzi subagentów oraz narzędzi MCP. Przykłady zastosowań: redagowanie wrażliwych treści z outputu dowolnego narzędzia, normalizowanie struktury dla dalszych odbiorców, wstrzykiwanie metadanych, zanim agent odczyta wynik.¹⁵⁴

Zmienne środowiskowe Hook

Hooks mają dostęp do zmiennych środowiskowych do rozwiązywania ścieżek:⁸⁹

Utrwalanie zmiennych środowiskowych z SessionStart:

#!/bin/bash
if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
fi
exit 0

Bezpieczeństwo HTTP hook (v2.1.51+): HTTP hooks, które interpolują zmienne środowiskowe do nagłówków, wymagają teraz jawnej listy allowedEnvVars. Zapobiega to eksfiltracji dowolnych zmiennych środowiskowych przez wartości nagłówków. HTTP hooks są też routowane przez sandbox network proxy, gdy sandboxing jest włączony, co egzekwuje allowlistę domen. HTTP hooks nie są obsługiwane dla zdarzeń SessionStart/Setup.⁹⁸

{
  "hooks": {
    "PostToolUse": [{
      "hooks": [{
        "type": "command",
        "command": "curl -H 'Authorization: Bearer $MY_TOKEN' https://api.example.com/notify",
        "allowedEnvVars": ["MY_TOKEN"]
      }]
    }]
  }
}

Zaufanie workspace dla Hook (v2.1.51+): Polecenia hook statusLine i fileSuggestion wymagają teraz akceptacji zaufania workspace przed wykonaniem w trybie interaktywnym, zamykając potencjalny wektor bezpieczeństwa.⁹⁸

Praktyczne przykłady Hook

Automatyczne formatowanie plików TypeScript po edycji:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c '[[ \"$FILE_PATH\" == *.ts ]] && npx prettier --write \"$FILE_PATH\" || true'"
          }
        ]
      }
    ]
  }
}

Logowanie wszystkich poleceń bash:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/bash-history.log"
          }
        ]
      }
    ]
  }
}

Blokowanie dostępu do plików wrażliwych:

#!/bin/bash
# .claude/hooks/protect-files.sh
data=$(cat)
path=$(echo "$data" | jq -r '.tool_input.file_path // empty')

if [[ "$path" == *".env"* ]] || [[ "$path" == *"secrets/"* ]] || [[ "$path" == *".pem"* ]]; then
  echo "Blocked: Cannot access sensitive file $path" >&2
  exit 2  # Exit 2 = block the tool call. Exit 1 = non-blocking error (hook failure only).
fi
exit 0

Uruchamianie testów po zmianach w kodzie:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c '[[ \"$FILE_PATH\" == *.test.ts ]] || npm run test:affected'"
          }
        ]
      }
    ]
  }
}

Niestandardowy system powiadomień:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Waiting for your input'"
          }
        ]
      }
    ]
  }
}

Wstrzykiwanie dynamicznego kontekstu do promptów:

#!/bin/bash
# .claude/hooks/inject-context.sh
# Add current git branch and recent commits to every prompt

branch=$(git branch --show-current 2>/dev/null)
commits=$(git log --oneline -3 2>/dev/null | tr '\n' ' ')

if [ -n "$branch" ]; then
  echo "[Context: Branch '$branch', Recent: $commits]"
fi
exit 0

Debugowanie Hook

Włącz tryb debug, aby rozwiązywać problemy z hooks:

claude --debug

Tryb debug loguje: - Czasy wykonania hook - Dane input/output - Komunikaty błędów i stack traces - Wyniki decyzji (allow/reject/ask)

Wyświetlanie źródła hook (v2.1.75+): Gdy hook wymaga potwierdzenia użytkownika, prompt uprawnień pokazuje teraz źródło hook (settings, plugin albo skill), co ułatwia identyfikację komponentu żądającego dostępu.¹¹⁷

Hooks ograniczone do komponentu (v2.1.0+)

Hooks można definiować bezpośrednio w Skills, subagents i slash commands za pomocą frontmatter. Te hooks są ograniczone do cyklu życia komponentu i uruchamiają się tylko wtedy, gdy dany komponent jest aktywny.³⁴

Skill z osadzonymi hooks:

---
name: secure-deployment
description: Deployment skill with security validation
hooks:
  PreToolUse:
    - matcher: Bash
      command: ".claude/hooks/validate-deploy.sh"
  PostToolUse:
    - matcher: Bash
      command: ".claude/hooks/log-deploy.sh"
  Stop:
    - command: ".claude/hooks/cleanup.sh"
      once: true  # Run only once per session
---

Obsługiwane zdarzenia: PreToolUse, PostToolUse, Stop

Opcja once (tylko skills i slash commands) zapewnia, że hook uruchomi się tylko raz na sesję, co jest przydatne przy zadaniach czyszczenia lub finalizacji.

Strategia dla długich sesji

W przypadku nocnych lub nienadzorowanych sesji Claude Code należy skonfigurować hooks tak, aby utrzymywały Claude na właściwym torze bez ręcznej interwencji. Kluczowa obserwacja: hooks lintingu i testowania warto traktować jako guardrails, które zmuszają Claude do naprawienia problemów przed kontynuacją.⁵⁷

Wzorzec „Nie zatrzymuj się, dopóki testy nie przejdą”:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint && npm run typecheck",
            "timeout": 60000
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npm test || echo 'Tests failing - Claude should fix before stopping'"
          }
        ]
      }
    ]
  }
}

Strategia dla nocnych sesji:

1. Kontrola przed startem: Użyj Setup hook, aby sprawdzić, czy środowisko jest gotowe
2. Ciągła walidacja: Hooks PostToolUse uruchamiają testy po każdej zmianie
3. Bramka ukończenia: Hooks Stop weryfikują wszystkie kryteria akceptacji, zanim Claude zadeklaruje „gotowe”
4. Powiadomienie: Hooks Stop mogą powiadomić Pana/Panią przez Slack/Pushover, gdy Claude skończy albo się zablokuje

Połącz z --dangerously-skip-permissions w sandboxed container dla w pełni autonomicznych nocnych uruchomień. Claude będzie iterować, dopóki testy nie przejdą albo dopóki nie wyczerpie swoich opcji.

Czym jest MCP (Model Context Protocol)?

MCP rozszerza Claude Code o dostęp do zewnętrznych narzędzi, baz danych, API i usług za pośrednictwem standardowego protokołu. Ekosystem przeżył eksplozję: MCP ma obecnie 100 milionów miesięcznych pobrań oraz ponad 3000 serwerów zindeksowanych na MCP.so (styczeń 2026), co umacnia jego pozycję jako standardu branżowego dla łączenia AI z narzędziami i danymi.³⁴⁷ Zrozumienie MCP jest niezbędne do zintegrowania Claude z istniejącym łańcuchem narzędzi.

Dlaczego MCP ma znaczenie dla deweloperów: Bez MCP Claude Code może jedynie czytać pliki i wykonywać polecenia bash. Z MCP Claude może odpytywać produkcyjną bazę danych, tworzyć zgłoszenia w Jira, recenzować PR-y w GitHub, sprawdzać błędy w Sentry oraz wchodzić w interakcję z dowolnym API używanym przez zespół — wszystko to z poziomu zapytań w języku naturalnym. Protokół standaryzuje sposób, w jaki narzędzia AI łączą się z usługami zewnętrznymi, zapobiegając uzależnieniu od jednego dostawcy. Patrz Decision Frameworks, aby uzyskać wskazówki, kiedy stosować MCP, a kiedy inne mechanizmy rozszerzeń.

Obsługa zdalnego MCP (czerwiec 2025)

Claude Code obsługuje teraz zdalne serwery MCP z natywnym uwierzytelnianiem OAuth.²¹ Można łączyć się z narzędziami i źródłami danych bez zarządzania lokalnymi serwerami. Wystarczy raz się uwierzytelnić, a Claude Code automatycznie obsłuży odświeżanie tokenów.

# Connect to remote MCP server with OAuth
claude mcp add --transport http linear https://mcp.linear.app/sse
# Browser opens for OAuth flow, tokens stored securely

SDK mcp_authenticate redirectUri (v2.1.121+): Funkcja mcp_authenticate w Agent SDK akceptuje parametr redirectUri służący do dokończenia OAuth na niestandardowych schematach URI — wymagane dla aplikacji desktopowych oraz przepływów konektorów claude.ai, które nie mogą wykorzystać domyślnego przekierowania loopback.¹⁵⁴

Konektory MCP claude.ai (v2.1.46+)

Claude Code może teraz korzystać z konektorów MCP skonfigurowanych na koncie claude.ai. Wypełnia to lukę między wersją webową a CLI: serwery MCP skonfigurowane przez interfejs claude.ai są automatycznie dostępne w Claude Code bez konieczności ich ponownej konfiguracji lokalnie.⁹⁵

Wyłączenie: Należy ustawić ENABLE_CLAUDEAI_MCP_SERVERS=false w środowisku lub w bloku env pliku settings.json, aby zapobiec ładowaniu serwerów MCP z claude.ai.¹⁰⁴

Wyszukiwanie narzędzi MCP (v2.1.7+)

W miarę rozwoju możliwości serwerów MCP (niektóre udostępniają ponad 50 narzędzi), opisy narzędzi zaczęły zużywać nadmiernie dużo kontekstu. MCP Tool Search rozwiązuje ten problem poprzez dynamiczne ładowanie opisów narzędzi tylko wtedy, gdy są potrzebne — jest to forma leniwego ładowania (lazy loading) dla narzędzi AI.⁴⁷

Wpływ na wydajność: Wewnętrzne testy wykazują znaczącą poprawę dokładności: - Opus 4: 49% → 74% w ewaluacjach MCP - Opus 4.5: 79,5% → 88,1% w ewaluacjach MCP - Redukcja narzutu tokenów: 85%

Jak to działa: Gdy opisy narzędzi MCP przekraczają 10% okna kontekstu (domyślny próg), Claude Code odracza ładowanie pełnych opisów do momentu, aż będą faktycznie potrzebne. Claude widzi nazwy narzędzi, ale opisy pobiera na żądanie.

Konfiguracja:

{
  "mcpToolSearchAutoEnable": "auto:15"  // Enable when tools exceed 15% of context
}

Wartości: - true - Zawsze włącz wyszukiwanie narzędzi - false - Zawsze wyłącz (ładuj wszystkie opisy narzędzi z góry) - auto:N - Włącz, gdy narzędzia przekraczają N% kontekstu (0-100)

Wskazówka eksperta: Z włączonym Tool Search można podłączyć znacznie więcej serwerów MCP bez obaw o limity kontekstu. 95% redukcja kontekstu oznacza, że serwery, które wcześniej rywalizowały o kontekst, teraz współistnieją bezkonfliktowo.

Wymuszone ładowanie MCP (v2.1.121+)

Tool Search odracza ładowanie pełnych opisów do momentu, gdy narzędzie jest potrzebne (próg: mcpToolSearchAutoEnable, domyślnie auto:10). W przypadku zaufanych serwerów, których narzędzi spodziewa się Pan/Pani używać w każdej turze, można zrezygnować z tego mechanizmu dla konkretnego serwera za pomocą alwaysLoad: true — każde narzędzie z tego serwera jest ładowane do promptu na początku sesji, bez konieczności wykonywania zapytania ToolSearch:¹⁵⁴

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "alwaysLoad": true
    }
  }
}

Automatyczne ponowne uruchamianie MCP (v2.1.121+): Serwer, który zgłasza błąd podczas uruchamiania, jest teraz ponawiany do 3 razy, zanim zostanie oznaczony jako rozłączony — przydatne dla serwerów stdio, które konkurują z wolno startującym procesem nadrzędnym, lub dla serwerów HTTP za zimno startującym backendem.¹⁵⁴

MCP Elicitation (v2.1.76+)

Serwery MCP mogą teraz żądać ustrukturyzowanego wejścia od użytkownika w trakcie zadania za pomocą interaktywnych okien dialogowych.¹¹⁸ Gdy serwer MCP potrzebuje dodatkowych informacji (np. wyboru gałęzi, wpisania nazwy projektu, potwierdzenia akcji), wysyła żądanie elicitation, które Claude Code renderuje jako pola formularza lub URL przeglądarki.

Integracja z hookami: Dwa nowe zdarzenia hook — Elicitation (zanim okno dialogowe się pojawi) oraz ElicitationResult (po odpowiedzi użytkownika) — umożliwiają programowe przechwytywanie, walidację lub nadpisywanie odpowiedzi elicitation. Pozwala to na budowanie korporacyjnych przepływów pracy, w których prompty serwerów MCP są wstępnie wypełniane lub ograniczane przez zasady firmy.

Nadpisywanie rozmiaru wyniku MCP (v2.1.91+)

Wyniki narzędzi MCP są domyślnie obcinane. Serwery mogą to nadpisać dla każdego wyniku za pomocą adnotacji _meta["anthropic/maxResultSizeChars"], dopuszczając do 500 tys. znaków.¹³⁶ Przydaje się to przy zwracaniu dużych ładunków, takich jak schematy baz danych, odpowiedzi API lub zawartość plików, bez ich obcinania.

Interaktywny kreator konfiguracji MCP

Uruchomienie claude mcp add bez argumentów uruchamia krok po kroku interfejs do dodawania serwerów MCP. Kreator prowadzi przez wybór typu transportu, uwierzytelnianie i konfigurację.⁸

Typy transportu

HTTP (zalecane dla zdalnych serwerów):

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# With authentication
claude mcp add --transport http api https://api.example.com/mcp \
  --header "Authorization: Bearer $API_TOKEN"

SSE (przestarzałe, ale działa):

claude mcp add --transport sse asana https://mcp.asana.com/sse \
  --header "X-API-Key: your-key"

Stdio (lokalne serwery):

# PostgreSQL
claude mcp add --transport stdio postgres \
  --env "DATABASE_URL=postgresql://user:pass@localhost/db" \
  -- npx -y @anthropic-ai/mcp-server-postgres

# Custom server
claude mcp add --transport stdio custom -- python /path/to/server.py --port 8000

W systemie Windows stdio wymaga opakowania cmd:

claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

Zarządzanie zakresami

Serwery MCP istnieją w trzech zakresach z jasnym pierwszeństwem (lokalny nadpisuje projektowy, projektowy nadpisuje użytkownika):

Zakres można określić podczas instalacji:

claude mcp add --scope project --transport http github https://...
claude mcp add --scope user --transport stdio personal-tool -- ./my-tool

Format pliku konfiguracyjnego

Plik .mcp.json definiuje serwery na poziomie projektu:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${SENTRY_API_KEY}"
      }
    },
    "internal-api": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "X-API-Key": "${INTERNAL_API_KEY}"
      }
    }
  }
}

Zmienne środowiskowe są rozwijane przy użyciu składni ${VAR} z opcjonalnymi wartościami domyślnymi: ${VAR:-default}.

Polecenia zarządzania MCP

claude mcp list                      # View all configured servers
claude mcp get github                # Get specific server details
claude mcp remove github             # Remove a server
claude mcp reset-project-choices     # Reset project-scoped approvals
claude mcp add-from-claude-desktop   # Import from Claude Desktop
claude mcp add-json weather '{"type":"http","url":"..."}'  # Add from JSON

# Within Claude Code REPL
> /mcp                               # Interactive MCP management

Uwierzytelnianie OAuth

Dla serwerów wymagających OAuth:

> /mcp
# Follow browser-based OAuth flow
# Tokens stored securely and auto-refreshed
# Use "Clear authentication" to revoke access

Korzystanie z zasobów i promptów MCP

Odwołania do zasobów:

@github:issue://123
@postgres:schema://users
@docs:file://api/authentication

Prompty MCP jako polecenia slash:

/mcp__github__list_prs
/mcp__github__pr_review 456
/mcp__jira__create_issue "Bug title" high

Limity wyjścia

Claude Code ogranicza wyjście MCP, aby zapobiec przepełnieniu kontekstu: - Próg ostrzeżenia: 10 000 tokenów - Domyślne maksimum: 25 000 tokenów

Można zwiększyć w razie potrzeby:

export MAX_MCP_OUTPUT_TOKENS=50000

Popularne serwery MCP

Praktyczne wzorce MCP

Przepływ pracy z GitHub:

> Review PR #456
> List all open issues assigned to me
> Create a bug issue for the authentication failure we found

Zapytania do bazy danych:

> What's our total revenue this quarter?
> Show the schema for the users table
> Find customers with no purchases in 90 days

Monitorowanie błędów:

> What errors occurred in production today?
> Show the stack trace for error ABC123
> Which deployment introduced these errors?