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 179 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 dla danego 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 — najpotężniejszy i najbardziej inteligentny model Anthropic, state-of-the-art w niemal każdym benchmarku, w którym był testowany, zaprojektowany tak, aby zachowywać spójność przez miliony tokenów kontekstu. Fable 5 to frontier model klasy „Mythos”, przygotowany do bezpiecznego ogólnego użycia: zawiera klasyfikatory bezpieczeństwa, które przełączają zapytania cyber, bio-chem i model-distillation na Opus 4.8 (Claude Mythos 5 to ten sam model z usuniętymi zabezpieczeniami dla autoryzowanych badaczy). Stał się dostępny do wyboru w Claude Code w v2.1.170 (9 czerwca 2026) — należy uruchomić claude update, potem /model fable (krótki alias; /model claude-fable-5 oraz alias best także go wybierają) — i jest wdrażany w planach subskrypcyjnych do 22 czerwca 2026. Model ID: claude-fable-5. Fable 5 domyślnie obejmuje 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 dostępne za [1m]); maksymalny output to 128K. Cena wynosi $10/MTok input i $50/MTok output — mniej więcej 2× Opus 4.8 — dlatego warto rezerwować go dla naprawdę trudnego rozumowania, nie rutynowych edycji. Współdzieli powierzchnię żądań Opus 4.8 (tylko adaptive thinking; usunięto temperature/top_p/top_k oraz budget_tokens) z jedną nowością: jawne thinking: {type: "disabled"} zwraca 400, więc aby uruchomić bez thinking, należy całkowicie pominąć parametr thinking.¹⁷³

W samym Claude Code: Fable 5 obsługuje pełną skalę effort (low/medium/high/xhigh/max, domyślnie high), tak jak Opus 4.8. Thinking nie da się wyłączyć w Fable 5 — przełącznik thinking w sesji, ustawienie alwaysThinkingEnabled oraz MAX_THINKING_TOKENS=0 nie mają wpływu; model zawsze rozumuje adaptacyjnie. Pełna powierzchnia konfiguracji rodziny fable odzwierciedla pokrętła Opus: ANTHROPIC_DEFAULT_FABLE_MODEL przypina model, do którego rozwiązuje się alias fable (przydatne w Bedrock/Vertex/Foundry), DISABLE_PROMPT_CACHING_FABLE wyłącza Fable z prompt caching, a automatyczny fallback oparty na treści działa w 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 szczyt 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 premii za długi kontekst. Maksymalny output 128K, tylko adaptive thinking (extended thinking usunięte) oraz nowy poziom effort xhigh, rekomendowany jako punkt startowy dla programowania i obciążeń agentic.¹⁴⁵ Wiarygodny knowledge cutoff: styczeń 2026. Training data cutoff: styczeń 2026. Model ID: claude-opus-4-7. Ceny odpowiadają Opus 4.6: $5/$25 za MTok, z 5-min cache write $6.25, 1-hr cache write $10 i 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 skuteczność rozwiązania 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 compaction.¹⁴⁵ 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 modele są przed Opus 4.7 (69,4%). Liderzy benchmarków zmieniają się dynamicznie; przed decyzją na kilka kwartałów należy 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 Messages API w Opus 4.7 (widoczne dla wywołującego):¹⁴⁵

• Extended thinking budget_tokens został usunięty. Zamiast tego należy użyć thinking: {type: "adaptive"}. Adaptive thinking jest domyślnie wyłączone; żądania bez pola thinking działają bez thinking.
• Ustawienie temperature, top_p lub top_k na wartość inną niż domyślna zwraca HTTP 400. Należy pominąć te parametry i sterować modelem przez prompting.
• 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 użytkownikom).

