cx-viewer 1.0.0

package/concepts/en/Tool-TaskUpdate.md

@@ -0,0 +1,123 @@
+# TaskUpdate
+
+## Definition
+
+Updates the status, content, or dependencies of a task in the task list.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `taskId` | string | Yes | The task ID to update |
+| `status` | enum | No | New status: `pending` / `in_progress` / `completed` / `deleted` |
+| `subject` | string | No | New title |
+| `description` | string | No | New description |
+| `activeForm` | string | No | Present continuous text displayed when in progress |
+| `owner` | string | No | New task owner (agent name) |
+| `metadata` | object | No | Metadata to merge (set to null to delete a key) |
+| `addBlocks` | string[] | No | List of task IDs blocked by this task |
+| `addBlockedBy` | string[] | No | List of prerequisite task IDs blocking this task |
+
+## Status Workflow
+
+```
+pending → in_progress → completed
+```
+
+`deleted` can be entered from any status and permanently removes the task.
+
+## Use Cases
+
+**Good for:**
+- Marking a task as `in_progress` when starting work
+- Marking a task as `completed` when work is done
+- Setting dependencies between tasks
+- Updating task content when requirements change
+
+**Important rules:**
+- Only mark a task as `completed` when it is fully finished
+- Keep the task as `in_progress` when encountering errors or blockers
+- Do not mark as `completed` if tests are failing, implementation is incomplete, or unresolved errors exist
+
+## Notes
+
+- Before updating, retrieve the task's latest status via TaskGet to avoid stale data
+- After completing a task, call TaskList to find the next available task
+
+## Original Text
+
+<textarea readonly>Use this tool to update a task in the task list.
+
+## When to Use This Tool
+
+**Mark tasks as resolved:**
+- When you have completed the work described in a task
+- When a task is no longer needed or has been superseded
+- IMPORTANT: Always mark your assigned tasks as resolved when you finish them
+- After resolving, call TaskList to find your next task
+
+- ONLY mark a task as completed when you have FULLY accomplished it
+- If you encounter errors, blockers, or cannot finish, keep the task as in_progress
+- When blocked, create a new task describing what needs to be resolved
+- Never mark a task as completed if:
+  - Tests are failing
+  - Implementation is partial
+  - You encountered unresolved errors
+  - You couldn't find necessary files or dependencies
+
+**Delete tasks:**
+- When a task is no longer relevant or was created in error
+- Setting status to `deleted` permanently removes the task
+
+**Update task details:**
+- When requirements change or become clearer
+- When establishing dependencies between tasks
+
+## Fields You Can Update
+
+- **status**: The task status (see Status Workflow below)
+- **subject**: Change the task title (imperative form, e.g., "Run tests")
+- **description**: Change the task description
+- **activeForm**: Present continuous form shown in spinner when in_progress (e.g., "Running tests")
+- **owner**: Change the task owner (agent name)
+- **metadata**: Merge metadata keys into the task (set a key to null to delete it)
+- **addBlocks**: Mark tasks that cannot start until this one completes
+- **addBlockedBy**: Mark tasks that must complete before this one can start
+
+## Status Workflow
+
+Status progresses: `pending` → `in_progress` → `completed`
+
+Use `deleted` to permanently remove a task.
+
+## Staleness
+
+Make sure to read a task's latest state using `TaskGet` before updating it.
+
+## Examples
+
+Mark task as in progress when starting work:
+```json
+{"taskId": "1", "status": "in_progress"}
+```
+
+Mark task as completed after finishing work:
+```json
+{"taskId": "1", "status": "completed"}
+```
+
+Delete a task:
+```json
+{"taskId": "1", "status": "deleted"}
+```
+
+Claim a task by setting owner:
+```json
+{"taskId": "1", "owner": "my-name"}
+```
+
+Set up task dependencies:
+```json
+{"taskId": "2", "addBlockedBy": ["1"]}
+```
+</textarea>

package/concepts/en/Tool-TeamCreate.md

