cx-viewer 1.0.0

package/concepts/de/UltraPlan.md

@@ -0,0 +1,55 @@
+# UltraPlan — Die ultimative Wunschmaschine
+
+## Was ist UltraPlan
+
+UltraPlan ist die **lokalisierte Implementierung** von cc-viewer fuer den nativen `/ultraplan`-Befehl von Claude Code. Es ermoeglicht Ihnen, die vollstaendigen Funktionen von `/ultraplan` in Ihrer lokalen Umgebung zu nutzen, **ohne Claudes offiziellen Remote-Dienst starten zu muessen**, und leitet Claude Code an, komplexe Planungs- und Implementierungsaufgaben mittels **Multi-Agenten-Zusammenarbeit** zu bewaeltigen.
+
+Im Vergleich zum regulaeren Plan-Modus oder Agent Team kann UltraPlan:
+- Automatisch die Aufgabenkomplexitaet bewerten und die optimale Planungsstrategie waehlen
+- Mehrere parallele Agenten einsetzen, um die Codebasis aus verschiedenen Dimensionen zu erkunden
+- Externe Recherche (webSearch) fuer branchenbewaehrte Verfahren einbeziehen
+- Nach der Planausfuehrung automatisch ein Code Review Team zusammenstellen
+- Einen vollstaendigen **Plan → Execute → Review → Fix** Kreislauf bilden
+
+---
+
+## Wichtige Hinweise
+
+### 1. UltraPlan ist nicht allmaechtig
+UltraPlan ist eine leistungsfaehigere Wunschmaschine, aber das bedeutet nicht, dass jeder Wunsch erfuellt werden kann. Es ist leistungsfaehiger als Plan und Agent Team, kann aber nicht direkt „Geld fuer Sie verdienen". Beruecksichtigen Sie eine angemessene Aufgabengranularitaet — zerlegen Sie grosse Ziele in ausfuehrbare mittelgrosse Aufgaben, anstatt alles auf einmal erreichen zu wollen.
+
+### 2. Derzeit am effektivsten fuer Programmierprojekte
+Die Vorlagen und Workflows von UltraPlan sind tiefgehend fuer Programmierprojekte optimiert. Andere Szenarien (Dokumentation, Datenanalyse usw.) koennen ausprobiert werden, aber es empfiehlt sich, auf Anpassungen in zukuenftigen Versionen zu warten.
+
+### 3. Ausfuehrungszeit und Kontextfenster-Anforderungen
+- Eine erfolgreiche UltraPlan-Ausfuehrung dauert in der Regel **30 Minuten oder laenger**
+- Erfordert, dass der MainAgent ein grosses Kontextfenster hat (1M-Context-Opus-Modell empfohlen)
+- Wenn Sie nur ein 200K-Modell haben, **fuehren Sie unbedingt `/clear` vor der Ausfuehrung aus**
+- Claude Codes `/compact` funktioniert schlecht bei unzureichendem Kontextfenster — vermeiden Sie es, den Platz aufzubrauchen
+- Ausreichend Kontextplatz zu erhalten ist eine entscheidende Voraussetzung fuer eine erfolgreiche UltraPlan-Ausfuehrung
+
+Wenn Sie Fragen oder Vorschlaege zum lokalisierten UltraPlan haben, eroeffnen Sie gerne [Issues auf GitHub](https://github.com/anthropics/claude-code/issues), um zu diskutieren und zusammenzuarbeiten.
+
+---
+
+## Funktionsweise
+
+UltraPlan bietet zwei Betriebsmodi:
+
+### Automatischer Modus
+Analysiert automatisch die Aufgabenkomplexitaet (Score 4-12) und leitet an verschiedene Strategien weiter:
+
+| Route | Score | Strategie |
+|-------|-------|-----------|
+| Route A | 4-6 | Leichtgewichtige Planung mit direkter Code-Erkundung |
+| Route B | 7-9 | Planung mit Strukturdiagrammen (Mermaid / ASCII) |
+| Route C | 10-12 | Multi-Agenten-Erkundung + Review-Kreislauf |
+
+### Erzwungener Modus
+Aktiviert direkt den vollstaendigen Route-C-Multi-Agenten-Workflow:
+1. Bis zu 5 parallele Agenten einsetzen, die gleichzeitig die Codebasis erkunden (Architektur, Dateiidentifikation, Risikobewertung usw.)
+2. Optional einen Recherche-Agenten einsetzen, um ueber webSearch Branchenloesungen zu untersuchen
+3. Alle Agenten-Erkenntnisse zu einem detaillierten Implementierungsplan zusammenfassen
+4. Einen Review-Agenten einsetzen, der den Plan aus mehreren Perspektiven prueft
+5. Den Plan nach Genehmigung ausfuehren
+6. Nach der Implementierung automatisch ein Code Review Team zusammenstellen, um die Codequalitaet zu validieren

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/BodyFields.md

@@ -0,0 +1,42 @@
+# Request Body Fields
+
+Field descriptions for the top-level fields in the Claude API `/v1/messages` request body.
+
+## Field List
+
+| Field | Type | Description |
+|-------|------|-------------|
+| **model** | string | The model name to use, e.g. `claude-opus-4-6`, `claude-sonnet-4-6` |
+| **messages** | array | Conversation message history. Each message contains `role` (user/assistant) and `content` (an array of blocks such as text, image, tool_use, tool_result, etc.) |
+| **system** | array | System prompt. Contains Codex's core instructions, tool usage guidelines, environment information, CLAUDE.md contents, etc. Blocks with `cache_control` are subject to prompt caching |
+| **tools** | array | List of available tool definitions. Each tool contains `name`, `description`, and `input_schema` (JSON Schema). MainAgent typically has 20+ tools, while SubAgent has only a few |
+| **metadata** | object | Request metadata, usually containing `user_id` to identify the user |
+| **max_tokens** | number | Maximum number of tokens for a single model response, e.g. `16000`, `64000` |
+| **thinking** | object | Extended thinking configuration. `type: "enabled"` activates thinking mode, `budget_tokens` controls the thinking token limit |
+| **context_management** | object | Context management configuration. `truncation: "auto"` allows Codex to automatically truncate overly long message histories |
+| **output_config** | object | Output configuration, such as `format` settings |
+| **stream** | boolean | Whether to enable streaming responses. Codex always uses `true` |
+
+## messages Structure
+
+The `content` of each message is an array of blocks. Common types include:
+
+- **text**: Plain text content
+- **tool_use**: Model tool invocation (contains `name`, `input`)
+- **tool_result**: Tool execution result (contains `tool_use_id`, `content`)
+- **image**: Image content (base64 or URL)
+- **thinking**: Model's thinking process (extended thinking mode)
+
+## system Structure
+
+The system prompt array typically contains:
+
+1. **Core agent instructions** ("You are Codex...")
+2. **Tool usage guidelines**
+3. **CLAUDE.md contents** (project-level instructions)
+4. **Skills reminders** (skills reminder)
+5. **Environment information** (OS, shell, git status, etc.) — In fact, Codex relies heavily on git. If a project has a git repository, Codex demonstrates a better understanding of the project, including the ability to pull remote changes and commit history to assist with analysis
+
+Blocks marked with `cache_control: { type: "ephemeral" }` are cached by the Anthropic API for 5 minutes. When cache hits occur, they are billed as `cache_read_input_tokens` (significantly cheaper than `input_tokens`).
+
+> **Note**: For special clients like Codex, the Anthropic server does not rely entirely on the `cache_control` attribute in the request to determine caching behavior. The server automatically applies caching strategies to specific fields (such as system prompt and tools definitions), even when the request does not explicitly include `cache_control` markers. Therefore, don't be puzzled when you don't see this attribute in the request body — the server has already performed caching behind the scenes, it simply doesn't expose this information to the client. This is a tacit understanding between Codex and the Anthropic API.

package/concepts/en/CacheRebuild.md

@@ -0,0 +1,36 @@
+# 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)

package/concepts/en/GlobalSettings.md

@@ -0,0 +1,232 @@
+# CC-Viewer Configuration Reference
+
+## 1. Global Settings Panel (UI)
+
+Open via top-left menu → "Global Settings".
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| Filter Irrelevant Requests | Switch | On | Hide heartbeat, count_tokens, sub-agent and other non-main-agent requests |
+| Expand Body Diff JSON | Switch | Off | Expand Body Diff section by default in request detail panel |
+| Log Directory | Text Input | `~/.claude/cc-viewer` | Root directory for project log read/write. Supports `~/` expansion. Takes effect immediately on Enter or blur |
+
+## 2. Display Settings Panel (UI)
+
+Open via top-left menu → "Display Settings".
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| Collapse Tool Results | Switch | On | Collapse tool call result blocks in chat view |
+| Expand Thinking | Switch | On | Expand Claude's thinking/reasoning blocks by default |
+| Show Full Tool Content | Switch | Off | Show full untruncated tool call content |
+| Auto Resume Session | Switch + Options | Off | Automatically choose when session resume prompt appears: `Continue` or `New` |
+
+## 3. Preferences File
+
+All UI settings are persisted to `<log_dir>/preferences.json` via the `/api/preferences` API.
+
+```json
+{
+  "lang": "en",
+  "filterIrrelevant": true,
+  "expandDiff": false,
+  "collapseToolResults": true,
+  "expandThinking": true,
+  "showFullToolContent": false,
+  "logDir": "~/.claude/cc-viewer",
+  "resumeAutoChoice": null,
+  "disabledPlugins": [],
+  "presetShortcuts": []
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `lang` | string | UI language (zh/en/zh-TW/ko/ja/de/es/fr/it/da/pl/ru/ar/no/pt-BR/th/tr/uk) |
+| `filterIrrelevant` | boolean | Filter irrelevant requests |
+| `expandDiff` | boolean | Expand Body Diff JSON by default |
+| `collapseToolResults` | boolean | Collapse tool results |
+| `expandThinking` | boolean | Expand thinking blocks |
+| `showFullToolContent` | boolean | Show full content |
+| `logDir` | string | Log directory path |
+| `resumeAutoChoice` | null / "continue" / "new" | Auto resume session choice |
+| `disabledPlugins` | string[] | Disabled plugin filenames |
+| `presetShortcuts` | array | Agent Team preset shortcuts |
+
+## 4. Environment Variables
+
+### CC-Viewer Specific
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CCV_LOG_DIR` | `~/.claude/cc-viewer` | Log storage root directory. Special values: `tmp`/`temp` use system temp dir |
+| `CCV_CLI_MODE` | unset | `=1` enables CLI mode (PTY terminal) |
+| `CCV_SDK_MODE` | unset | `=1` enables Agent SDK mode (no terminal) |
+| `CCV_WORKSPACE_MODE` | unset | `=1` enables workspace selection mode |
+| `CCV_PROJECT_DIR` | `process.cwd()` | Project working directory for file operations and Git commands |
+| `CCV_PROXY_PORT` | unset | Local MITM proxy port |
+| `CCV_BYPASS_PERMISSIONS` | unset | `=1` skip tool permission approval (with `--dangerously-skip-permissions`) |
+| `CCV_DISABLE_DELTA` | unset | `=1` disable incremental log storage, write full messages every time |
+| `CCV_DEBUG` | unset | `=1` enable HTTP proxy debug logging |
+| `CCV_DEBUG_PLUGINS` | unset | `=1` enable plugin loading debug logging |
+
+### Internal IPC
+
+| Variable | Description |
+|----------|-------------|
+| `CCVIEWER_PORT` | Server port for ask-bridge/perm-bridge communication |
+| `CCV_EDITOR_PORT` | Server port for ccv-editor file editing bridge |
+
+### External (Read-only)
+
+| Variable | Description |
+|----------|-------------|
+| `ANTHROPIC_BASE_URL` | Custom Anthropic API address |
+| `SHELL` | User's shell (PTY spawn and shell config detection) |
+| `http_proxy` / `HTTPS_PROXY` etc. | HTTP proxy config (via undici EnvHttpProxyAgent) |
+
+## 5. CLI Arguments
+
+```
+ccv [options] [claude args...]
+```
+
+### CC-Viewer Options
+
+| Argument | Description |
+|----------|-------------|
+| `-logger` | Install/repair Claude Code hooks |
+| `--uninstall` / `-uninstall` | Remove all CC-Viewer integration |
+| `--help` / `-h` / `help` | Show help text |
+| `--version` / `-v` | Show version |
+| `-SDK` / `--sdk` | Use Agent SDK mode |
+| `--d` | Shortcut for `--dangerously-skip-permissions` |
+| `--ad` | Shortcut for `--allow-dangerously-skip-permissions` |
+| `run` | Run command through proxy (`ccv run -- claude ...`) |
+
+### Claude Pass-through (common)
+
+| Argument | Description |
+|----------|-------------|
+| `-c` / `--continue` | Continue last session |
+| `-r` / `--resume` | Resume specific session |
+| `-p` / `--print` | Non-interactive output |
+| `--model` | Specify model |
+| `--permission-mode` | Permission mode |
+| `--system-prompt` | Custom system prompt |
+| `--max-budget-usd` | Maximum budget |
+
+## 6. Hook Configuration
+
+CC-Viewer auto-registers hooks in `~/.claude/settings.json` under `hooks.PreToolUse`:
+
+### 1. AskUserQuestion Bridge
+- **Matcher**: `"AskUserQuestion"`
+- **Command**: `node <install_dir>/lib/ask-bridge.js`
+- **Purpose**: Forward Claude's questions to Web UI, wait for user answers
+
+### 2. Permission Approval Bridge
+- **Matcher**: `""` (empty = match all tools)
+- **Command**: `node <install_dir>/lib/perm-bridge.js`
+- **Purpose**: Only `Bash`/`Edit`/`Write`/`NotebookEdit` require Web UI approval; others pass through
+
+## 7. Shell Integration
+
+CC-Viewer injects a `claude()` function into `~/.zshrc` (or `.bashrc`):
+
+```bash
+# >>> CC-Viewer Auto-Inject >>>
+claude() { ... }
+# <<< CC-Viewer Auto-Inject <<<
+```
+
+All `claude` commands are automatically routed through CC-Viewer proxy for log capture and Web UI features.
+
+Uninstall: `ccv --uninstall` or manually delete content between the markers.
+
+## 8. Proxy Configuration (Proxy Profile)
+
+Stored in `<log_dir>/profile.json`, managed via the "Proxy Switch" panel in the UI.
+
+```json
+{
+  "active": "max",
+  "profiles": [
+    { "id": "max", "name": "Default" },
+    { "id": "my-proxy", "name": "Custom", "baseURL": "https://...", "apiKey": "sk-..." }
+  ]
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `active` | Active profile ID (`"max"` = direct connection, no proxy) |
+| `id` | Unique identifier |
+| `name` | Display name |
+| `baseURL` | Proxy API address (replaces request origin) |
+| `apiKey` | Proxy API key (replaces auth headers) |
+| `models` | Available model list |
+| `activeModel` | Currently selected model |
+
+## 9. Plugin System
+
+Plugin directory: `<log_dir>/plugins/`
+
+### Supported Hook Types
+
+| Hook | Type | Description |
+|------|------|-------------|
+| `httpsOptions` | Waterfall | Provide HTTPS certificate (return `{ cert, key }` or `{ pfx }`) |
+| `localUrl` | Waterfall | Modify local access URL |
+| `serverStarted` | Parallel | Server startup notification |
+| `serverStopping` | Parallel | Server shutdown notification |
+| `onNewEntry` | Parallel | New log entry written notification |
+
+Plugin enable/disable managed via `disabledPlugins` array in `preferences.json`.
+
+## 10. Directory Structure
+
+```
+~/.claude/cc-viewer/               # Log root directory
+├── preferences.json               # User preferences
+├── workspaces.json                # Workspace registry
+├── profile.json                   # Proxy configuration
+├── plugins/                       # Plugin directory
+│   └── my-plugin.js
+├── <project>/                     # Per-project log directory
+│   ├── <project>_20260404_123456.jsonl  # JSONL log files
+│   ├── <project>.json             # Stats data (background generated)
+│   └── images/                    # Persistent uploaded image copies
+└── ...
+
+/tmp/cc-viewer-uploads/            # Temporary upload file directory
+```
+
+## 11. Server Configuration
+
+| Setting | Value | Description |
+|---------|-------|-------------|
+| Port range | 7008-7099 | Auto-scans for available port |
+| Bind address | 0.0.0.0 | All network interfaces |
+| Access token | Random 16-byte hex | LAN access requires `?token=xxx`; localhost is exempt |
+| HTTPS | Plugin only | Requires plugin providing `httpsOptions` hook |
+| CORS | `*` | All origins allowed |
+| Upload limit | 50MB | Maximum single file upload size |
+
+## 12. URL Parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| `?token=xxx` | LAN access authentication token |
+| `?logfile=path` | Open specific historical log file (read-only mode) |
+
+## 13. localStorage Settings
+
+| Key | Description |
+|-----|-------------|
+| `cxv_cacheExpireAt` | Cache countdown expiration time |
+| `cxv_cacheType` | Cache type label |
+| `ccv_sseSlim` | Enable SSE incremental pruning (desktop performance optimization) |
+| `ccv_calibrationModel` | KV-Cache context window calibration model |
+| `ccv_fileExplorerOpen` | File explorer panel toggle |
+| `cc-viewer-terminal-width` | Terminal panel width (pixels) |

package/concepts/en/KVCacheContent.md

@@ -0,0 +1,49 @@
+# KV-Cache Content
+
+## What is Prompt Caching?
+
+When you chat with Claude, each API request sends the full conversation context (system prompt + tool definitions + historical messages). Anthropic's prompt caching mechanism caches previously computed prefix content on the server side. If the prefix of a subsequent request matches, the cached result is reused directly, skipping redundant computation and significantly reducing latency and cost.
+
+In cc-viewer, this mechanism is referred to as "KV-Cache", corresponding to Anthropic's API-level prompt caching — not the key-value cache within the transformer attention layers of the LLM itself.
+
+## How Caching Works
+
+Anthropic's prompt caching concatenates the cache key in a fixed order:
+
+```
+Tools → System Prompt → Messages (up to cache breakpoint)
+```
+
+As long as this prefix exactly matches any request within the TTL window, the API returns a cache hit (`cache_read_input_tokens`) rather than recomputing (`cache_creation_input_tokens`).
+
+> **Claude Code does not strongly depend on the `cache_control` attribute. The server will strip some of these attributes accordingly, yet caching still works well. So not seeing `cache_control` does not mean the content is not cached.**
+>
+> For special clients like Claude Code, Anthropic's server does not fully rely on the `cache_control` attribute in requests to determine caching behavior. The server automatically applies caching policies to specific fields (such as system prompt and tool definitions), even when the request does not explicitly include `cache_control` markers. Therefore, when you don't see this attribute in the request body, don't be puzzled — the server has already performed the caching operation behind the scenes, it simply hasn't exposed this information to the client. This is a tacit understanding between Claude Code and the Anthropic API.
+
+## What is "Current KV-Cache Content"?
+
+The "Current KV-Cache Content" displayed in cc-viewer is extracted from the most recent MainAgent request — specifically the content before the cache boundary (cache breakpoint). It includes:
+
+- **System Prompt**: Claude Code's system instructions, including core agent directives, tool usage specifications, CLAUDE.md project instructions, environment information, etc.
+- **Tools**: The current list of available tool definitions (such as Read, Write, Bash, Agent, MCP tools, etc.)
+- **Messages**: The portion of conversation history that is cached (typically earlier messages, up to the last `cache_control` marker)
+
+## Why View Cache Content?
+
+1. **Understand Context**: See what Claude currently "remembers" to help you judge whether its behavior matches expectations
+2. **Cost Optimization**: Cache hits cost far less than recomputation. Viewing cache content helps you understand why certain requests triggered a cache rebuild
+3. **Debug Conversations**: When Claude's responses don't match expectations, checking cache content confirms whether the system prompt and historical messages are correct
+4. **Context Quality Monitoring**: During debugging, configuration changes, or prompt adjustments, KV-Cache-Text provides a centralized view to quickly confirm whether core context has degraded or been unexpectedly polluted — without manually reviewing raw messages
+
+## Multi-Level Caching Strategy
+
+The KV-Cache corresponding to Claude Code is not a single cache. The server generates separate caches for Tools and System Prompt, independent from the Messages cache. The benefit of this design is: when the messages stack becomes corrupted (e.g., context truncation, message modification) and needs rebuilding, it won't invalidate the Tools and System Prompt caches along with it, avoiding a full recomputation.
+
+This is a current server-side optimization strategy — because Tool definitions and the System Prompt remain relatively stable during normal use and rarely change. Caching them separately minimizes unnecessary rebuild overhead. So when you observe the cache, you'll notice that apart from Tools rebuilds which require a full cache refresh, disruptions to the System Prompt and Messages still have inheritable caches available.
+
+## Cache Lifecycle
+
+- **Creation**: On first request or after cache expiration, the API creates a new cache (`cache_creation_input_tokens`)
+- **Hit**: Subsequent requests with matching prefixes reuse the cache (`cache_read_input_tokens`)
+- **Expiration**: Cache has a 5-minute TTL (time-to-live) and automatically expires after timeout
+- **Rebuild**: When system prompt, tool list, model, or message content changes, the cache key no longer matches, triggering a rebuild at the corresponding level

package/concepts/en/MainAgent.md

@@ -0,0 +1,23 @@
+# 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 |

package/concepts/en/ProxySwitch.md

@@ -0,0 +1,50 @@
+# Hot-Switch Proxy
+
+## Overview
+
+Hot-Switch Proxy lets you dynamically redirect API requests to a different endpoint without restarting Claude Code. This is useful when using third-party API proxy services.
+
+> ⚠️ Do not use this feature if you are a Claude Max subscriber.
+
+## Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| **Name** | ✅ | Display name for this proxy, used to identify it |
+| **Base URL** | ✅ | Base URL of the API service (e.g. `https://api.example.com`). The original request origin will be replaced |
+| **API Key** | ✅ | API key for the proxy service, replaces the original authentication |
+| **Models** | ❌ | Comma-separated list of models supported by this proxy (e.g. `model-a, model-b`) |
+| **Active Model** | ❌ | Select the active model from the list. The `model` field in requests will be replaced |
+
+## How It Works
+
+When a proxy is active, `interceptor.js` performs the following before each API request:
+
+1. **URL Rewrite** — Replaces the request origin with the proxy's Base URL
+2. **Auth Replace** — Replaces `x-api-key` or `Authorization` header with the proxy's API Key
+3. **Model Replace** — If an active model is set, replaces the `model` field in the request body
+
+## Config File
+
+Configuration is stored at `~/.claude/cc-viewer/profile.json`. Click the folder icon in the title to open the directory:
+
+```json
+{
+  "active": "my-proxy",
+  "profiles": [
+    { "id": "max", "name": "Max" },
+    {
+      "id": "my-proxy",
+      "name": "My Proxy",
+      "baseURL": "https://api.example.com",
+      "apiKey": "sk-xxx",
+      "models": ["model-a", "model-b"],
+      "activeModel": "model-a"
+    }
+  ]
+}
+```
+
+- `active` — ID of the current profile. Set to `"max"` for direct connection (no proxy)
+- `profiles` — Profile list. `id: "max"` is built-in and cannot be deleted
+- Changes take effect within ~1.5 seconds (monitored via `fs.watchFile`), no restart needed

package/concepts/en/QRCode.md

@@ -0,0 +1,29 @@
+# Mobile QR Code Access
+
+## How It Works
+
+CC Viewer starts an HTTP server on your machine and generates a **local network address** (e.g., `http://192.168.1.100:7008`). Scan the QR code with your phone to access Claude Code from your mobile device over the same WiFi network.
+
+## Why Can't I Connect?
+
+Common reasons:
+
+1. **Not on the same network** — Your phone and computer must be connected to the same WiFi (same router / same network name)
+2. **Firewall blocking** — macOS/Windows firewall may block incoming connections; allow CC Viewer's port
+3. **Corporate/school network isolation** — Some enterprise networks isolate device-to-device communication (AP isolation)
+4. **VPN interference** — A VPN on either device may disrupt the network path
+
+## Security Notice
+
+> ⚠️ CC Viewer's LAN service is accessible to all devices on the same network by default.
+
+- Be cautious when using on **public WiFi** (cafes, airports) — others on the same network could potentially access your service
+- CC Viewer uses **token-based authentication** for LAN access (token is embedded in the URL); requests without a valid token are rejected
+- Recommended for use on trusted home or office networks
+
+## Beyond the LAN
+
+If you need remote access to Claude Code from a different network (e.g., when traveling):
+
+- **Tunneling tools** — frp, ngrok, Tailscale, etc. to expose local services to the internet
+- **CC Viewer plugins** — Configure a proxy middleware via the plugin system for cross-network access (see plugin docs)

package/concepts/en/ResponseFields.md

@@ -0,0 +1,50 @@
+# Response Body Field Reference
+
+Field reference for the Claude API `/v1/messages` response body.
+
+## Top-Level Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| **model** | string | The model name actually used, e.g. `claude-opus-4-6` |
+| **id** | string | Unique identifier for this response, e.g. `msg_01Tgsr2QeH8AVXGoP2wAXRvU` |
+| **type** | string | Always `"message"` |
+| **role** | string | Always `"assistant"` |
+| **content** | array | Array of content blocks output by the model, containing text, tool calls, thinking process, etc. |
+| **stop_reason** | string | Reason for stopping: `"end_turn"` (normal completion), `"tool_use"` (tool execution needed), `"max_tokens"` (token limit reached) |
+| **stop_sequence** | string/null | The sequence that triggered the stop, usually `null` |
+| **usage** | object | Token usage statistics (see below) |
+
+## content Block Types
+
+| Type | Description |
+|------|-------------|
+| **text** | The model's text reply, contains a `text` field |
+| **tool_use** | Tool call request, contains `name` (tool name), `input` (parameters), `id` (call ID, used to match tool_result) |
+| **thinking** | Extended thinking content (only appears when thinking mode is enabled), contains a `thinking` field |
+
+## usage Field Details
+
+| Field | Description |
+|-------|-------------|
+| **input_tokens** | Number of input tokens that did not hit the cache (billed at full price) |
+| **cache_creation_input_tokens** | Number of tokens for newly created cache entries (cache write, billed higher than normal input) |
+| **cache_read_input_tokens** | Number of tokens that hit the cache (cache read, billed much lower than normal input) |
+| **output_tokens** | Number of tokens output by the model |
+| **service_tier** | Service tier, e.g. `"standard"` |
+| **inference_geo** | Inference geography, e.g. `"not_available"` means no geography info is provided |
+
+## cache_creation Sub-Fields
+
+| Field | Description |
+|-------|-------------|
+| **ephemeral_5m_input_tokens** | Number of tokens for short-term cache creation with a 5-minute TTL |
+| **ephemeral_1h_input_tokens** | Number of tokens for long-term cache creation with a 1-hour TTL |
+
+> **About cache billing**: The unit price of `cache_read_input_tokens` is much lower than `input_tokens`, while the unit price of `cache_creation_input_tokens` is slightly higher than normal input. Therefore, maintaining a high cache hit rate in ongoing conversations can significantly reduce costs. You can visually monitor this ratio through the "Hit Rate" metric in cc-viewer.
+
+## stop_reason Meanings
+
+- **end_turn**: The model completed its reply normally
+- **tool_use**: The model needs to call a tool; the content will include a `tool_use` block. The next request must append a `tool_result` in the messages to continue the conversation
+- **max_tokens**: The reply was truncated due to reaching the `max_tokens` limit and may be incomplete

package/concepts/en/SubAgent-Search.md

@@ -0,0 +1,20 @@
+# SubAgent: Search
+
+## Definition
+
+Search is a sub-agent type spawned by Claude Code's main agent to perform codebase searches. It executes targeted file and content searches using tools like Glob, Grep, and Read, then returns the results to the parent agent.
+
+## Behavior
+
+- Spawned automatically when the main agent needs to search or explore the codebase
+- Runs in an isolated context with read-only access
+- Uses Glob for file pattern matching, Grep for content search, and Read for file inspection
+- Returns search results to the parent agent for further processing
+
+## When It Appears
+
+Search sub-agents typically appear when:
+
+1. The main agent needs to find specific files, functions, or code patterns
+2. A broad codebase exploration is requested by the user
+3. The agent is investigating dependencies, references, or usage patterns

package/concepts/en/Teammate.md

@@ -0,0 +1,26 @@
+# Teammate
+
+## Definition
+
+A Teammate is a collaborative agent in Claude Code Agent Team mode. When the main agent creates a team via `TeamCreate` and spawns teammates using the `Agent` tool, each teammate runs as an independent agent process with its own context window and toolset, communicating with team members through `SendMessage`.
+
+## Differences from SubAgent
+
+| Feature | Teammate | SubAgent |
+|---------|----------|----------|
+| Lifecycle | Persistent, can receive multiple messages | One-off task, destroyed upon completion |
+| Communication | SendMessage bidirectional messaging | Parent→child unidirectional call, returns result |
+| Context | Independent full context, retained across turns | Isolated task context |
+| Collaboration | Team collaboration, can communicate with each other | Hierarchical structure, only interacts with parent agent |
+| Task Type | Complex multi-step tasks | Single tasks such as search and exploration |
+
+## Behavior
+
+- Created by the main agent (team lead) via the `Agent` tool and assigned a `team_name`
+- Shares task lists through `TaskList` / `TaskGet` / `TaskUpdate`
+- Enters idle state after each turn, waiting to be woken by a new message
+- Can be gracefully terminated via `shutdown_request`
+
+## Stats Panel Description
+
+The Teammate stats panel displays the number of API calls for each teammate. The `Name` column shows the teammate's name (e.g., `reviewer-security`, `reviewer-pipeline`), and the `Count` column shows the total number of API requests generated by that teammate.