Task budgets (beta header task-budgets-2026-03-13) pozwalają zasugerować modelowi docelową liczbę tokenów w całej 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 ze względu na lepsze agentic coding. Opus 4.6 pierwotnie wydano 5 lutego 2026.⁷⁹¹⁴⁴ Od v2.1.117 (22 kwietnia 2026) subskrybenci Pro i Max mają domyślnie high effort w Opus 4.6 i Sonnet 4.6 (wcześniej medium); Opus 4.7 pozostaje na 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.⁹³ Ta sama cena co Sonnet 4.5 ($3/$15 za MTok). Lepsza wydajność agentic search przy mniejszym zużyciu tokenów. Obsługuje extended thinking, adaptive thinking oraz okno kontekstu 1M tokenów (beta). Maksymalny output 64K (górny limit 128K w v2.1.77).¹¹⁹ Knowledge cutoff: sierpień 2025 (wiarygodny), styczeń 2026 (dane treningowe). Model ID: claude-sonnet-4-6.

Claude Mythos Preview (7 kwietnia 2026): Frontier model w research preview do defensywnych prac cyberbezpieczeństwa, oferowany w ramach Project Glasswing.¹³⁹ Tylko na zaproszenie; niedostępny ogólnie. Anthropic przedstawia Opus 4.7 jako celowo mniej zdolny niż Mythos w wymiarach cyber — to kompromis bezpieczeństwa — i uruchomił 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 programowania zużywa 50K-200K tokenów input i 10K-50K tokenów output. W Haiku kosztuje to $0.10-$0.45 za sesję. W Opus ta sama sesja kosztuje $0.50-$2.25, czyli 5x więcej. Opus warto rezerwować dla naprawdę trudnych problemów.¹

Kiedy używać którego modelu

Haiku: Do subagents wykonujących eksplorację, proste wyszukiwania plików i szybkie pytania. Jest około 5x tańszy niż Opus i odpowiada szybciej. Idealny do zadań w tle, w których głębokie rozumowanie nie jest potrzebne.

Sonnet: Roboczy model do codziennego developmentu, gdy koszt ma znaczenie. Obsługuje większość zadań programistycznych: implementowanie funkcji, naprawianie błędów, pisanie testów, code review. Sonnet 4.6 zapewnia lepsze agentic search i wyższą efektywność tokenów niż Sonnet 4.5, z obsługą adaptive thinking i 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 pozostają przy Sonnet 4.6 jako domyślnym modelu do czasu przejścia Enterprise i API na Opus 4.7 23 kwietnia 2026.¹⁴⁷ Sonnet warto wybrać, gdy potrzebne są tańsze tokeny, mniejsze opóźnienie albo korzystniejsza ekonomika subagentów.

Opus: Flagowy poziom od 16 kwietnia 2026 i domyślny model w planach Max oraz Team Premium.¹⁴⁴¹⁴⁷ Droższe rozumowanie należy rezerwować tam, gdzie się opłaca: decyzje architektoniczne, trudne debugowanie, rozumienie złożonych systemów, analiza bezpieczeństwa, długohoryzontowa praca agentic. 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 skuteczność rozwiązania o 13% w wewnętrznym benchmarku kodowania obejmującym 93 zadania.¹⁴⁴ Claude Code domyślnie ustawia xhigh effort w Opus 4.7, z możliwością strojenia przez /effort (v2.1.111+).¹⁴⁶¹⁴⁷ Auto Mode jest dostępny dla subskrybentów Max w Opus 4.7 przez Anthropic API bez potrzeby --enable-auto-mode; inne plany/dostawcy mają dostępność zależną od planu i kontroli administratora.¹⁴⁶ Kontekst 1M w standardowej cenie — bez premii za długi kontekst. Zmiany zachowania, które warto znać: Opus 4.7 bardziej dosłownie wykonuje instrukcje, dopasowuje długość odpowiedzi do złożoności zadania, domyślnie uruchamia mniej subagentów i przyjmuje bardziej bezpośredni ton z mniejszą liczbą sformułowań walidujących. Jeśli prompty zawierają scaffolding wymuszający komunikaty o postępie pośrednim lub zachowanie double-check, warto spróbować go usunąć.¹⁴⁵