@@ -0,0 +1,38 @@
+# TeamCreate
+
+## Definition
+
+Creates a new team to coordinate multiple agents working on a project. Teams enable parallel task execution through a shared task list and inter-agent messaging.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `team_name` | string | Yes | Name for the new team |
+| `description` | string | No | Team description/purpose |
+| `agent_type` | string | No | Type/role of the team lead |
+
+## What It Creates
+
+- **Team config file**: `~/.claude/teams/{team-name}/config.json` — stores member list and metadata
+- **Task list directory**: `~/.claude/tasks/{team-name}/` — shared task list for all teammates
+
+Teams have a 1:1 correspondence with task lists.
+
+## Team Workflow
+
+1. **TeamCreate** — create the team and its task list
+2. **TaskCreate** — define tasks for the team
+3. **Agent** (with `team_name` + `name`) — spawn teammates that join the team
+4. **TaskUpdate** — assign tasks to teammates via `owner`
+5. Teammates work on tasks, communicate via **SendMessage**
+6. **Shutdown** teammates when done, then **TeamDelete** to clean up
+
+## Related Tools
+
+| Tool | Purpose |
+|------|---------|
+| `TeamDelete` | Remove team and task directories |
+| `SendMessage` | Inter-agent communication within the team |
+| `TaskCreate` / `TaskUpdate` / `TaskList` / `TaskGet` | Manage the shared task list |
+| `Agent` | Spawn teammates that join the team |

package/concepts/en/Tool-TeamDelete.md

@@ -0,0 +1,30 @@
+# TeamDelete
+
+## Definition
+
+Removes a team and its associated task directories when multi-agent collaboration work is complete. This is the cleanup counterpart to TeamCreate.
+
+## Behavior
+
+- Removes the team directory: `~/.claude/teams/{team-name}/`
+- Removes the task directory: `~/.claude/tasks/{team-name}/`
+- Clears team context from the current session
+
+**Important**: TeamDelete will fail if the team still has active members. Teammates must be gracefully shut down first via SendMessage shutdown requests.
+
+## Typical Usage
+
+TeamDelete is called at the end of a team workflow:
+
+1. All tasks are completed
+2. Teammates are shut down via `SendMessage` with `shutdown_request`
+3. **TeamDelete** removes team and task directories
+
+## Related Tools
+
+| Tool | Purpose |
+|------|---------|
+| `TeamCreate` | Create a new team and its task list |
+| `SendMessage` | Communicate with teammates / send shutdown requests |
+| `TaskCreate` / `TaskUpdate` / `TaskList` / `TaskGet` | Manage the shared task list |
+| `Agent` | Spawn teammates that join the team |

package/concepts/en/Tool-WebFetch.md

@@ -0,0 +1,55 @@
+# WebFetch
+
+## Definition
+
+Fetches web page content from a specified URL, converts HTML to markdown, and processes the content using an AI model based on the prompt.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `url` | string (URI) | Yes | The full URL to fetch |
+| `prompt` | string | Yes | Describes what information to extract from the page |
+
+## Use Cases
+
+**Good for:**
+- Fetching content from public web pages
+- Consulting online documentation
+- Extracting specific information from web pages
+
+**Not good for:**
+- URLs requiring authentication (Google Docs, Confluence, Jira, GitHub, etc.) — look for a dedicated MCP tool first
+- GitHub URLs — prefer using the `gh` CLI
+
+## Notes
+
+- The URL must be a complete, valid URL
+- HTTP is automatically upgraded to HTTPS
+- Results may be summarized if the content is too large
+- Includes a 15-minute self-cleaning cache
+- When a URL redirects to a different host, the tool returns the redirect URL, and you need to re-request with the new URL
+- If an MCP-provided web fetch tool is available, prefer using that one
+
+## Original Text
+
+<textarea readonly>IMPORTANT: WebFetch WILL FAIL for authenticated or private URLs. Before using this tool, check if the URL points to an authenticated service (e.g. Google Docs, Confluence, Jira, GitHub). If so, you MUST use ToolSearch first to find a specialized tool that provides authenticated access.
+
+- Fetches content from a specified URL and processes it using an AI model
+- Takes a URL and a prompt as input
+- Fetches the URL content, converts HTML to markdown
+- Processes the content with the prompt using a small, fast model
+- Returns the model's response about the content
+- Use this tool when you need to retrieve and analyze web content
+
+Usage notes:
+  - IMPORTANT: If an MCP-provided web fetch tool is available, prefer using that tool instead of this one, as it may have fewer restrictions.
+  - The URL must be a fully-formed valid URL
+  - HTTP URLs will be automatically upgraded to HTTPS
+  - The prompt should describe what information you want to extract from the page
+  - This tool is read-only and does not modify any files
+  - Results may be summarized if the content is very large
+  - Includes a self-cleaning 15-minute cache for faster responses when repeatedly accessing the same URL
+  - When a URL redirects to a different host, the tool will inform you and provide the redirect URL in a special format. You should then make a new WebFetch request with the redirect URL to fetch the content.
+  - For GitHub URLs, prefer using the gh CLI via Bash instead (e.g., gh pr view, gh issue view, gh api).
+</textarea>

package/concepts/en/Tool-WebSearch.md

@@ -0,0 +1,58 @@
+# WebSearch
+
+## Definition
+
+Performs search engine queries and returns search results for obtaining up-to-date information.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `query` | string | Yes | Search query (minimum 2 characters) |
+| `allowed_domains` | string[] | No | Only include results from these domains |
+| `blocked_domains` | string[] | No | Exclude results from these domains |
+
+## Use Cases
+
+**Good for:**
+- Getting the latest information beyond the model's knowledge cutoff date
+- Finding current events and recent data
+- Searching for the latest technical documentation
+
+## Notes
+
+- Search results are returned in markdown hyperlink format
+- After using this tool, a "Sources:" section must be appended at the end of the response listing the relevant URLs
+- Supports domain filtering (include/exclude)
+- Use the current year in search queries
+- Only available in the US
+
+## Original Text
+
+<textarea readonly>
+- Allows Claude to search the web and use the results to inform responses
+- Provides up-to-date information for current events and recent data
+- Returns search result information formatted as search result blocks, including links as markdown hyperlinks
+- Use this tool for accessing information beyond Claude's knowledge cutoff
+- Searches are performed automatically within a single API call
+
+CRITICAL REQUIREMENT - You MUST follow this:
+  - After answering the user's question, you MUST include a "Sources:" section at the end of your response
+  - In the Sources section, list all relevant URLs from the search results as markdown hyperlinks: [Title](URL)
+  - This is MANDATORY - never skip including sources in your response
+  - Example format:
+
+    [Your answer here]
+
+    Sources:
+    - [Source Title 1](https://example.com/1)
+    - [Source Title 2](https://example.com/2)
+
+Usage notes:
+  - Domain filtering is supported to include or block specific websites
+  - Web search is only available in the US
+
+IMPORTANT - Use the correct year in search queries:
+  - The current month is March 2026. You MUST use this year when searching for recent information, documentation, or current events.
+  - Example: If the user asks for "latest React docs", search for "React documentation" with the current year, NOT last year
+</textarea>

package/concepts/en/Tool-Write.md

@@ -0,0 +1,39 @@
+# Write
+
+## Definition
+
+Writes content to the local filesystem. Overwrites the file if it already exists.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `file_path` | string | Yes | Absolute path of the file (must be an absolute path) |
+| `content` | string | Yes | The content to write |
+
+## Use Cases
+
+**Good for:**
+- Creating new files
+- When a complete rewrite of file content is needed
+
+**Not good for:**
+- Modifying partial content in a file — use Edit instead
+- Should not proactively create documentation files (*.md) or READMEs unless the user explicitly requests it
+
+## Notes
+
+- If the target file already exists, it must first be read via Read, otherwise it will fail
+- Overwrites the entire content of existing files
+- Prefer using Edit for existing files; Write is only for creating new files or complete rewrites
+
+## Original Text
+
+<textarea readonly>Writes a file to the local filesystem.
+
+Usage:
+- This tool will overwrite the existing file if there is one at the provided path.
+- If this is an existing file, you MUST use the Read tool first to read the file's contents. This tool will fail if you did not read the file first.
+- Prefer the Edit tool for modifying existing files — it only sends the diff. Only use this tool to create new files or for complete rewrites.
+- NEVER create documentation files (*.md) or README files unless explicitly requested by the User.
+- Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.</textarea>

package/concepts/en/Tool-executeCode.md

@@ -0,0 +1,41 @@
+# executeCode (mcp__ide__executeCode)
+
+## Definition
+
+Executes Python code in the Jupyter kernel of the current notebook file.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `code` | string | Yes | The Python code to execute |
+
+## Use Cases
+
+**Good for:**
+- Executing code in a Jupyter notebook environment
+- Testing code snippets
+- Data analysis and computation
+
+**Not good for:**
+- Code execution outside of Jupyter environments — use Bash instead
+- Modifying files — use Edit or Write instead
+
+## Notes
+
+- This is an MCP (Model Context Protocol) tool provided by IDE integration
+- Code executes in the current Jupyter kernel, and state persists between calls
+- Unless the user explicitly requests it, avoid declaring variables or modifying kernel state
+- State is lost after a kernel restart
+
+## Original Text
+
+<textarea readonly>Execute python code in the Jupyter kernel for the current notebook file.
+    
+    All code will be executed in the current Jupyter kernel.
+    
+    Avoid declaring variables or modifying the state of the kernel unless the user
+    explicitly asks for it.
+    
+    Any code executed will persist across calls to this tool, unless the kernel
+    has been restarted.</textarea>

package/concepts/en/Tool-getDiagnostics.md

@@ -0,0 +1,32 @@
+# getDiagnostics (mcp__ide__getDiagnostics)
+
+## Definition
+
+Gets language diagnostics from VS Code, including syntax errors, type errors, lint warnings, and more.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `uri` | string | No | File URI. If not provided, gets diagnostics for all files |
+
+## Use Cases
+
+**Good for:**
+- Checking code for syntax, type, lint, and other semantic issues
+- Verifying whether new errors were introduced after editing code
+- Replacing Bash commands for checking code quality
+
+**Not good for:**
+- Running tests — use Bash instead
+- Checking runtime errors — use Bash to execute the code instead
+
+## Notes
+
+- This is an MCP (Model Context Protocol) tool provided by IDE integration
+- Only available in VS Code / IDE environments
+- Prefer this tool over Bash commands for checking code issues
+
+## Original Text
+
+<textarea readonly>Get language diagnostics from VS Code</textarea>

package/concepts/en/Tools.md

@@ -0,0 +1,67 @@
+# Claude Code Tools Overview
+
+Claude Code provides a set of built-in tools to the model through the Anthropic API's tool_use mechanism. Each MainAgent request includes the complete JSON Schema definitions of these tools in the `tools` array, and the model invokes them via `tool_use` content blocks in its responses.
+
+Below is a categorized index of all tools.
+
+## Agent System
+
+| Tool | Purpose |
+|------|---------|
+| [Task](Tool-Task.md) | Launch a SubAgent to handle complex multi-step tasks |
+| [TaskOutput](Tool-TaskOutput.md) | Get the output of a background task |
+| [TaskStop](Tool-TaskStop.md) | Stop a running background task |
+| [TaskCreate](Tool-TaskCreate.md) | Create a structured task list entry |
+| [TaskGet](Tool-TaskGet.md) | Get task details |
+| [TaskUpdate](Tool-TaskUpdate.md) | Update task status, dependencies, etc. |
+| [TaskList](Tool-TaskList.md) | List all tasks |
+
+## File Operations
+
+| Tool | Purpose |
+|------|---------|
+| [Read](Tool-Read.md) | Read file contents (supports text, images, PDF, Jupyter notebook) |
+| [Edit](Tool-Edit.md) | Edit files via exact string replacement |
+| [Write](Tool-Write.md) | Write to or overwrite files |
+| [NotebookEdit](Tool-NotebookEdit.md) | Edit Jupyter notebook cells |
+
+## Search
+
+| Tool | Purpose |
+|------|---------|
+| [Glob](Tool-Glob.md) | Search files by filename pattern matching |
+| [Grep](Tool-Grep.md) | Search file contents based on ripgrep |
+
+## Terminal
+
+| Tool | Purpose |
+|------|---------|
+| [Bash](Tool-Bash.md) | Execute shell commands |
+
+## Web
+
+| Tool | Purpose |
+|------|---------|
+| [WebFetch](Tool-WebFetch.md) | Fetch web page content and process it with AI |
+| [WebSearch](Tool-WebSearch.md) | Search engine queries |
+
+## Planning & Interaction
+
+| Tool | Purpose |
+|------|---------|
+| [EnterPlanMode](Tool-EnterPlanMode.md) | Enter plan mode to design an implementation plan |
+| [ExitPlanMode](Tool-ExitPlanMode.md) | Exit plan mode and submit the plan for user approval |
+| [AskUserQuestion](Tool-AskUserQuestion.md) | Ask the user a question for clarification or decisions |
+
+## Extensions
+
+| Tool | Purpose |
+|------|---------|
+| [Skill](Tool-Skill.md) | Execute a skill (slash command) |
+
+## IDE Integration
+
+| Tool | Purpose |
+|------|---------|
+| [getDiagnostics](Tool-getDiagnostics.md) | Get VS Code language diagnostics |
+| [executeCode](Tool-executeCode.md) | Execute code in a Jupyter kernel |

package/concepts/en/ToolsFirst.md

@@ -0,0 +1,77 @@
+# Why Are Tools Listed First?
+
+In cc-viewer's Context panel, **Tools appear before System Prompt and Messages**. This ordering precisely mirrors the **Anthropic API's KV-Cache prefix sequence**.
+
+## KV-Cache Prefix Sequence
+
+When Anthropic's API constructs the KV-Cache, it concatenates context into a prefix in this **fixed order**:
+
+```
+┌─────────────────────────────────────────────────┐
+│ 1. Tools (JSON Schema definitions)               │  ← Start of cache prefix
+│ 2. System Prompt                                 │
+│ 3. Messages (conversation history + current turn)│  ← End of cache prefix
+└─────────────────────────────────────────────────┘
+```
+
+This means **Tools sit before System Prompt at the very beginning of the cache prefix**.
+
+## Why Do Tools Have Higher Cache Weight Than System?
+
+In KV-Cache prefix matching, **earlier content is more critical** — any change invalidates everything after it:
+
+1. **Prefix matching starts from the beginning**: The KV-Cache compares the current request against the cached prefix token-by-token from the start. The moment a mismatch is found, all subsequent content is invalidated.
+
+2. **Tools change = entire cache invalidated**: Since Tools come first, any change to tool definitions (even adding or removing a single MCP tool) **breaks the prefix from the very start**, invalidating all cached System Prompt and Messages.
+
+3. **System change = Messages cache invalidated**: System Prompt sits in the middle, so its changes only invalidate the Messages portion that follows.
+
+4. **Messages change = only the tail affected**: Messages are at the end, so appending new messages only invalidates a small trailing segment — Tools and System cache remain intact.
+
+## Practical Impact
+
+| Change Type | Cache Impact | Typical Scenario |
+|-------------|-------------|-----------------|
+| Tool added/removed | **Full invalidation** | MCP server connect/disconnect, IDE plugin toggle |
+| System Prompt change | Messages cache lost | CLAUDE.md edit, system reminder injection |
+| New message appended | Tail increment only | Normal conversation flow (most common, cheapest) |
+
+This is why `tools_change` in [CacheRebuild](CacheRebuild.md) tends to be the most expensive rebuild reason — it breaks the prefix chain at the very front.
+
+## Why Are Tool Definitions Placed Before the "Brain"?
+
+From a caching perspective, Tools being first is a technical fact. But from a cognitive design perspective, this ordering is equally logical — **Tools are the hands and feet, System Prompt is the brain**.
+
+Before taking action, a person needs to perceive what limbs and tools are available. An infant doesn't first understand the rules of the world (System), then learn to reach and grab — they first sense that they have hands and feet, then gradually understand rules through interaction with the environment. Similarly, an LLM needs to know what tools it can call (read files, write code, search, execute commands) before receiving task instructions (System Prompt), so it can accurately assess "what can I do" and "how should I do it" when processing the instructions.
+
+If reversed — first telling the model "your task is to refactor this module", then telling it "you have Read, Edit, Bash tools" — the model would lack critical capability boundary information when understanding the task, potentially producing unrealistic plans or overlooking available approaches.
+
+**Know what cards you hold before deciding how to play.** This is the cognitive logic behind Tools preceding System.
+
+## Why Are MCP Tools Also in This Position?
+
+MCP (Model Context Protocol) tools, like built-in tools, are placed at the very front of the Tools area. Understanding MCP's position in the context helps evaluate its real benefits and costs.
+
+### MCP Advantages
+
+- **Capability extension**: MCP lets models access external services (database queries, API calls, IDE operations, browser control, etc.), breaking beyond built-in tool boundaries
+- **Open ecosystem**: Anyone can implement an MCP server; the model gains new capabilities without retraining
+- **On-demand loading**: MCP servers can be selectively connected/disconnected based on task scenario, flexibly composing tool sets
+
+### MCP Costs
+
+- **Cache killer**: Each MCP tool's JSON Schema definition is concatenated into the very front of the KV-Cache prefix. Adding or removing one MCP tool = **entire cache invalidated from the start**. Frequently connecting/disconnecting MCP servers will dramatically reduce cache hit rates
+- **Prefix bloat**: MCP tool Schemas are typically larger than built-in tools (containing detailed parameter descriptions, enums, etc.). Many MCP tools significantly increase the Tools area's token count, squeezing the context space available for Messages
+- **Latency overhead**: MCP tool calls require cross-process communication (JSON-RPC over stdio/SSE), an order of magnitude slower than built-in function calls
+- **Stability risk**: MCP servers are external processes that may crash, timeout, or return unexpected formats, requiring additional error handling
+
+### Practical Recommendations
+
+| Scenario | Recommendation |
+|----------|---------------|
+| Long conversations, high-frequency interaction | Minimize MCP tool count to protect cache prefix stability |
+| Short tasks, one-off operations | Use MCP tools freely; cache impact is limited |
+| Frequently adding/removing MCP servers | Each change triggers full cache rebuild; consider fixing the tool set |
+| Oversized Tool Schemas | Trim descriptions and enums to reduce prefix token footprint |
+
+In cc-viewer's Context panel, MCP tools are displayed alongside built-in tools in the Tools area, giving you a clear view of each tool's Schema size and contribution to the cache prefix.

package/concepts/en/TranslateContextPollution.md

@@ -0,0 +1,46 @@
+# Translate API Context Pollution
+
+## Background
+
+CC-Viewer includes a built-in translation feature (`POST /api/translate`) powered by the Anthropic Messages API. In the early implementation, translation requests reused cached authentication credentials from the Claude Code session — including both `x-api-key` and `authorization` headers. This caused a subtle but serious issue: translation results frequently returned irrelevant content.
+
+## Root Cause
+
+### Fundamental Difference Between Two Authentication Methods
+
+The Anthropic API supports two authentication methods:
+
+| Method | Header | Typical Source | Characteristics |
+|--------|--------|----------------|-----------------|
+| API Key | `x-api-key: sk-ant-...` | Environment variable / Console | Stateless, each request is independent |
+| OAuth Token | `authorization: Bearer sessionToken` | Claude Code subscription login | Session-bound, server maintains context association |
+
+The key difference: **API Keys are stateless** — each request is completely independent; while **OAuth session tokens are stateful** — the Anthropic server associates requests using the same token to the same session context.
+
+### Pollution Chain
+
+When Claude Code uses subscription OAuth login, the authentication flow looks like:
+
+```
+Claude Code main conversation ──(authorization: Bearer sessionToken)──→ Anthropic API
+                                                                          ↑
+CC-Viewer translate request ──(authorization: Bearer sessionToken)──→ Anthropic API
+```
+
+Since translation requests reused the same session token, the Anthropic server may associate translation requests with Claude Code's main conversation context. This causes:
+
+1. **Translation results influenced by main conversation context**: The translation request's system prompt is "you are a translator", but the server context still contains Claude Code's conversation history, potentially interfering with the model
+2. **Main conversation disturbed by translation requests**: Translation request content (UI text fragments) may be injected into the main conversation context, causing Claude Code's responses to deviate
+3. **Unpredictable behavior**: Since context pollution is server-side behavior, the client cannot detect or control it
+
+## Lessons Learned
+
+- **OAuth session tokens are not "just another API Key"** — they carry server-side state, reusing them means sharing context
+- **Internal service calls should use independent, stateless authentication** to avoid association with user sessions
+
+## References
+
+- [Anthropic API Authentication Docs](https://docs.anthropic.com/en/api/getting-started) — Official documentation on `x-api-key` and `authorization` headers
+- [Claude Code Authentication](https://support.claude.com/en/articles/12304248-managing-api-key-environment-variables-in-claude-code) — API Key environment variable management
+- [Anthropic Bans Subscription OAuth in Third-Party Apps](https://winbuzzer.com/2026/02/19/anthropic-bans-claude-subscription-oauth-in-third-party-apps-xcxwbn/) — Anthropic's restrictions on OAuth token usage scope
+- [Claude Code Authentication: API Keys, Subscriptions, and SSO](https://developertoolkit.ai/en/claude-code/quick-start/authentication/) — Authentication method comparison

package/concepts/en/UltraPlan.md

@@ -0,0 +1,55 @@
+# UltraPlan — The Ultimate Wishing Machine
+
+## What is UltraPlan
+
+UltraPlan is cc-viewer's **localized implementation** of Claude Code's native `/ultraplan` command. It allows you to use the full capabilities of `/ultraplan` in your local environment **without needing to launch Claude's official remote service**, guiding Claude Code to accomplish complex planning and implementation tasks using **multi-agent collaboration**.
+
+Compared to regular Plan mode or Agent Team, UltraPlan can:
+- Automatically assess task complexity and select the optimal planning strategy
+- Deploy multiple parallel agents to explore the codebase from different dimensions
+- Incorporate external research (webSearch) for industry best practices
+- Automatically assemble a Code Review Team after plan execution for code review
+- Form a complete **Plan → Execute → Review → Fix** closed loop
+
+---
+
+## Important Notes
+
+### 1. UltraPlan Is Not Omnipotent
+UltraPlan is a more powerful wishing machine, but that doesn't mean every wish can be fulfilled. It's more powerful than Plan and Agent Team, but it can't directly "make you money." Consider reasonable task granularity — break large goals into executable medium-sized tasks rather than trying to accomplish everything in one shot.
+
+### 2. Currently Most Effective for Programming Projects
+UltraPlan's templates and workflows are deeply optimized for programming projects. Other scenarios (documentation, data analysis, etc.) can be attempted, but you may want to wait for future version adaptations.
+
+### 3. Execution Time and Context Window Requirements
+- A successful UltraPlan run typically takes **30 minutes or more**
+- Requires MainAgent to have a large context window (1M context Opus model recommended)
+- If you only have a 200K model, **make sure to `/clear` context before running**
+- Claude Code's `/compact` performs poorly when the context window is insufficient — avoid running out of space
+- Maintaining sufficient context space is a critical prerequisite for successful UltraPlan execution
+
+If you have any questions or suggestions about the localized UltraPlan, feel free to open [Issues on GitHub](https://github.com/anthropics/claude-code/issues) to discuss and collaborate.
+
+---
+
+## How It Works
+
+UltraPlan offers two operating modes:
+
+### Auto Mode
+Automatically analyzes task complexity (score 4-12) and routes to different strategies:
+
+| Route | Score | Strategy |
+|-------|-------|----------|
+| Route A | 4-6 | Lightweight planning with direct code exploration |
+| Route B | 7-9 | Planning with structural diagrams (Mermaid / ASCII) |
+| Route C | 10-12 | Multi-agent exploration + review closed loop |
+
+### Forced Mode
+Directly activates the full Route C multi-agent workflow:
+1. Deploy up to 5 parallel agents to explore the codebase simultaneously (architecture, file identification, risk assessment, etc.)
+2. Optionally deploy a research agent to investigate industry solutions via webSearch
+3. Synthesize all agent findings into a detailed implementation plan
+4. Deploy a review agent to scrutinize the plan from multiple perspectives
+5. Execute the plan once approved
+6. Automatically assemble a Code Review Team to validate code quality after implementation