cc-viewer 1.2.0 → 1.2.2

package/concepts/no/Tools.md

@@ -0,0 +1,73 @@
+# Oversikt over Claude Code-verktøy
+
+Claude Code tilbyr en samling innebygde verktøy til modellen via tool_use-mekanismen i Anthropic API. `tools`-arrayen i hver MainAgent-forespørsel inneholder komplette JSON Schema-definisjoner for disse verktøyene, og modellen kaller dem i responsen via `tool_use` content blocks.
+
+Nedenfor er en kategorisert indeks over alle verktøy.
+
+## Agent-system
+
+| Verktøy | Formål |
+|---------|--------|
+| [Task](Tool-Task.md) | Starte en sub-agent (SubAgent) for å håndtere komplekse flerstegsoppgaver |
+| [TaskOutput](Tool-TaskOutput.md) | Hente utdata fra bakgrunnsoppgaver |
+| [TaskStop](Tool-TaskStop.md) | Stoppe en kjørende bakgrunnsoppgave |
+| [TaskCreate](Tool-TaskCreate.md) | Opprette et strukturert oppgavelisteelement |
+| [TaskGet](Tool-TaskGet.md) | Hente oppgavedetaljer |
+| [TaskUpdate](Tool-TaskUpdate.md) | Oppdatere oppgavestatus, avhengigheter osv. |
+| [TaskList](Tool-TaskList.md) | Liste alle oppgaver |
+
+## Filoperasjoner
+
+| Verktøy | Formål |
+|---------|--------|
+| [Read](Tool-Read.md) | Lese filinnhold (støtter tekst, bilder, PDF, Jupyter notebook) |
+| [Edit](Tool-Edit.md) | Redigere filer via nøyaktig strengerstatning |
+| [Write](Tool-Write.md) | Skrive eller overskrive filer |
+| [NotebookEdit](Tool-NotebookEdit.md) | Redigere Jupyter notebook-celler |
+
+## Søk
+
+| Verktøy | Formål |
+|---------|--------|
+| [Glob](Tool-Glob.md) | Søke etter filer med filnavnmønstermatching |
+| [Grep](Tool-Grep.md) | Innholdssøk i filer basert på ripgrep |
+
+## Terminal
+
+| Verktøy | Formål |
+|---------|--------|
+| [Bash](Tool-Bash.md) | Kjøre shell-kommandoer |
+
+## Web
+
+| Verktøy | Formål |
+|---------|--------|
+| [WebFetch](Tool-WebFetch.md) | Hente nettsidens innhold og behandle det med AI |
+| [WebSearch](Tool-WebSearch.md) | Søkemotorforespørsler |
+
+## Planlegging og interaksjon
+
+| Verktøy | Formål |
+|---------|--------|
+| [EnterPlanMode](Tool-EnterPlanMode.md) | Gå inn i planleggingsmodus for å designe implementeringsplan |
+| [ExitPlanMode](Tool-ExitPlanMode.md) | Gå ut av planleggingsmodus og sende planen til brukergodkjenning |
+| [AskUserQuestion](Tool-AskUserQuestion.md) | Stille spørsmål til brukeren for avklaring eller beslutninger |
+
+## Utvidelser
+
+| Verktøy | Formål |
+|---------|--------|
+| [Skill](Tool-Skill.md) | Kjøre ferdigheter (slash command) |
+
+## IDE-integrasjon
+
+| Verktøy | Formål |
+|---------|--------|
+| [getDiagnostics](Tool-getDiagnostics.md) | Hente språkdiagnostikk fra VS Code |
+| [executeCode](Tool-executeCode.md) | Kjøre kode i Jupyter kernel |
+
+## Betydning i cc-viewer
+
+Verktøykall er blant de viktigste observerbare dataene i Claude Code-forespørselslogger. `tools`-arrayen i hver MainAgent-forespørsel definerer verktøysettet tilgjengelig for modellen, mens `tool_use` / `tool_result` content blocks i responsen registrerer faktiske verktøykall og resultater. cc-viewer analyserer disse dataene for å rekonstruere den komplette verktøykallkjeden i Chat Mode.
+
+Endringer i verktøydefinisjoner (som tillegg/fjerning av verktøy på grunn av MCP-server tilkobling/frakobling) utløser cache-gjenoppbygging, se [CacheRebuild](CacheRebuild.md).

package/concepts/no/TranslateContextPollution.md

@@ -0,0 +1,46 @@
+# Kontekstforurensning i Translate API
+
+## Bakgrunn
+
+CC-Viewer inkluderer en innebygd oversettelsesfunksjon (`POST /api/translate`) drevet av Anthropic Messages API. I den tidlige implementeringen gjenbrukte oversettelsesforespørsler bufrede autentiseringsopplysninger fra Claude Code-sesjonen — inkludert både `x-api-key`- og `authorization`-headere. Dette forårsaket et subtilt, men alvorlig problem: oversettelsesresultater returnerte ofte irrelevant innhold.
+
+## Rotårsak
+
+### Fundamental forskjell mellom to autentiseringsmetoder
+
+Anthropic API støtter to autentiseringsmetoder:
+
+| Metode | Header | Typisk kilde | Egenskaper |
+|--------|--------|--------------|------------|
+| API-nøkkel | `x-api-key: sk-ant-...` | Miljøvariabel / Console | Tilstandsløs, hver forespørsel er uavhengig |
+| OAuth-token | `authorization: Bearer sessionToken` | Claude Code abonnementsinnlogging | Sesjonsbundet, serveren opprettholder konteksttilknytning |
+
+Den avgjørende forskjellen: **API-nøkler er tilstandsløse** — hver forespørsel er fullstendig uavhengig; mens **OAuth-sesjonstokens er tilstandsbaserte** — Anthropic-serveren knytter forespørsler med samme token til samme sesjonskontekst.
+
+### Forurensningskjede
+
+Når Claude Code bruker OAuth-abonnementsinnlogging, ser autentiseringsflyten slik ut:
+
+```
+Claude Code hovedsamtale ──(authorization: Bearer sessionToken)──→ Anthropic API
+                                                                      ↑
+CC-Viewer oversettelsesforespørsel ──(authorization: Bearer sessionToken)──→ Anthropic API
+```
+
+Siden oversettelsesforespørsler gjenbrukte det samme sesjonstokenet, kan Anthropic-serveren knytte oversettelsesforespørsler til Claude Codes hovedsamtalekontekst. Dette fører til:
+
+1. **Oversettelsesresultater påvirket av hovedsamtalens kontekst**: Oversettelsesforespørselens systemprompt er «du er en oversetter», men serverkonteksten inneholder fortsatt Claude Codes samtalehistorikk, som potensielt kan forstyrre modellen
+2. **Hovedsamtalen forstyrret av oversettelsesforespørsler**: Innhold fra oversettelsesforespørsler (UI-tekstfragmenter) kan bli injisert i hovedsamtalens kontekst, noe som får Claude Codes svar til å avvike
+3. **Uforutsigbar oppførsel**: Siden kontekstforurensning er oppførsel på serversiden, kan klienten ikke oppdage eller kontrollere det
+
+## Erfaringer
+
+- **OAuth-sesjonstokens er ikke «bare en annen API-nøkkel»** — de bærer tilstand på serversiden, og gjenbruk av dem betyr deling av kontekst
+- **Interne tjenestekall bør bruke uavhengig, tilstandsløs autentisering** for å unngå tilknytning til brukersesjoner
+
+## Referanser
+
+- [Anthropic API Authentication Docs](https://docs.anthropic.com/en/api/getting-started)
+- [Claude Code Authentication](https://support.claude.com/en/articles/12304248-managing-api-key-environment-variables-in-claude-code)
+- [Anthropic Bans Subscription OAuth in Third-Party Apps](https://winbuzzer.com/2026/02/19/anthropic-bans-claude-subscription-oauth-in-third-party-apps-xcxwbn/)
+- [Claude Code Authentication: API Keys, Subscriptions, and SSO](https://developertoolkit.ai/en/claude-code/quick-start/authentication/)

package/concepts/pl/BodyDiffJSON.md

@@ -0,0 +1,32 @@
+# Body Diff JSON (przyrostowe porównanie treści żądania)
+
+## Kontekst
+
+MainAgent w Claude Code stosuje mechanizm wysyłania pełnego kontekstu — każde żądanie zawiera kompletną historię rozmowy, system prompt, definicje narzędzi itp. Oznacza to, że w miarę postępu rozmowy treść żądania staje się coraz większa, a bezpośrednie przeglądanie surowego Body utrudnia szybkie zlokalizowanie „co dokładnie zostało dodane w tej turze".
+
+Body Diff JSON rozwiązuje właśnie ten problem: automatycznie porównuje treści dwóch kolejnych żądań MainAgent, wyodrębnia przyrostowe zmiany i pozwala od razu zobaczyć, co faktycznie zostało dodane w bieżącym żądaniu.
+
+## Zasada działania
+
+1. **Identyfikacja kolejnych żądań MainAgent**: bieżące żądanie musi być typu MainAgent i musi istnieć poprzednie żądanie MainAgent
+2. **Porównanie pole po polu**: iteracja po wszystkich polach najwyższego poziomu w treści żądania, z pominięciem wewnętrznych właściwości z prefiksem `_`
+3. **Inteligentne wyodrębnianie różnic**:
+   - Nowe pola: wyświetlane bezpośrednio
+   - Usunięte pola: nie są wyświetlane (zazwyczaj nie wpływają na zrozumienie)
+   - Zmienione pola: wyświetlana jest bieżąca wartość
+   - Tablica `messages` — specjalne traktowanie: wyświetlane są tylko nowe wiadomości (ponieważ w normalnej rozmowie wiadomości są dopisywane, a prefiks pozostaje bez zmian)
+4. **Wykrywanie zmniejszenia treści żądania**: jeśli bieżące żądanie jest mniejsze od poprzedniego, oznacza to obcięcie kontekstu lub reset sesji — w takim przypadku wyświetlany jest komunikat informacyjny zamiast diff
+
+## Typowe scenariusze
+
+W normalnej turze rozmowy Body Diff JSON zazwyczaj zawiera tylko:
+- `messages`: 1–2 nowe wiadomości (dane wejściowe użytkownika + odpowiedź asystenta z poprzedniej tury)
+
+Jeśli w diff pojawiają się zmiany pól `system`, `tools`, `model` itp., oznacza to zmianę konfiguracji w bieżącej turze, co często jest również przyczyną przebudowy cache.
+
+## Sposób użycia
+
+- Body Diff JSON jest wyświetlany w panelu szczegółów żądania MainAgent
+- Kliknięcie nagłówka rozwija/zwija zawartość
+- Obsługuje tryby podglądu JSON i Text oraz kopiowanie jednym kliknięciem
+- W lewym górnym rogu **CC-Viewer → Ustawienia globalne** można ustawić „Domyślnie rozwiń Body Diff JSON"

package/concepts/pl/CacheRebuild.md

@@ -0,0 +1,40 @@
+# Cache Rebuild (przebudowa cache)
+
+## Kontekst
+
+Mechanizm prompt caching Anthropic łączy system → tools → messages (do punktu przerwania cache) w klucz cache. Gdy klucz cache jest identyczny z poprzednim żądaniem, API zwraca `cache_read_input_tokens` (trafienie cache); gdy klucz cache się zmieni, API tworzy cache od nowa, zwracając dużą liczbę `cache_creation_input_tokens`, czyli przebudowę cache.
+
+Przebudowa cache oznacza dodatkowe koszty tokenów (cena cache creation jest wyższa niż cache read), dlatego identyfikacja przyczyn przebudowy ma bezpośrednią wartość dla optymalizacji kosztów.
+
+## Klasyfikacja przyczyn przebudowy cache
+
+cc-viewer porównuje treści dwóch kolejnych żądań MainAgent, aby precyzyjnie określić przyczynę przebudowy cache:
+
+| reason | Znaczenie | Sposób określenia |
+|--------|------|----------|
+| `ttl` | Cache wygasł | Od poprzedniego żądania MainAgent upłynęło ponad 5 minut |
+| `system_change` | Zmiana system prompt | `JSON.stringify(prev.system) !== JSON.stringify(curr.system)` |
+| `tools_change` | Zmiana definicji narzędzi | `JSON.stringify(prev.tools) !== JSON.stringify(curr.tools)` |
+| `model_change` | Zmiana modelu | `prev.model !== curr.model` |
+| `msg_truncated` | Obcięcie stosu wiadomości | Bieżące żądanie ma mniej wiadomości niż poprzednie, zazwyczaj z powodu obcięcia wywołanego przepełnieniem okna kontekstu |
+| `msg_modified` | Modyfikacja historii wiadomości | Treść wiadomości prefiksowych jest niespójna (przy normalnym dopisywaniu prefiks powinien być identyczny) |
+| `key_change` | Nieznana zmiana klucza | Fallback, gdy żaden z powyższych warunków nie pasuje |
+
+## Priorytet określania
+
+1. Najpierw sprawdzany jest odstęp czasowy — ponad 5 minut oznacza bezpośrednio `ttl`, bez porównywania treści
+2. Następnie kolejno sprawdzane są: model, system, tools, messages
+3. Jedno żądanie może jednocześnie spełniać wiele przyczyn (np. zmiana modelu + zmiana system prompt), wtedy tablica `reasons` zawiera wszystkie pasujące elementy, a tooltip wyświetla je w osobnych wierszach
+
+## Typowe scenariusze
+
+- **`ttl`**: użytkownik wstrzymał pracę na ponad 5 minut, cache naturalnie wygasł
+- **`system_change`**: Claude Code zaktualizował system prompt (np. załadowanie nowego CLAUDE.md, zmiana instrukcji projektu)
+- **`tools_change`**: połączenie/rozłączenie serwera MCP spowodowało zmianę listy dostępnych narzędzi
+- **`model_change`**: użytkownik przełączył model poleceniem `/model`
+- **`msg_truncated`**: zbyt długi dialog wywołał zarządzanie oknem kontekstu, Claude Code obciął wcześniejsze wiadomości
+- **`msg_modified`**: Claude Code edytował historyczne wiadomości (np. `/compact` zastąpił oryginalne wiadomości skompresowanym podsumowaniem)
+
+## Wyświetlanie w cc-viewer
+
+Na liście żądań, żądania z przebudową cache mają czerwony wskaźnik kropkowy w wierszu cache. Po najechaniu myszą wyświetlany jest tooltip z konkretnym opisem przyczyny przebudowy (obsługa 18 języków).

package/concepts/pl/MainAgent.md

@@ -0,0 +1,30 @@
+# MainAgent
+
+## Definicja
+
+MainAgent to główny łańcuch żądań Claude Code w trybie bez agent team. Każda interakcja użytkownika z Claude Code generuje serię żądań API, z których żądania MainAgent tworzą główny łańcuch dialogu — zawierają pełny system prompt, definicje narzędzi i historię wiadomości.
+
+## Sposób identyfikacji
+
+W cc-viewer MainAgent jest identyfikowany przez `req.mainAgent === true`, automatycznie oznaczany przez `interceptor.js` podczas przechwytywania żądania.
+
+Warunki kwalifikacji (wszystkie muszą być spełnione):
+- Treść żądania zawiera pole `system` (system prompt)
+- Treść żądania zawiera tablicę `tools` (definicje narzędzi)
+- System prompt zawiera tekst charakterystyczny dla "Claude Code"
+
+## Różnice względem SubAgent
+
+| Cecha | MainAgent | SubAgent |
+|------|-----------|----------|
+| system prompt | Pełny główny prompt Claude Code | Uproszczony prompt dedykowany zadaniu |
+| tablica tools | Zawiera wszystkie dostępne narzędzia | Zazwyczaj zawiera tylko kilka narzędzi potrzebnych do zadania |
+| historia wiadomości | Kumuluje pełny kontekst dialogu | Zawiera tylko wiadomości związane z podzadaniem |
+| zachowanie cache | Prompt caching (5 minut TTL) | Zazwyczaj bez cache lub z małym cache |
+
+## Znaczenie w cc-viewer
+
+- **Śledzenie cache**: stan prompt caching żądań MainAgent bezpośrednio wpływa na koszty. Monitorowanie proporcji `cache_creation_input_tokens` do `cache_read_input_tokens` pozwala ocenić współczynnik trafień cache
+- **Analiza utraty cache**: gdy żądanie MainAgent wykazuje dużą liczbę cache creation (zamiast cache read), oznacza to utratę i przebudowę cache — cc-viewer oznacza te żądania czerwonym wskaźnikiem kropkowym
+- **Analiza głównego łańcucha**: sekwencja żądań MainAgent odzwierciedla pełny proces interakcji użytkownika z Claude Code i stanowi kluczowe dane do analizy zachowania sesji
+- **Rekonstrukcja sesji**: cc-viewer rekonstruuje widok dialogu (Chat Mode) na podstawie historii wiadomości z żądań MainAgent

package/concepts/pl/Tool-AskUserQuestion.md

@@ -0,0 +1,54 @@
+# AskUserQuestion
+
+## Definicja
+
+Zadaje pytanie użytkownikowi podczas wykonywania, w celu uzyskania wyjaśnienia, weryfikacji założeń lub uzyskania decyzji.
+
+## Parametry
+
+| Parametr | Typ | Wymagany | Opis |
+|------|------|------|------|
+| `questions` | array | Tak | Lista pytań (1-4 pytania) |
+| `answers` | object | Nie | Odpowiedzi zebrane od użytkownika |
+| `annotations` | object | Nie | Adnotacje do każdego pytania (np. uwagi do podglądu wyboru) |
+| `metadata` | object | Nie | Metadane do śledzenia i analizy |
+
+Każdy obiekt `question`:
+
+| Pole | Typ | Wymagany | Opis |
+|------|------|------|------|
+| `question` | string | Tak | Pełny tekst pytania, powinien kończyć się znakiem zapytania |
+| `header` | string | Tak | Krótka etykieta (maks. 12 znaków), wyświetlana jako chip etykiety |
+| `options` | array | Tak | 2-4 opcje |
+| `multiSelect` | boolean | Tak | Czy dozwolony jest wielokrotny wybór |
+
+Każdy obiekt `option`:
+
+| Pole | Typ | Wymagany | Opis |
+|------|------|------|------|
+| `label` | string | Tak | Tekst wyświetlany opcji (1-5 słów) |
+| `description` | string | Tak | Opis opcji |
+| `markdown` | string | Nie | Zawartość podglądu (do wizualnego porównania układów ASCII, fragmentów kodu itp.) |
+
+## Scenariusze użycia
+
+**Odpowiednie zastosowanie:**
+- Zbieranie preferencji lub wymagań użytkownika
+- Wyjaśnianie niejasnych instrukcji
+- Uzyskiwanie decyzji podczas wdrażania
+- Oferowanie użytkownikowi wyboru kierunku
+
+**Nieodpowiednie zastosowanie:**
+- Pytanie „czy plan jest OK?" — należy użyć ExitPlanMode
+
+## Uwagi
+
+- Użytkownik zawsze może wybrać "Other" i podać własne dane wejściowe
+- Rekomendowana opcja powinna być na pierwszym miejscu, z "(Recommended)" na końcu etykiety
+- Podgląd `markdown` jest obsługiwany tylko dla pytań jednokrotnego wyboru
+- Opcje z `markdown` przełączają się na układ obok siebie (lewo-prawo)
+- W trybie planowania służy do wyjaśniania wymagań przed ustaleniem planu
+
+## Znaczenie w cc-viewer
+
+Wywołanie AskUserQuestion w logach żądań pojawia się jako blok content `tool_use`, zawierający definicje pytań i opcji. Odpowiedź użytkownika pojawia się w historii wiadomości kolejnych żądań.

package/concepts/pl/Tool-Bash.md

@@ -0,0 +1,47 @@
+# Bash
+
+## Definicja
+
+Wykonuje polecenia shell z opcjonalnym ustawieniem limitu czasu. Katalog roboczy jest zachowywany między poleceniami, ale stan shell (zmienne środowiskowe itp.) nie jest zachowywany.
+
+## Parametry
+
+| Parametr | Typ | Wymagany | Opis |
+|------|------|------|------|
+| `command` | string | Tak | Polecenie bash do wykonania |
+| `description` | string | Nie | Krótki opis polecenia |
+| `timeout` | number | Nie | Limit czasu (milisekundy), maks. 600000, domyślnie 120000 |
+| `run_in_background` | boolean | Nie | Czy uruchomić w tle |
+
+## Scenariusze użycia
+
+**Odpowiednie zastosowanie:**
+- Operacje git (commit, push, branch itp.)
+- Polecenia menedżerów pakietów npm/yarn
+- Operacje docker
+- Polecenia kompilacji i budowania
+- Wyświetlanie zawartości katalogów (`ls`)
+- Inne polecenia systemowe wymagające wykonania w shell
+
+**Nieodpowiednie zastosowanie:**
+- Odczyt plików — należy użyć Read
+- Wyszukiwanie nazw plików — należy użyć Glob
+- Wyszukiwanie zawartości plików — należy użyć Grep
+- Edycja plików — należy użyć Edit
+- Zapis plików — należy użyć Write
+- Wyświetlanie informacji użytkownikowi — bezpośrednio w tekście odpowiedzi
+- Długo działające procesy (dev server, tryb watch) — zalecane ręczne uruchomienie przez użytkownika
+
+## Uwagi
+
+- Ścieżki zawierające spacje muszą być ujęte w podwójne cudzysłowy
+- Wyjście przekraczające 30000 znaków zostanie obcięte
+- Wyniki poleceń uruchomionych w tle pobiera się przez TaskOutput
+- Należy używać ścieżek bezwzględnych, unikać `cd`
+- Niezależne polecenia mogą być wywoływane równolegle w wielu Bash
+- Polecenia z zależnościami łączy się za pomocą `&&`
+- Środowisko shell jest inicjalizowane z profilu użytkownika (bash lub zsh)
+
+## Znaczenie w cc-viewer
+
+Wywołania Bash w logach żądań pojawiają się jako pary bloków content `tool_use` (zawierające polecenie) i `tool_result` (zawierające wyjście). Wyjście wykonania polecenia może być wykorzystane do analizy zachowania modelu.

package/concepts/pl/Tool-Edit.md

@@ -0,0 +1,38 @@
+# Edit
+
+## Definicja
+
+Edytuje plik poprzez precyzyjne zastępowanie ciągów znaków. Zastępuje `old_string` w pliku na `new_string`.
+
+## Parametry
+
+| Parametr | Typ | Wymagany | Opis |
+|------|------|------|------|
+| `file_path` | string | Tak | Bezwzględna ścieżka do pliku do modyfikacji |
+| `old_string` | string | Tak | Oryginalny tekst do zastąpienia |
+| `new_string` | string | Tak | Nowy tekst po zastąpieniu (musi różnić się od old_string) |
+| `replace_all` | boolean | Nie | Czy zastąpić wszystkie wystąpienia, domyślnie `false` |
+
+## Scenariusze użycia
+
+**Odpowiednie zastosowanie:**
+- Modyfikacja określonych fragmentów kodu w istniejących plikach
+- Naprawianie błędów, aktualizacja logiki
+- Zmiana nazw zmiennych (w połączeniu z `replace_all: true`)
+- Każdy scenariusz wymagający precyzyjnej modyfikacji zawartości pliku
+
+**Nieodpowiednie zastosowanie:**
+- Tworzenie nowych plików — należy użyć Write
+- Masowe przepisywanie — może wymagać Write do nadpisania całego pliku
+
+## Uwagi
+
+- Przed użyciem należy najpierw odczytać plik za pomocą Read, w przeciwnym razie wystąpi błąd
+- `old_string` musi być unikalny w pliku, w przeciwnym razie edycja się nie powiedzie. Jeśli nie jest unikalny, należy podać więcej kontekstu lub użyć `replace_all`
+- Podczas edycji tekstu należy zachować oryginalne wcięcia (tab/spacje), nie dołączać prefiksów numerów linii z wyjścia Read
+- Preferowana jest edycja istniejących plików zamiast tworzenia nowych
+- `new_string` musi różnić się od `old_string`
+
+## Znaczenie w cc-viewer
+
+Wywołanie Edit w logach żądań pojawia się jako blok content `tool_use`, którego `input` zawiera `old_string` i `new_string`, co pozwala śledzić, jakie modyfikacje model wprowadził w pliku.

package/concepts/pl/Tool-EnterPlanMode.md

@@ -0,0 +1,43 @@
+# EnterPlanMode
+
+## Definicja
+
+Przełącza Claude Code w tryb planowania, służący do eksploracji bazy kodu i projektowania planu przed wdrożeniem.
+
+## Parametry
+
+Brak parametrów.
+
+## Scenariusze użycia
+
+**Odpowiednie zastosowanie:**
+- Implementacja nowych funkcji — wymagane decyzje architektoniczne
+- Istnieje wiele możliwych rozwiązań — wymagany wybór użytkownika
+- Zmiany w kodzie wpływają na istniejące zachowanie lub strukturę
+- Zmiany w wielu plikach — potencjalnie 2-3 lub więcej plików
+- Niejasne wymagania — konieczna eksploracja przed zrozumieniem zakresu
+- Preferencje użytkownika są istotne — implementacja może mieć wiele rozsądnych kierunków
+
+**Nieodpowiednie zastosowanie:**
+- Poprawki jednej lub kilku linii (literówki, oczywiste błędy)
+- Użytkownik podał bardzo konkretne instrukcje
+- Czyste zadania badawcze/eksploracyjne — należy użyć Task (typ Explore)
+
+## Zachowanie w trybie planowania
+
+Po wejściu w tryb planowania Claude Code:
+1. Używa narzędzi Glob, Grep, Read do dogłębnej eksploracji bazy kodu
+2. Rozumie istniejące wzorce i architekturę
+3. Projektuje plan wdrożenia
+4. Przesyła plan do zatwierdzenia przez użytkownika
+5. W razie potrzeby wyjaśnień może użyć AskUserQuestion
+6. Gdy plan jest gotowy, wychodzi przez ExitPlanMode
+
+## Uwagi
+
+- To narzędzie wymaga zgody użytkownika na wejście w tryb planowania
+- W razie wątpliwości, czy planowanie jest potrzebne, lepiej planować — wcześniejsze uzgodnienie jest lepsze niż przerabianie
+
+## Znaczenie w cc-viewer
+
+Wywołanie EnterPlanMode w logach żądań pojawia się jako blok content `tool_use`. Po wejściu w tryb planowania sekwencja żądań zazwyczaj składa się głównie z eksploracyjnych wywołań narzędzi (Glob, Grep, Read), aż do wywołania ExitPlanMode.

package/concepts/pl/Tool-ExitPlanMode.md

@@ -0,0 +1,39 @@
+# ExitPlanMode
+
+## Definicja
+
+Wychodzi z trybu planowania i przesyła plan do zatwierdzenia przez użytkownika. Treść planu jest odczytywana z wcześniej zapisanego pliku planu.
+
+## Parametry
+
+| Parametr | Typ | Wymagany | Opis |
+|------|------|------|------|
+| `allowedPrompts` | array | Nie | Lista opisów uprawnień wymaganych do wdrożenia planu |
+
+Każdy element tablicy `allowedPrompts`:
+
+| Pole | Typ | Wymagany | Opis |
+|------|------|------|------|
+| `tool` | enum | Tak | Odpowiednie narzędzie, obecnie obsługiwane tylko `Bash` |
+| `prompt` | string | Tak | Semantyczny opis operacji (np. "run tests", "install dependencies") |
+
+## Scenariusze użycia
+
+**Odpowiednie zastosowanie:**
+- Plan w trybie planowania jest ukończony, gotowy do przesłania do zatwierdzenia przez użytkownika
+- Tylko dla zadań wdrożeniowych wymagających pisania kodu
+
+**Nieodpowiednie zastosowanie:**
+- Czyste zadania badawcze/eksploracyjne — nie wymagają wyjścia z trybu planowania
+- Chcesz zapytać użytkownika „czy plan jest OK?" — to właśnie funkcja tego narzędzia, nie używaj AskUserQuestion do tego
+
+## Uwagi
+
+- To narzędzie nie przyjmuje treści planu jako parametru — odczytuje ją z wcześniej zapisanego pliku planu
+- Użytkownik zobaczy zawartość pliku planu do zatwierdzenia
+- Nie pytaj za pomocą AskUserQuestion „czy plan jest OK" przed wywołaniem tego narzędzia — to byłoby duplikowanie
+- Nie wspominaj o „planie" w pytaniach, ponieważ użytkownik nie widzi treści planu przed ExitPlanMode
+
+## Znaczenie w cc-viewer
+
+Wywołanie ExitPlanMode oznacza koniec fazy planowania. W logach żądań, żądania po tym wywołaniu zazwyczaj przechodzą do operacji wdrożeniowych (Edit, Write, Bash itp.).

package/concepts/pl/Tool-Glob.md

@@ -0,0 +1,34 @@
+# Glob
+
+## Definicja
+
+Szybkie narzędzie do dopasowywania wzorców nazw plików, obsługujące bazy kodu dowolnej wielkości. Zwraca pasujące ścieżki plików posortowane według czasu modyfikacji.
+
+## Parametry
+
+| Parametr | Typ | Wymagany | Opis |
+|------|------|------|------|
+| `pattern` | string | Tak | Wzorzec glob (np. `**/*.js`, `src/**/*.ts`) |
+| `path` | string | Nie | Katalog wyszukiwania, domyślnie bieżący katalog roboczy. Nie przekazuj "undefined" ani "null" |
+
+## Scenariusze użycia
+
+**Odpowiednie zastosowanie:**
+- Wyszukiwanie plików według wzorca nazwy
+- Wyszukiwanie wszystkich plików określonego typu (np. wszystkie pliki `.tsx`)
+- Lokalizowanie plików przy wyszukiwaniu definicji klasy (np. `class Foo`)
+- Można równolegle wysyłać wiele wywołań Glob w jednej wiadomości
+
+**Nieodpowiednie zastosowanie:**
+- Wyszukiwanie zawartości plików — należy użyć Grep
+- Otwarta eksploracja wymagająca wielu rund wyszukiwania — należy użyć Task (typ Explore)
+
+## Uwagi
+
+- Obsługuje standardową składnię glob: `*` dopasowuje jeden poziom, `**` dopasowuje wiele poziomów, `{}` dopasowuje wielokrotny wybór
+- Wyniki posortowane według czasu modyfikacji
+- Bardziej zalecane niż polecenie `find` w Bash
+
+## Znaczenie w cc-viewer
+
+Wywołania Glob w logach żądań pojawiają się jako pary bloków content `tool_use` / `tool_result`. `tool_result` zawiera listę pasujących ścieżek plików.

package/concepts/pl/Tool-Grep.md

@@ -0,0 +1,47 @@
+# Grep
+
+## Definicja
+
+Potężne narzędzie do wyszukiwania zawartości oparte na ripgrep. Obsługuje wyrażenia regularne, filtrowanie typów plików i wiele trybów wyjścia.
+
+## Parametry
+
+| Parametr | Typ | Wymagany | Opis |
+|------|------|------|------|
+| `pattern` | string | Tak | Wzorzec wyszukiwania wyrażenia regularnego |
+| `path` | string | Nie | Ścieżka wyszukiwania (plik lub katalog), domyślnie bieżący katalog roboczy |
+| `glob` | string | Nie | Filtr nazw plików (np. `*.js`, `*.{ts,tsx}`) |
+| `type` | string | Nie | Filtr typu pliku (np. `js`, `py`, `rust`), wydajniejszy niż glob |
+| `output_mode` | enum | Nie | Tryb wyjścia: `files_with_matches` (domyślny), `content`, `count` |
+| `-i` | boolean | Nie | Wyszukiwanie bez rozróżniania wielkości liter |
+| `-n` | boolean | Nie | Wyświetlanie numerów linii (tylko tryb content), domyślnie true |
+| `-A` | number | Nie | Liczba linii wyświetlanych po dopasowaniu |
+| `-B` | number | Nie | Liczba linii wyświetlanych przed dopasowaniem |
+| `-C` / `context` | number | Nie | Liczba linii wyświetlanych przed i po dopasowaniu |
+| `head_limit` | number | Nie | Limit liczby wyników, domyślnie 0 (bez limitu) |
+| `offset` | number | Nie | Pominięcie pierwszych N wyników |
+| `multiline` | boolean | Nie | Włączenie trybu dopasowywania wieloliniowego, domyślnie false |
+
+## Scenariusze użycia
+
+**Odpowiednie zastosowanie:**
+- Wyszukiwanie określonych ciągów znaków lub wzorców w bazie kodu
+- Znajdowanie miejsc użycia funkcji/zmiennych
+- Filtrowanie wyników wyszukiwania według typu pliku
+- Zliczanie dopasowań
+
+**Nieodpowiednie zastosowanie:**
+- Wyszukiwanie plików według nazwy — należy użyć Glob
+- Otwarta eksploracja wymagająca wielu rund wyszukiwania — należy użyć Task (typ Explore)
+
+## Uwagi
+
+- Używa składni ripgrep (nie grep), znaki specjalne jak nawiasy klamrowe wymagają escapowania
+- Tryb `files_with_matches` zwraca tylko ścieżki plików, najwydajniejszy
+- Tryb `content` zwraca zawartość pasujących linii, obsługuje linie kontekstowe
+- Dopasowywanie wieloliniowe wymaga ustawienia `multiline: true`
+- Zawsze preferuj narzędzie Grep zamiast poleceń `grep` lub `rg` w Bash
+
+## Znaczenie w cc-viewer
+
+Wywołania Grep w logach żądań pojawiają się jako pary bloków content `tool_use` / `tool_result`. `tool_result` zawiera wyniki wyszukiwania.

package/concepts/pl/Tool-NotebookEdit.md

@@ -0,0 +1,33 @@
+# NotebookEdit
+
+## Definicja
+
+Zastępuje, wstawia lub usuwa określoną komórkę w Jupyter notebook (plik .ipynb).
+
+## Parametry
+
+| Parametr | Typ | Wymagany | Opis |
+|------|------|------|------|
+| `notebook_path` | string | Tak | Bezwzględna ścieżka do pliku notebook |
+| `new_source` | string | Tak | Nowa zawartość komórki |
+| `cell_id` | string | Nie | ID komórki do edycji. W trybie wstawiania nowa komórka jest wstawiana po tym ID |
+| `cell_type` | enum | Nie | Typ komórki: `code` lub `markdown`. Wymagany w trybie wstawiania |
+| `edit_mode` | enum | Nie | Tryb edycji: `replace` (domyślny), `insert`, `delete` |
+
+## Scenariusze użycia
+
+**Odpowiednie zastosowanie:**
+- Modyfikacja komórek kodu lub markdown w Jupyter notebook
+- Dodawanie nowych komórek do notebook
+- Usuwanie komórek z notebook
+
+## Uwagi
+
+- `cell_number` jest indeksowany od 0
+- Tryb `insert` wstawia nową komórkę w określonej pozycji
+- Tryb `delete` usuwa komórkę w określonej pozycji
+- Ścieżka musi być bezwzględna
+
+## Znaczenie w cc-viewer
+
+Wywołanie NotebookEdit w logach żądań pojawia się jako blok content `tool_use`, rejestrujący konkretne operacje modyfikacji notebook.

package/concepts/pl/Tool-Read.md

@@ -0,0 +1,41 @@
+# Read
+
+## Definicja
+
+Odczytuje zawartość pliku z lokalnego systemu plików. Obsługuje pliki tekstowe, obrazy, PDF i Jupyter notebook.
+
+## Parametry
+
+| Parametr | Typ | Wymagany | Opis |
+|------|------|------|------|
+| `file_path` | string | Tak | Bezwzględna ścieżka do pliku |
+| `offset` | number | Nie | Numer linii początkowej (do segmentowego odczytu dużych plików) |
+| `limit` | number | Nie | Liczba linii do odczytu (do segmentowego odczytu dużych plików) |
+| `pages` | string | Nie | Zakres stron PDF (np. "1-5", "3", "10-20"), dotyczy tylko PDF |
+
+## Scenariusze użycia
+
+**Odpowiednie zastosowanie:**
+- Odczyt plików kodu, plików konfiguracyjnych i innych plików tekstowych
+- Przeglądanie plików graficznych (Claude jest modelem multimodalnym)
+- Odczyt dokumentów PDF
+- Odczyt Jupyter notebook (zwraca wszystkie komórki z wyjściem)
+- Równoległy odczyt wielu plików w celu uzyskania kontekstu
+
+**Nieodpowiednie zastosowanie:**
+- Odczyt katalogów — należy użyć polecenia `ls` w Bash
+- Otwarta eksploracja bazy kodu — należy użyć Task (typ Explore)
+
+## Uwagi
+
+- Ścieżka musi być bezwzględna, nie może być względna
+- Domyślnie odczytuje pierwsze 2000 linii pliku
+- Linie przekraczające 2000 znaków zostaną obcięte
+- Wyjście używa formatu `cat -n`, numery linii zaczynają się od 1
+- Duże pliki PDF (ponad 10 stron) muszą mieć określony parametr `pages`, maksymalnie 20 stron na raz
+- Odczyt nieistniejącego pliku zwróci błąd (nie spowoduje awarii)
+- Można równolegle wywoływać wiele Read w jednej wiadomości
+
+## Znaczenie w cc-viewer
+
+Wywołania Read w logach żądań pojawiają się jako pary bloków content `tool_use` (wywołanie) i `tool_result` (zwrócona zawartość). `tool_result` zawiera faktyczną zawartość pliku, co pozwala analizować, które pliki model odczytał.

package/concepts/pl/Tool-Skill.md

@@ -0,0 +1,35 @@
+# Skill
+
+## Definicja
+
+Wykonuje umiejętność (skill) w głównej rozmowie. Umiejętności to specjalizowane zdolności, które użytkownik może wywoływać za pomocą slash command (np. `/commit`, `/review-pr`).
+
+## Parametry
+
+| Parametr | Typ | Wymagany | Opis |
+|------|------|------|------|
+| `skill` | string | Tak | Nazwa umiejętności (np. "commit", "review-pr", "pdf") |
+| `args` | string | Nie | Argumenty umiejętności |
+
+## Scenariusze użycia
+
+**Odpowiednie zastosowanie:**
+- Użytkownik wpisał slash command w formacie `/<skill-name>`
+- Żądanie użytkownika pasuje do funkcjonalności zarejestrowanej umiejętności
+
+**Nieodpowiednie zastosowanie:**
+- Wbudowane polecenia CLI (np. `/help`, `/clear`)
+- Umiejętność już jest w trakcie wykonywania
+- Nazwa umiejętności nie znajduje się na liście dostępnych umiejętności
+
+## Uwagi
+
+- Po wywołaniu umiejętność rozwija się w pełny prompt
+- Obsługuje w pełni kwalifikowane nazwy (np. `ms-office-suite:pdf`)
+- Lista dostępnych umiejętności jest podawana w wiadomościach system-reminder
+- Gdy widoczny jest tag `<command-name>`, oznacza to, że umiejętność została załadowana — należy ją bezpośrednio wykonać, a nie ponownie wywoływać to narzędzie
+- Nie wspominaj o umiejętności bez faktycznego wywołania narzędzia
+
+## Znaczenie w cc-viewer
+
+Wywołanie Skill w logach żądań pojawia się jako blok content `tool_use`. Prompt rozwinięty z umiejętności wpływa na system prompt lub zawartość wiadomości kolejnych żądań.