Opusplan: Tryb hybrydowy używający Opus do planowania (tam, gdzie jakość rozumowania ma największe znaczenie) i Sonnet do wykonania (tam, gdzie liczy się szybkość). Bardzo dobry do złożonego refactoringu, gdy potrzebny jest najlepszy plan, ale rozumowanie na poziomie Opus nie jest konieczne przy 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"
}

Specjalnie dla subagents:

export CLAUDE_CODE_SUBAGENT_MODEL=haiku

Łańcuch fallback model (v2.1.166+): ustawienie fallbackModel konfiguruje do trzech modeli awaryjnych, próbowanych po kolei, gdy model główny jest przeciążony lub niedostępny. Flaga --fallback-model (wcześniej wyłącznie przełącznik w trakcie sesji) działa teraz 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 ponawia teraz także turę raz na modelu fallback przed pokazaniem awarii, dzięki czemu przejściowy problem z modelem głównym degraduje się łagodnie zamiast utracić turę.¹⁷⁵

Rozszerzony kontekst

Dla dużych baz kodu lub 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 trakcie sesji:

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

Opus 4.7, Opus 4.6 i Sonnet 4.6 obejmują pełne okno kontekstu 1M tokenów w standardowej cenie — bez premii 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 dołączony automatycznie — sufiks [1m] nie jest potrzebny (domyślnie włączone 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 według standardowych stawek 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 model ID dla przypiętych wersji, wraz 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. W trakcie sesji można go przełączyć 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 około 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, dopóki nie nastąpi przełączenie 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: - Przy szybkiej iteracji małych zmian, gdy wąskim gardłem jest opóźnienie - Przy generowaniu testów, boilerplate lub powtarzalnego kodu, gdzie szybkość jest ważniejsza niż koszt - Podczas sekwencyjnej pracy nad listą podobnych zadań

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

Opus 4.6 fast mode 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). Gdy opóźnienie jest ważniejsze niż koszt, należy użyć fast mode bezpośrednio, a przy pracy autonomicznej lub batch wyłączyć go. /fast wymaga extra usage; administratorzy Team/Enterprise mogą najpierw musieć 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ą. W trakcie sesji należy użyć /effort:

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

Claude Code używa teraz domyślnie xhigh effort dla Opus 4.7. xhigh działa tylko w Opus 4.7 — inne modele cofają się do high. Claude Managed Agents obsługuje effort automatycznie; parametr effort jest pojęciem 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ść z intencją i bezpieczeństwo. Uwaga (v2.1.111+): flaga --enable-auto-mode została usunięta; sesję w Auto Mode należy uruchomić przez --permission-mode auto. Auto Mode nie jest dostępny w Pro; zgodnie z dokumentacją 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 przez CLAUDE_CODE_ENABLE_AUTO_MODE=1.¹⁷⁸

Reguły niestandardowe 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, więc można nakładać reguły niestandardowe wokół domyślnych:¹⁵²

// .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 dla 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, z możliwością rezygnacji przez /config lub 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 również z klientów Remote Control.

Narzędzie Windows PowerShell (v2.1.111+, wdrożenie)

Claude Code wdraża 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 wdrożenia.¹⁴⁶

Automatyczne zatwierdzanie w permission-mode (v2.1.119+). Polecenia narzędzia PowerShell mogą teraz otrzymywać automatyczne zatwierdzenie w permission mode tak samo jak polecenia Bash. Reguły allow takie jak PowerShell(Get-*:*) i istniejąca składnia wzorców omijają teraz prompt dla operacji tylko do odczytu, zapewniając ergonomię operatora znaną zespołom z Linux/macOS.¹⁵²

Redukcja uprawnień: Bash tylko do odczytu (v2.1.111+)

