cc-viewer 1.2.1 → 1.2.2

package/concepts/de/Tool-getDiagnostics.md

@@ -0,0 +1,32 @@
+# getDiagnostics (mcp__ide__getDiagnostics)
+
+## Definition
+
+Ruft Sprachdiagnoseinformationen von VS Code ab, einschließlich Syntaxfehler, Typfehler, Lint-Warnungen usw.
+
+## Parameter
+
+| Parameter | Typ | Erforderlich | Beschreibung |
+|-----------|-----|--------------|--------------|
+| `uri` | string | Nein | Datei-URI. Wenn nicht angegeben, werden Diagnoseinformationen aller Dateien abgerufen |
+
+## Anwendungsfälle
+
+**Geeignet für:**
+- Syntax-, Typ-, Lint- und andere semantische Probleme im Code prüfen
+- Nach Codebearbeitung überprüfen, ob neue Fehler eingeführt wurden
+- Als Alternative zu Bash-Befehlen zur Codequalitätsprüfung
+
+**Nicht geeignet für:**
+- Tests ausführen – dafür Bash verwenden
+- Laufzeitfehler prüfen – dafür Code über Bash ausführen
+
+## Hinweise
+
+- Dies ist ein MCP-Tool (Model Context Protocol), bereitgestellt durch die IDE-Integration
+- Nur in VS Code / IDE-Umgebungen verfügbar
+- Dieses Tool gegenüber Bash-Befehlen zur Codeprüfung bevorzugen
+
+## Bedeutung in cc-viewer
+
+getDiagnostics ist ein MCP-Tool und erscheint im `tools`-Array des Anfrage-Logs unter dem Namen `mcp__ide__getDiagnostics`. Aufrufe und Rückgaben folgen dem Standard-`tool_use` / `tool_result`-Muster. Änderungen an MCP-Tools führen zu Änderungen im tools-Array und können einen Cache-Neuaufbau auslösen.

package/concepts/de/Tools.md

@@ -0,0 +1,73 @@
+# Claude Code Tool-Übersicht
+
+Claude Code stellt dem Modell über den tool_use-Mechanismus der Anthropic API eine Reihe integrierter Tools zur Verfügung. Das `tools`-Array jeder MainAgent-Anfrage enthält die vollständigen JSON-Schema-Definitionen dieser Tools, und das Modell ruft sie in der Antwort über `tool_use` Content Blocks auf.
+
+Im Folgenden finden Sie den kategorisierten Index aller Tools.
+
+## Agent-System
+
+| Tool | Zweck |
+|------|-------|
+| [Task](Tool-Task.md) | Startet einen Sub-Agent (SubAgent) für komplexe mehrstufige Aufgaben |
+| [TaskOutput](Tool-TaskOutput.md) | Ruft die Ausgabe von Hintergrundaufgaben ab |
+| [TaskStop](Tool-TaskStop.md) | Stoppt eine laufende Hintergrundaufgabe |
+| [TaskCreate](Tool-TaskCreate.md) | Erstellt einen strukturierten Aufgabenlisteneintrag |
+| [TaskGet](Tool-TaskGet.md) | Ruft Aufgabendetails ab |
+| [TaskUpdate](Tool-TaskUpdate.md) | Aktualisiert Aufgabenstatus, Abhängigkeiten usw. |
+| [TaskList](Tool-TaskList.md) | Listet alle Aufgaben auf |
+
+## Dateioperationen
+
+| Tool | Zweck |
+|------|-------|
+| [Read](Tool-Read.md) | Liest Dateiinhalte (unterstützt Text, Bilder, PDF, Jupyter Notebook) |
+| [Edit](Tool-Edit.md) | Bearbeitet Dateien durch exakte Zeichenkettenersetzung |
+| [Write](Tool-Write.md) | Schreibt oder überschreibt Dateien |
+| [NotebookEdit](Tool-NotebookEdit.md) | Bearbeitet Jupyter-Notebook-Zellen |
+
+## Suche
+
+| Tool | Zweck |
+|------|-------|
+| [Glob](Tool-Glob.md) | Sucht Dateien nach Dateinamenmustern |
+| [Grep](Tool-Grep.md) | Dateiinhaltssuche basierend auf ripgrep |
+
+## Terminal
+
+| Tool | Zweck |
+|------|-------|
+| [Bash](Tool-Bash.md) | Führt Shell-Befehle aus |
+
+## Web
+
+| Tool | Zweck |
+|------|-------|
+| [WebFetch](Tool-WebFetch.md) | Ruft Webinhalte ab und verarbeitet sie mit KI |
+| [WebSearch](Tool-WebSearch.md) | Suchmaschinenabfrage |
+
+## Planung und Interaktion
+
+| Tool | Zweck |
+|------|-------|
+| [EnterPlanMode](Tool-EnterPlanMode.md) | Wechselt in den Planungsmodus zur Entwurfsplanung |
+| [ExitPlanMode](Tool-ExitPlanMode.md) | Verlässt den Planungsmodus und reicht den Plan zur Benutzerfreigabe ein |
+| [AskUserQuestion](Tool-AskUserQuestion.md) | Stellt dem Benutzer Fragen zur Klärung oder Entscheidungsfindung |
+
+## Erweiterungen
+
+| Tool | Zweck |
+|------|-------|
+| [Skill](Tool-Skill.md) | Führt einen Skill (Slash Command) aus |
+
+## IDE-Integration
+
+| Tool | Zweck |
+|------|-------|
+| [getDiagnostics](Tool-getDiagnostics.md) | Ruft VS Code Sprachdiagnoseinformationen ab |
+| [executeCode](Tool-executeCode.md) | Führt Code im Jupyter-Kernel aus |
+
+## Bedeutung in cc-viewer
+
+Tool-Aufrufe gehören zu den wichtigsten beobachtbaren Daten in den Claude Code Anfrage-Logs. Das `tools`-Array jeder MainAgent-Anfrage definiert die verfügbaren Tools des Modells, während die `tool_use` / `tool_result` Content Blocks in der Antwort die tatsächlichen Tool-Aufrufe und Rückgaben aufzeichnen. cc-viewer analysiert diese Daten und rekonstruiert im Chat Mode die vollständige Tool-Aufrufkette.
+
+Änderungen an Tool-Definitionen (z.B. durch MCP-Server-Verbindung/-Trennung verursachte Tool-Änderungen) lösen einen Cache-Neuaufbau aus, siehe [CacheRebuild](CacheRebuild.md).

package/concepts/de/TranslateContextPollution.md

@@ -0,0 +1,46 @@
+# Kontextverschmutzung der Übersetzungs-API
+
+## Hintergrund
+
+CC-Viewer enthält eine integrierte Übersetzungsfunktion (`POST /api/translate`), die von der Anthropic Messages API angetrieben wird. In der frühen Implementierung verwendeten Übersetzungsanfragen die zwischengespeicherten Authentifizierungsdaten der Claude Code-Sitzung wieder — einschließlich der Header `x-api-key` und `authorization`. Dies verursachte ein subtiles, aber schwerwiegendes Problem: Übersetzungsergebnisse lieferten häufig irrelevante Inhalte zurück.
+
+## Ursache
+
+### Grundlegender Unterschied zwischen zwei Authentifizierungsmethoden
+
+Die Anthropic API unterstützt zwei Authentifizierungsmethoden:
+
+| Methode | Header | Typische Quelle | Eigenschaften |
+|---------|--------|-----------------|---------------|
+| API-Schlüssel | `x-api-key: sk-ant-...` | Umgebungsvariable / Console | Zustandslos, jede Anfrage ist unabhängig |
+| OAuth-Token | `authorization: Bearer sessionToken` | Claude Code-Abonnement-Login | Sitzungsgebunden, Server pflegt Kontextzuordnung |
+
+Der entscheidende Unterschied: **API-Schlüssel sind zustandslos** — jede Anfrage ist vollständig unabhängig; während **OAuth-Sitzungstoken zustandsbehaftet sind** — der Anthropic-Server ordnet Anfragen mit demselben Token demselben Sitzungskontext zu.
+
+### Verschmutzungskette
+
+Wenn Claude Code die OAuth-Anmeldung über ein Abonnement verwendet, sieht der Authentifizierungsfluss folgendermaßen aus:
+
+```
+Claude Code Hauptkonversation ──(authorization: Bearer sessionToken)──→ Anthropic API
+                                                                          ↑
+CC-Viewer Übersetzungsanfrage ──(authorization: Bearer sessionToken)──→ Anthropic API
+```
+
+Da Übersetzungsanfragen dasselbe Sitzungstoken wiederverwendeten, konnte der Anthropic-Server Übersetzungsanfragen mit dem Hauptkonversationskontext von Claude Code verknüpfen. Dies führt zu:
+
+1. **Übersetzungsergebnisse werden vom Hauptkonversationskontext beeinflusst**: Der Systemprompt der Übersetzungsanfrage lautet „Du bist ein Übersetzer", aber der Serverkontext enthält weiterhin den Gesprächsverlauf von Claude Code, was das Modell beeinträchtigen kann
+2. **Hauptkonversation wird durch Übersetzungsanfragen gestört**: Inhalte der Übersetzungsanfrage (UI-Textfragmente) können in den Hauptkonversationskontext injiziert werden, wodurch die Antworten von Claude Code abweichen
+3. **Unvorhersehbares Verhalten**: Da die Kontextverschmutzung serverseitiges Verhalten ist, kann der Client sie weder erkennen noch kontrollieren
+
+## Erkenntnisse
+
+- **OAuth-Sitzungstoken sind nicht „einfach ein weiterer API-Schlüssel"** — sie tragen serverseitigen Zustand, ihre Wiederverwendung bedeutet gemeinsame Nutzung des Kontexts
+- **Interne Dienstaufrufe sollten eine unabhängige, zustandslose Authentifizierung verwenden**, um eine Verknüpfung mit Benutzersitzungen zu vermeiden
+
+## Referenzen
+
+- [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/en/BodyDiffJSON.md

@@ -0,0 +1,32 @@
+# Body Diff JSON (Request Body Incremental Comparison)
+
+## Background
+
+Claude Code's MainAgent uses a full-context sending mechanism — each request carries the complete conversation history, system prompt, tool definitions, and more. This means the request body grows increasingly large as the conversation progresses, making it difficult to quickly identify "what was actually added this round" when viewing the raw body.
+
+Body Diff JSON solves exactly this problem: it automatically compares the bodies of two consecutive MainAgent requests, extracts the incremental differences, and lets you see at a glance what content was actually added in the current request.
+
+## How It Works
+
+1. **Identify consecutive MainAgent requests**: The current request must be a MainAgent type, and a previous MainAgent request must exist
+2. **Field-by-field comparison**: Iterates through all top-level fields of the request body, skipping internal properties prefixed with `_`
+3. **Smart diff extraction**:
+   - New fields: Displayed directly
+   - Deleted fields: Not shown (usually doesn't affect understanding)
+   - Changed fields: Shows the current value
+   - `messages` array special handling: Only shows newly added messages (since normal conversation is append-only, prefix messages remain unchanged)
+4. **Request body shrinkage detection**: If the current request body is smaller than the previous one, it indicates context truncation or session reset, and a notice is displayed instead of a diff
+
+## Typical Scenarios
+
+In a normal conversation round, Body Diff JSON typically contains only:
+- `messages`: 1-2 newly added messages (the user's input + the assistant's reply from the previous round)
+
+If you see changes to `system`, `tools`, `model`, or other fields in the diff, it means a configuration change occurred in this round, which is often the cause of a cache rebuild.
+
+## Usage
+
+- Body Diff JSON is displayed in the MainAgent request detail panel
+- Click the title to expand/collapse
+- Supports both JSON and Text viewing modes, plus one-click copy
+- In the top-left **CC-Viewer → Global Settings**, you can set "Expand Body Diff JSON by default"

package/concepts/en/CacheRebuild.md

@@ -0,0 +1,40 @@
+# Cache Rebuild
+
+## Background
+
+Anthropic's prompt caching mechanism concatenates system → tools → messages (up to the cache breakpoint) in order to form the cache key. When the cache key matches the previous request exactly, the API returns `cache_read_input_tokens` (cache hit); when the cache key changes, the API recreates the cache and returns a large number of `cache_creation_input_tokens`, i.e., a cache rebuild.
+
+Cache rebuilds mean additional token charges (cache creation is priced higher than cache read), so identifying rebuild causes has direct value for cost optimization.
+
+## Cache Rebuild Reason Categories
+
+cc-viewer compares the bodies of two consecutive MainAgent requests to precisely determine the cause of a cache rebuild:
+
+| reason | Meaning | Detection Method |
+|--------|---------|------------------|
+| `ttl` | Cache expired | More than 5 minutes since the last MainAgent request |
+| `system_change` | System prompt changed | `JSON.stringify(prev.system) !== JSON.stringify(curr.system)` |
+| `tools_change` | Tool definitions changed | `JSON.stringify(prev.tools) !== JSON.stringify(curr.tools)` |
+| `model_change` | Model switched | `prev.model !== curr.model` |
+| `msg_truncated` | Message stack truncated | Current request has fewer messages than the previous one, usually triggered by context window overflow |
+| `msg_modified` | Historical messages modified | Prefix message content is inconsistent (prefix should be identical during normal appending) |
+| `key_change` | Unknown key change | Fallback when none of the above conditions match |
+
+## Detection Priority
+
+1. First check the time interval — if more than 5 minutes, immediately classify as `ttl` without body comparison
+2. Then check model, system, tools, and messages in sequence
+3. A single request may match multiple reasons (e.g., model switch + system prompt change), in which case the `reasons` array contains all matches and the tooltip displays them on separate lines
+
+## Common Scenarios
+
+- **`ttl`**: The user paused for more than 5 minutes before continuing, and the cache naturally expired
+- **`system_change`**: Claude Code updated the system prompt (e.g., loaded new CLAUDE.md, project instructions changed)
+- **`tools_change`**: MCP server connection/disconnection caused changes to the available tool list
+- **`model_change`**: The user switched models via the `/model` command
+- **`msg_truncated`**: A long conversation triggered context window management, and Claude Code truncated earlier messages
+- **`msg_modified`**: Claude Code edited historical messages (e.g., `/compact` replaced original messages with a compressed summary)
+
+## Display in cc-viewer
+
+In the request list, requests with cache rebuilds show a red dot indicator on the cache row. Hovering displays a tooltip with the specific rebuild reason description (supports 18 languages).

package/concepts/en/MainAgent.md

@@ -0,0 +1,30 @@
+# MainAgent
+
+## Definition
+
+MainAgent is the primary request chain in Claude Code when not in agent team mode. Every interaction between the user and Claude Code produces a series of API requests, where MainAgent requests form the core conversation chain — they carry the complete system prompt, tool definitions, and message history.
+
+## Identification
+
+In cc-viewer, MainAgent is identified by `req.mainAgent === true`, automatically tagged by `interceptor.js` during request capture.
+
+Criteria (all must be met):
+- The request body contains a `system` field (system prompt)
+- The request body contains a `tools` array (tool definitions)
+- The system prompt contains "Claude Code" signature text
+
+## Differences from SubAgent
+
+| Feature | MainAgent | SubAgent |
+|---------|-----------|----------|
+| system prompt | Complete Claude Code main prompt | Streamlined task-specific prompt |
+| tools array | Contains all available tools | Usually contains only a few tools needed for the task |
+| Message history | Accumulates full conversation context | Contains only sub-task related messages |
+| Caching behavior | Has prompt caching (5-minute TTL) | Usually no caching or smaller cache |
+
+## Significance in cc-viewer
+
+- **Cache tracking**: The prompt caching status of MainAgent requests directly affects costs. By monitoring the ratio of `cache_creation_input_tokens` to `cache_read_input_tokens`, you can assess cache hit rates
+- **Cache miss analysis**: When MainAgent requests show large amounts of cache creation (rather than cache read), it indicates cache misses and rebuilds. cc-viewer marks these requests with a red dot indicator
+- **Main chain analysis**: The MainAgent request sequence reflects the complete interaction between the user and Claude Code, serving as the core data for analyzing session behavior
+- **Session reconstruction**: cc-viewer reconstructs the conversation view (Chat Mode) from MainAgent request message history

package/concepts/en/Tool-AskUserQuestion.md

@@ -0,0 +1,54 @@
+# AskUserQuestion
+
+## Definition
+
+Asks the user a question during execution to obtain clarification, validate assumptions, or request decisions.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `questions` | array | Yes | List of questions (1-4 questions) |
+| `answers` | object | No | Answers collected from the user |
+| `annotations` | object | No | Annotations for each question (e.g., notes for preview selections) |
+| `metadata` | object | No | Metadata for tracking and analysis |
+
+Each `question` object:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `question` | string | Yes | Full question text, should end with a question mark |
+| `header` | string | Yes | Short label (max 12 characters), displayed as a tag chip |
+| `options` | array | Yes | 2-4 options |
+| `multiSelect` | boolean | Yes | Whether multiple selections are allowed |
+
+Each `option` object:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `label` | string | Yes | Option display text (1-5 words) |
+| `description` | string | Yes | Option description |
+| `markdown` | string | No | Preview content (for visual comparison of ASCII layouts, code snippets, etc.) |
+
+## Use Cases
+
+**Good for:**
+- Collecting user preferences or requirements
+- Clarifying ambiguous instructions
+- Getting decisions during implementation
+- Providing directional choices to the user
+
+**Not good for:**
+- Asking "Is the plan okay?" — use ExitPlanMode instead
+
+## Notes
+
+- The user can always choose "Other" to provide custom input
+- Place the recommended option first and append "(Recommended)" to its label
+- `markdown` preview is only supported for single-select questions
+- Options with `markdown` switch to a side-by-side layout
+- In plan mode, used to clarify requirements before finalizing the plan
+
+## Significance in cc-viewer
+
+AskUserQuestion calls appear in request logs as `tool_use` content blocks containing the question and option definitions. The user's answers appear in the message history of subsequent requests.

package/concepts/en/Tool-Bash.md

@@ -0,0 +1,47 @@
+# Bash
+
+## Definition
+
+Executes shell commands with optional timeout settings. The working directory persists between commands, but shell state (environment variables, etc.) does not persist.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `command` | string | Yes | The bash command to execute |
+| `description` | string | No | A short description of the command |
+| `timeout` | number | No | Timeout in milliseconds, max 600000, default 120000 |
+| `run_in_background` | boolean | No | Whether to run in the background |
+
+## Use Cases
+
+**Good for:**
+- git operations (commit, push, branch, etc.)
+- npm/yarn and other package management commands
+- docker operations
+- Compilation and build commands
+- Listing directory contents (`ls`)
+- Other system commands that require shell execution
+
+**Not good for:**
+- Reading files — use Read instead
+- Searching for filenames — use Glob instead
+- Searching file contents — use Grep instead
+- Editing files — use Edit instead
+- Writing files — use Write instead
+- Outputting information to the user — output directly in the response text
+- Long-running processes (dev server, watch mode) — recommend the user run them manually
+
+## Notes
+
+- Paths containing spaces must be wrapped in double quotes
+- Output exceeding 30000 characters will be truncated
+- Background commands retrieve results via TaskOutput
+- Use absolute paths whenever possible, avoid `cd`
+- Independent commands can invoke multiple Bash calls in parallel
+- Dependent commands should be chained with `&&`
+- The shell environment is initialized from the user's profile (bash or zsh)
+
+## Significance in cc-viewer
+
+Bash calls appear in request logs as `tool_use` (containing the command) and `tool_result` (containing the output) content block pairs. The command execution output can be used to analyze the model's operational behavior.

package/concepts/en/Tool-Edit.md

@@ -0,0 +1,38 @@
+# Edit
+
+## Definition
+
+Edits files via exact string replacement. Replaces `old_string` with `new_string` in the file.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `file_path` | string | Yes | Absolute path of the file to modify |
+| `old_string` | string | Yes | The original text to replace |
+| `new_string` | string | Yes | The new replacement text (must differ from old_string) |
+| `replace_all` | boolean | No | Whether to replace all matches, default `false` |
+
+## Use Cases
+
+**Good for:**
+- Modifying specific code sections in existing files
+- Fixing bugs, updating logic
+- Renaming variables (with `replace_all: true`)
+- Any scenario requiring precise file content modification
+
+**Not good for:**
+- Creating new files — use Write instead
+- Large-scale rewrites — may need Write to overwrite the entire file
+
+## Notes
+
+- You must first read the file via Read before using this tool, otherwise it will error
+- `old_string` must be unique in the file, otherwise the edit fails. If not unique, provide more context to make it unique, or use `replace_all`
+- When editing text, preserve the original indentation (tabs/spaces); do not include the line number prefix from Read output
+- Prefer editing existing files over creating new ones
+- `new_string` must differ from `old_string`
+
+## Significance in cc-viewer
+
+Edit calls appear in request logs as `tool_use` content blocks, with `input` containing `old_string` and `new_string`, which can be used to track what modifications the model made to files.

package/concepts/en/Tool-EnterPlanMode.md

@@ -0,0 +1,43 @@
+# EnterPlanMode
+
+## Definition
+
+Switches Claude Code into plan mode for exploring the codebase and designing an implementation plan before execution.
+
+## Parameters
+
+No parameters.
+
+## Use Cases
+
+**Good for:**
+- New feature implementation — requires architectural decisions
+- Multiple viable approaches exist — requires user selection
+- Code changes affect existing behavior or structure
+- Multi-file changes — potentially involving 2-3 or more files
+- Requirements are unclear — need to explore first to understand scope
+- User preferences matter — implementation can go in multiple reasonable directions
+
+**Not good for:**
+- Single-line or few-line fixes (typos, obvious bugs)
+- The user has given very specific instructions
+- Pure research/exploration tasks — use Task (Explore type) instead
+
+## Behavior in Plan Mode
+
+After entering plan mode, Claude Code will:
+1. Use Glob, Grep, and Read tools to deeply explore the codebase
+2. Understand existing patterns and architecture
+3. Design an implementation plan
+4. Submit the plan for user approval
+5. Use AskUserQuestion if clarification is needed
+6. Exit via ExitPlanMode when the plan is ready
+
+## Notes
+
+- This tool requires user consent to enter plan mode
+- When unsure whether planning is needed, lean toward planning — aligning upfront is better than rework
+
+## Significance in cc-viewer
+
+EnterPlanMode calls appear in request logs as `tool_use` content blocks. The request sequence after entering plan mode is typically dominated by exploratory tool calls (Glob, Grep, Read) until ExitPlanMode is called.

package/concepts/en/Tool-ExitPlanMode.md

@@ -0,0 +1,39 @@
+# ExitPlanMode
+
+## Definition
+
+Exits plan mode and submits the plan for user approval. The plan content is read from a previously written plan file.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `allowedPrompts` | array | No | List of permission descriptions required for the implementation plan |
+
+Each element in the `allowedPrompts` array:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `tool` | enum | Yes | The applicable tool, currently only supports `Bash` |
+| `prompt` | string | Yes | Semantic description of the operation (e.g., "run tests", "install dependencies") |
+
+## Use Cases
+
+**Good for:**
+- The plan is complete in plan mode and ready for user approval
+- Only for implementation tasks that require writing code
+
+**Not good for:**
+- Pure research/exploration tasks — no need to exit plan mode
+- Asking the user "Is the plan okay?" — that is exactly what this tool does, do not use AskUserQuestion for that
+
+## Notes
+
+- This tool does not accept plan content as a parameter — it reads from a previously written plan file
+- The user will see the plan file content for approval
+- Do not use AskUserQuestion to ask "Is the plan okay?" before calling this tool, as that would be redundant
+- Do not mention "the plan" in questions, since the user cannot see the plan content before ExitPlanMode
+
+## Significance in cc-viewer
+
+ExitPlanMode calls mark the end of the planning phase. In request logs, requests after this call typically shift to implementation operations (Edit, Write, Bash, etc.).

package/concepts/en/Tool-Glob.md

@@ -0,0 +1,34 @@
+# Glob
+
+## Definition
+
+A fast file pattern matching tool that works with any codebase size. Returns matching file paths sorted by modification time.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `pattern` | string | Yes | Glob pattern (e.g., `**/*.js`, `src/**/*.ts`) |
+| `path` | string | No | Search directory, defaults to the current working directory. Do not pass "undefined" or "null" |
+
+## Use Cases
+
+**Good for:**
+- Finding files by filename pattern
+- Finding all files of a specific type (e.g., all `.tsx` files)
+- Locating files first when searching for a specific class definition (e.g., `class Foo`)
+- Multiple Glob calls can be issued in parallel within a single message
+
+**Not good for:**
+- Searching file contents — use Grep instead
+- Open-ended exploration requiring multiple rounds of searching — use Task (Explore type) instead
+
+## Notes
+
+- Supports standard glob syntax: `*` matches single level, `**` matches multiple levels, `{}` matches alternatives
+- Results are sorted by modification time
+- Preferred over the `find` command in Bash
+
+## Significance in cc-viewer
+
+Glob calls appear in request logs as `tool_use` / `tool_result` content block pairs. The `tool_result` contains the list of matched file paths.

package/concepts/en/Tool-Grep.md

@@ -0,0 +1,47 @@
+# Grep
+
+## Definition
+
+A powerful content search tool based on ripgrep. Supports regular expressions, file type filtering, and multiple output modes.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `pattern` | string | Yes | Regular expression search pattern |
+| `path` | string | No | Search path (file or directory), defaults to current working directory |
+| `glob` | string | No | Filename filter (e.g., `*.js`, `*.{ts,tsx}`) |
+| `type` | string | No | File type filter (e.g., `js`, `py`, `rust`), more efficient than glob |
+| `output_mode` | enum | No | Output mode: `files_with_matches` (default), `content`, `count` |
+| `-i` | boolean | No | Case-insensitive search |
+| `-n` | boolean | No | Show line numbers (content mode only), default true |
+| `-A` | number | No | Number of lines to show after a match |
+| `-B` | number | No | Number of lines to show before a match |
+| `-C` / `context` | number | No | Number of lines to show before and after a match |
+| `head_limit` | number | No | Limit the number of output entries, default 0 (unlimited) |
+| `offset` | number | No | Skip the first N results |
+| `multiline` | boolean | No | Enable multiline matching mode, default false |
+
+## Use Cases
+
+**Good for:**
+- Searching for specific strings or patterns in the codebase
+- Finding where functions/variables are used
+- Filtering search results by file type
+- Counting the number of matches
+
+**Not good for:**
+- Finding files by filename — use Glob instead
+- Open-ended exploration requiring multiple rounds of searching — use Task (Explore type) instead
+
+## Notes
+
+- Uses ripgrep syntax (not grep); special characters like braces need escaping
+- `files_with_matches` mode returns only file paths, most efficient
+- `content` mode returns matching line content, supports context lines
+- Multiline matching requires setting `multiline: true`
+- Always prefer the Grep tool over `grep` or `rg` commands in Bash
+
+## Significance in cc-viewer
+
+Grep calls appear in request logs as `tool_use` / `tool_result` content block pairs. The `tool_result` contains the search results.

package/concepts/en/Tool-NotebookEdit.md

@@ -0,0 +1,33 @@
+# NotebookEdit
+
+## Definition
+
+Replaces, inserts, or deletes specific cells in a Jupyter notebook (.ipynb file).
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `notebook_path` | string | Yes | Absolute path of the notebook file |
+| `new_source` | string | Yes | New content for the cell |
+| `cell_id` | string | No | ID of the cell to edit. In insert mode, the new cell is inserted after this ID |
+| `cell_type` | enum | No | Cell type: `code` or `markdown`. Required in insert mode |
+| `edit_mode` | enum | No | Edit mode: `replace` (default), `insert`, `delete` |
+
+## Use Cases
+
+**Good for:**
+- Modifying code or markdown cells in a Jupyter notebook
+- Adding new cells to a notebook
+- Deleting cells from a notebook
+
+## Notes
+
+- `cell_number` is 0-indexed
+- `insert` mode inserts a new cell at the specified position
+- `delete` mode deletes the cell at the specified position
+- The path must be an absolute path
+
+## Significance in cc-viewer
+
+NotebookEdit calls appear in request logs as `tool_use` content blocks, recording the specific modification operations on the notebook.

package/concepts/en/Tool-Read.md

@@ -0,0 +1,41 @@
+# Read
+
+## Definition
+
+Reads file contents from the local filesystem. Supports text files, images, PDFs, and Jupyter notebooks.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `file_path` | string | Yes | Absolute path of the file |
+| `offset` | number | No | Starting line number (for reading large files in segments) |
+| `limit` | number | No | Number of lines to read (for reading large files in segments) |
+| `pages` | string | No | PDF page range (e.g., "1-5", "3", "10-20"), only applicable to PDFs |
+
+## Use Cases
+
+**Good for:**
+- Reading code files, configuration files, and other text files
+- Viewing image files (Claude is a multimodal model)
+- Reading PDF documents
+- Reading Jupyter notebooks (returns all cells with outputs)
+- Reading multiple files in parallel to gather context
+
+**Not good for:**
+- Reading directories — use the `ls` command in Bash instead
+- Open-ended codebase exploration — use Task (Explore type) instead
+
+## Notes
+
+- The path must be an absolute path, not a relative path
+- Reads the first 2000 lines of a file by default
+- Lines exceeding 2000 characters will be truncated
+- Output uses `cat -n` format, with line numbers starting at 1
+- Large PDFs (over 10 pages) must specify the `pages` parameter, max 20 pages per call
+- Reading a non-existent file returns an error (does not crash)
+- Multiple Read calls can be issued in parallel within a single message
+
+## Significance in cc-viewer
+
+Read calls appear in request logs as `tool_use` (invocation) and `tool_result` (returned content) content block pairs. The `tool_result` contains the actual file content, which can be used to analyze which files the model read.