Wzorce Bash tylko do odczytu z argumentami glob (np. ls *.ts, cat src/*.md) oraz polecenia zaczynające się od cd <project-dir> && nie wywołują już promptu uprawnień.¹⁴⁶ W połączeniu z /less-permission-prompts powinno to znacząco ograniczyć przerwy w codziennych workflow.

Distributed Tracing (v2.1.110+)

Sesje SDK i headless odczytują teraz TRACEPARENT i TRACESTATE ze środowiska, łącząc uruchomienia Claude Code z distributed traces. Można połączyć 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.¹⁴⁶

Natywna dystrybucja binarna (v2.1.113+)¹⁵⁰

v2.1.113 zmienia sposób uruchamiania CLI: claude tworzy teraz natywny binarny Claude Code przez opcjonalną zależność per platforma zamiast uruchamiać spakowane JavaScript. Polecenia instalacji i aktualizacji pozostają takie same, a zespoły nie muszą zmieniać skryptów wdrożeniowych.

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

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

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

Timeout zatrzymania subagenta (v2.1.113+)¹⁵⁰

Subagents, które zatrzymują się w połowie streamu, kończą się teraz po 10 minutach czytelnym błędem zamiast wisieć po cichu. Warto połączyć to z CLAUDE_STREAM_IDLE_TIMEOUT_MS (v2.1.84+), aby szerzej obsłużyć zablokowane procesy przy streamujących API.

Poprawka stabilności v2.1.114¹⁵⁰

v2.1.114 (18 kwietnia 2026) zawiera jedną poprawkę: okno dialogowe uprawnień mogło się wywrócić, gdy członek zespołu agent-teams poprosił o uprawnienie do 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, jakie operacje mogą zostać wykonane. Jego zrozumienie ma kluczowe znaczenie zarówno dla bezpieczeństwa, jak i efektywności pracy. Zobacz także wdrożenie Enterprise, aby poznać ustawienia zarządzane, które wymuszają uprawnienia w całej organizacji.

Poziomy uprawnień

Narzędzia tylko do odczytu (zatwierdzane automatycznie): - Read - odczyt zawartości plików - Glob - znajdowanie plików według wzorca - Grep - przeszukiwanie zawartości plików - WebSearch - wyszukiwanie w internecie - 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: przejście do miejsca, w którym zdefiniowano symbol - Znajdowanie odwołań: wyświetlenie listy wszystkich użyć symbolu w całej bazie kodu - Dokumentacja po najechaniu kursorem: uzyskanie informacji o typie i dokumentacji dla dowolnego symbolu - Działa z TypeScript, Python, Go, Rust i innymi językami obsługującymi LSP - Wymaga dostępnego serwera językowego (zwykle instalowanego razem z używanym toolchainem)

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

Przy pierwszym uruchomieniu narzędzia modyfikacji Claude Code prosi o zatwierdzenie. Zatwierdzenia pozostają ważne przez czas trwania sesji, chyba że skonfigurowano inaczej.

Tryby uprawnień

Pliki konfiguracji wykonujące kod wywołują teraz monit 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ą umożliwić ciche wykonywanie poleceń: plików startowych powłoki (.zshenv, .zlogin, .bash_login), ~/.config/git/ oraz konfiguracji narzędzi budowania (.npmrc, .yarnrc*, bunfig.toml, .bazelrc, .pre-commit-config.yaml, .devcontainer/ i podobnych). Uzasadnienie jest takie, że edycja dowolnego z tych plików zmienia następną powłokę, instalację lub commit w wektor wykonania, dlatego otrzymują one świadomą bramkę nawet w trybie zaufanego projektu, który w innych przypadkach przepuszcza edycje. To ten sam model zagrożeń co istniejące zabezpieczenia zapisu dla .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. Oddzielny model klasyfikatora (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 i edycje plików w katalogu roboczym są zatwierdzane automatycznie - Niestandardowe reguły allow/deny są rozstrzygane jako pierwsze - Wszystko pozostałe trafia do klasyfikatora do oceny - W razie zablokowania Claude automatycznie próbuje alternatywnego podejścia

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

Wyłącznik awaryjny: 3 kolejne blokady lub 20 łącznie w sesji powodują powrót do ręcznych monitów.¹²⁵

# 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.¹²⁴

Tryb YOLO (v2.0.68+): Do w pełni autonomicznego działania bez żadnego 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 użyte celowo. Auto Mode jest zalecaną alternatywą dla większości zastosowań.⁵⁴

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ń

Reguły szczegółowe kontrolują konkretne operacje. Reguły są oceniane kolejno: 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, a nie regex. Wzorzec taki jak Bash(curl http:*) nie dopasuje curl -X GET http://..., ponieważ opcje występują przed URL. Aby blokowanie było niezawodne, należy zablokować całe polecenie: 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 z pliku ustawień: Edit(/build/**) - względem lokalizacji pliku ustawień - Rzeczywiście 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 albo blokowania całych serwerów z niezaufanych źródeł.

Od v2.1.166 reguły deny akceptują także glob w pozycji nazwy narzędzia: sama gwiazdka "*" w polu nazwy narzędzia blokuje wszystkie narzędzia, dzięki czemu można zablokować wszystko, a następnie dopuścić tylko wąski zestaw. Reguły allow natomiast odrzucają globy spoza MCP — nie można w ten sam sposób szeroko zezwolić na wszystko, co utrzymuje restrykcyjną postawę domyślną.¹⁷⁵

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ównoległych.

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 trybie sandbox: - Dostęp do systemu plików ograniczony do katalogu projektu - Dostęp do sieci kontrolowany - Niektóre polecenia wyłączone z ograniczeń sandbox - Polecenia Bash automatycznie dozwolone, jeśli autoAllowBashIfSandboxed ma wartość true

Wskazówka ekspercka: Tryb sandbox świetnie nadaje się do uruchamiania Claude na niezaufanych bazach kodu. Warto go włączyć podczas eksplorowania nieznanych projektów albo wtedy, gdy potrzebna jest dodatkowa warstwa ochrony. Wewnętrzne testy Anthropic wykazały, że sandboxing zmniejsza liczbę monitów o uprawnienia o 84%.³⁸ Sandbox używa prymitywów na poziomie OS (macOS seatbelt, Linux bubblewrap) do izolacji systemu plików i sieci, więc nawet skuteczne prompt injection pozostaje w pełni ograniczone. Anthropic udostępniło runtime sandbox 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 zgodę Bash, gdy włączone było autoAllowBashIfSandboxed; naprawiono to 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 sandbox allowRead, które ponownie zezwala na dostęp do odczytu w regionach denyRead — przydatne, gdy chce się zablokować większość drzewa katalogów, ale dodać konkretne podkatalogi do allowlisty.¹¹⁹

Wyjątek konfiguracji agentów .claude/ (v2.1.121+): --dangerously-skip-permissions nie wywołuje już monitów przy zapisach do .claude/skills/, .claude/agents/ i .claude/commands/.¹⁵⁴

Niestandardowe ścieżki bubblewrap i socat (v2.1.133+): Zarządzane ustawienia sandbox.bwrapPath i sandbox.socatPath pozwalają administratorom kierować wdrożenia Linux/WSL do niestandardowych lokalizacji binariów bubblewrap i socat. Jest to przydatne, gdy dystrybucje instalują te narzędzia poza $PATH albo gdy organizacja dostarcza wzmocnione kompilacje.¹⁶⁰

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

• sandbox.network.deniedDomains blokuje konkretne hosty nawet wtedy, gdy szerszy wildcard allowedDomains w przeciwnym razie by je dopuszczał. Warto użyć blocklisty, aby odciąć pastebiny, miejsca zrzutu plików lub znane złośliwe hosty 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 i 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ł 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?

Konfiguracja MCP w środowisku korporacyjnym

Administratorzy systemu mogą egzekwować polityki MCP za pomocą pliku managed-mcp.json: