cx-viewer 1.0.0

package/concepts/uk/GlobalSettings.md

@@ -0,0 +1,232 @@
+# CC-Viewer 全局配置参考
+
+## 一、全局设置面板（UI）
+
+通过左上角菜单 → "全局设置" 打开。
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| 过滤无关请求 | 开关 | 开 | 隐藏心跳、count_tokens、子代理等非主代理请求 |
+| 默认展开 Body Diff JSON | 开关 | 关 | 请求详情面板中的 Body Diff 区域默认展开 |
+| 日志目录设置 | 文本输入 | `~/.claude/cc-viewer` | 项目日志的读写根目录，支持 `~/` 展开。修改后回车或失焦保存，立即生效 |
+
+## 二、显示设置面板（UI）
+
+通过左上角菜单 → "显示设置" 打开。
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| 折叠工具结果 | 开关 | 开 | 聊天视图中折叠工具调用结果块 |
+| 展开思考过程 | 开关 | 开 | 默认展开 Claude 的思考/推理过程块 |
+| 完整展示所有内容 | 开关 | 关 | 显示完整的工具调用内容，不截断 |
+| 自动恢复会话 | 开关 + 选项 | 关 | 遇到会话恢复提示时自动选择：`继续` 或 `新建` |
+
+## 三、偏好设置文件
+
+所有 UI 设置持久化到 `<日志目录>/preferences.json`，通过 `/api/preferences` 接口读写。
+
+```json
+{
+  "lang": "zh",
+  "filterIrrelevant": true,
+  "expandDiff": false,
+  "collapseToolResults": true,
+  "expandThinking": true,
+  "showFullToolContent": false,
+  "logDir": "~/.claude/cc-viewer",
+  "resumeAutoChoice": null,
+  "disabledPlugins": [],
+  "presetShortcuts": []
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `lang` | string | 界面语言（zh/en/zh-TW/ko/ja/de/es/fr/it/da/pl/ru/ar/no/pt-BR/th/tr/uk） |
+| `filterIrrelevant` | boolean | 过滤无关请求 |
+| `expandDiff` | boolean | 默认展开 Body Diff JSON |
+| `collapseToolResults` | boolean | 折叠工具结果 |
+| `expandThinking` | boolean | 展开思考过程 |
+| `showFullToolContent` | boolean | 完整展示内容 |
+| `logDir` | string | 日志目录路径 |
+| `resumeAutoChoice` | null / "continue" / "new" | 自动恢复会话选择 |
+| `disabledPlugins` | string[] | 已禁用的插件文件名列表 |
+| `presetShortcuts` | array | Agent Team 快捷指令预设 |
+
+## 四、环境变量
+
+### CC-Viewer 专有
+
+| 变量名 | 默认值 | 说明 |
+|--------|--------|------|
+| `CCV_LOG_DIR` | `~/.claude/cc-viewer` | 日志存储根目录。特殊值：`tmp`/`temp` 使用系统临时目录 |
+| `CCV_CLI_MODE` | 未设置 | `=1` 启用 CLI 模式（PTY 终端） |
+| `CCV_SDK_MODE` | 未设置 | `=1` 启用 Agent SDK 模式（无终端） |
+| `CCV_WORKSPACE_MODE` | 未设置 | `=1` 启用工作空间选择模式 |
+| `CCV_PROJECT_DIR` | `process.cwd()` | 项目工作目录，用于文件操作和 Git 命令 |
+| `CCV_PROXY_PORT` | 未设置 | 本地 MITM 代理端口 |
+| `CCV_BYPASS_PERMISSIONS` | 未设置 | `=1` 跳过工具权限审批（配合 `--dangerously-skip-permissions`） |
+| `CCV_DISABLE_DELTA` | 未设置 | `=1` 禁用增量日志存储，每次写入完整消息 |
+| `CCV_DEBUG` | 未设置 | `=1` 启用 HTTP 代理调试日志 |
+| `CCV_DEBUG_PLUGINS` | 未设置 | `=1` 启用插件加载调试日志 |
+
+### 内部 IPC
+
+| 变量名 | 说明 |
+|--------|------|
+| `CCVIEWER_PORT` | 服务端口，供 ask-bridge/perm-bridge 通信 |
+| `CCV_EDITOR_PORT` | 服务端口，供 ccv-editor 文件编辑桥接 |
+
+### 外部变量（读取）
+
+| 变量名 | 说明 |
+|--------|------|
+| `ANTHROPIC_BASE_URL` | 自定义 Anthropic API 地址 |
+| `SHELL` | 用户 Shell（PTY 启动和 Shell 配置检测） |
+| `http_proxy` / `HTTPS_PROXY` 等 | HTTP 代理配置（通过 undici EnvHttpProxyAgent） |
+
+## 五、CLI 命令参数
+
+```
+ccv [选项] [claude 参数...]
+```
+
+### CC-Viewer 专有选项
+
+| 参数 | 说明 |
+|------|------|
+| `-logger` | 安装/修复 Claude Code hooks |
+| `--uninstall` / `-uninstall` | 卸载所有 CC-Viewer 集成 |
+| `--help` / `-h` / `help` | 显示帮助信息 |
+| `--version` / `-v` | 显示版本号 |
+| `-SDK` / `--sdk` | 使用 Agent SDK 模式 |
+| `--d` | `--dangerously-skip-permissions` 简写 |
+| `--ad` | `--allow-dangerously-skip-permissions` 简写 |
+| `run` | 通过代理运行命令（`ccv run -- claude ...`） |
+
+### Claude 透传参数（常用）
+
+| 参数 | 说明 |
+|------|------|
+| `-c` / `--continue` | 继续上一次会话 |
+| `-r` / `--resume` | 恢复指定会话 |
+| `-p` / `--print` | 非交互式输出 |
+| `--model` | 指定模型 |
+| `--permission-mode` | 权限模式 |
+| `--system-prompt` | 自定义系统提示词 |
+| `--max-budget-usd` | 最大预算 |
+
+## 六、Hook 配置
+
+CC-Viewer 自动注册到 `~/.claude/settings.json` 的 `hooks.PreToolUse` 中：
+
+### 1. AskUserQuestion 桥接
+- **匹配器**: `"AskUserQuestion"`
+- **命令**: `node <安装目录>/lib/ask-bridge.js`
+- **作用**: 将 Claude 的问题转发到 Web UI，等待用户回答
+
+### 2. 权限审批桥接
+- **匹配器**: `""` (空 = 匹配所有工具)
+- **命令**: `node <安装目录>/lib/perm-bridge.js`
+- **作用**: 仅 `Bash`/`Edit`/`Write`/`NotebookEdit` 需要 Web UI 审批，其余自动放行
+
+## 七、Shell 集成
+
+CC-Viewer 在 `~/.zshrc`（或 `.bashrc`）中注入 `claude()` 函数：
+
+```bash
+# >>> CC-Viewer Auto-Inject >>>
+claude() { ... }
+# <<< CC-Viewer Auto-Inject <<<
+```
+
+所有 `claude` 命令自动通过 CC-Viewer 代理，实现日志捕获和 Web UI 功能。
+
+卸载：`ccv --uninstall` 或手动删除标记之间的内容。
+
+## 八、代理配置（Proxy Profile）
+
+存储在 `<日志目录>/profile.json`，通过 UI 的"代理切换"面板管理。
+
+```json
+{
+  "active": "max",
+  "profiles": [
+    { "id": "max", "name": "Default" },
+    { "id": "my-proxy", "name": "自定义", "baseURL": "https://...", "apiKey": "sk-..." }
+  ]
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `active` | 当前激活的配置 ID（`"max"` = 直连，无代理） |
+| `id` | 唯一标识 |
+| `name` | 显示名称 |
+| `baseURL` | 代理 API 地址（替换请求 origin） |
+| `apiKey` | 代理 API 密钥（替换认证头） |
+| `models` | 可用模型列表 |
+| `activeModel` | 当前选中的模型 |
+
+## 九、插件系统
+
+插件目录：`<日志目录>/plugins/`
+
+### 支持的 Hook 类型
+
+| Hook | 类型 | 说明 |
+|------|------|------|
+| `httpsOptions` | 瀑布 | 提供 HTTPS 证书（返回 `{ cert, key }` 或 `{ pfx }`） |
+| `localUrl` | 瀑布 | 修改本地访问 URL |
+| `serverStarted` | 并行 | 服务器启动通知 |
+| `serverStopping` | 并行 | 服务器停止通知 |
+| `onNewEntry` | 并行 | 新日志条目写入通知 |
+
+插件启用/禁用通过 `preferences.json` 的 `disabledPlugins` 数组管理。
+
+## 十、目录结构
+
+```
+~/.claude/cc-viewer/               # 日志根目录
+├── preferences.json               # 用户偏好设置
+├── workspaces.json                # 工作空间注册表
+├── profile.json                   # 代理配置
+├── plugins/                       # 插件目录
+│   └── my-plugin.js
+├── <项目名>/                       # 每个项目的日志目录
+│   ├── <项目名>_20260404_123456.jsonl  # JSONL 日志文件
+│   ├── <项目名>.json              # 统计数据（后台生成）
+│   └── images/                    # 上传图片的持久副本
+└── ...
+
+/tmp/cc-viewer-uploads/            # 临时上传文件目录
+```
+
+## 十一、服务器配置
+
+| 配置 | 值 | 说明 |
+|------|-----|------|
+| 端口范围 | 7008-7099 | 自动扫描可用端口 |
+| 绑定地址 | 0.0.0.0 | 所有网络接口 |
+| 访问令牌 | 随机 16 字节 hex | 局域网访问需要 `?token=xxx`，本机免认证 |
+| HTTPS | 仅通过插件 | 需要插件提供 `httpsOptions` hook |
+| CORS | `*` | 允许所有来源 |
+| 上传限制 | 50MB | 单文件最大上传大小 |
+
+## 十二、URL 参数
+
+| 参数 | 说明 |
+|------|------|
+| `?token=xxx` | 局域网访问认证令牌 |
+| `?logfile=path` | 打开指定历史日志文件（只读模式） |
+
+## 十三、localStorage 配置
+
+| 键 | 说明 |
+|-----|------|
+| `cxv_cacheExpireAt` | 缓存倒计时到期时间 |
+| `cxv_cacheType` | 缓存类型标签 |
+| `ccv_sseSlim` | 启用 SSE 增量裁剪（桌面端性能优化） |
+| `ccv_calibrationModel` | KV-Cache 上下文窗口校准模型 |
+| `ccv_fileExplorerOpen` | 文件浏览器面板开关 |
+| `cc-viewer-terminal-width` | 终端面板宽度（像素） |

package/concepts/uk/KVCacheContent.md

@@ -0,0 +1,49 @@
+# Вміст кешу KV-Cache
+
+## Що таке Prompt Caching?
+
+Коли ви спілкуєтесь з Claude, кожен запит API надсилає повний контекст розмови (system prompt + визначення інструментів + історія повідомлень). Механізм prompt caching від Anthropic кешує на сервері вже обчислений вміст префікса, і якщо префікс залишається тим самим у наступних запитах, результат кешу використовується повторно напряму, пропускаючи повторні обчислення та значно зменшуючи затримку і витрати.
+
+У cc-viewer цей механізм називається "KV-Cache" і відповідає prompt caching на рівні Anthropic API, а не key-value кешу в шарах уваги трансформера всередині LLM.
+
+## Як працює кеш
+
+Prompt caching від Anthropic об'єднує ключі кешу у фіксованому порядку:
+
+```
+Tools → System Prompt → Messages (до cache breakpoint)
+```
+
+Поки цей префікс повністю ідентичний будь-якому запиту у вікні TTL, API влучає в кеш (повертає `cache_read_input_tokens`), а не перераховує (`cache_creation_input_tokens`).
+
+> **Claude Code не є сильно залежним від атрибута `cache_control` — сервер видаляє деякі з цих атрибутів, але все одно добре створює кеш, тому відсутність атрибута `cache_control` не означає, що вміст не кешується**
+>
+> Для спеціальних клієнтів на кшталт Claude Code сервер Anthropic не повністю залежить від атрибута `cache_control` у запиті для визначення поведінки кешу. Сервер автоматично застосовує стратегії кешування для певних полів (таких як system prompt і визначення інструментів), навіть коли запит явно не містить маркерів `cache_control`. Тому не дивуйтеся, коли не бачите цей атрибут у тілі запиту — сервер вже виконав операцію кешування за лаштунками, просто не розкрив цю інформацію клієнту. Це негласна домовленість між Claude Code та Anthropic API.
+
+## Що таке "поточний вміст кешу KV-Cache"?
+
+"Поточний вміст кешу KV-Cache", що відображається в cc-viewer, — це вміст, витягнутий з останнього запиту MainAgent, що знаходиться перед межею кешу (cache breakpoint). Конкретно включає:
+
+- **System Prompt**: Системні інструкції Claude Code, включаючи основні інструкції агента, правила використання інструментів, інструкції проєкту CLAUDE.md, інформацію про середовище тощо
+- **Tools**: Список доступних визначень інструментів (таких як Read, Write, Bash, Agent, інструменти MCP тощо)
+- **Messages**: Кешована частина історії розмови (зазвичай старіші повідомлення, до останнього маркера `cache_control`)
+
+## Чому варто переглядати вміст кешу?
+
+1. **Розуміння контексту**: Дізнайтеся, який вміст Claude наразі "пам'ятає", і оцініть, чи його поведінка відповідає очікуванням
+2. **Оптимізація витрат**: Влучення в кеш коштує набагато менше, ніж перерахунок. Перегляд вмісту кешу допомагає зрозуміти, чому певні запити спричинили перебудову кешу (cache rebuild)
+3. **Налагодження розмови**: Коли відповідь Claude не відповідає очікуванням, перевірка вмісту кешу дозволяє підтвердити, чи system prompt та історія повідомлень правильні
+4. **Моніторинг якості контексту**: Під час налагодження, зміни конфігурації або коригування промптів, KV-Cache-Text забезпечує централізовану перспективу, яка допомагає швидко підтвердити, чи основний контекст не погіршився або не був забруднений неочікуваним вмістом — без необхідності переглядати оригінальні повідомлення одне за одним
+
+## Багаторівнева стратегія кешування
+
+KV-Cache, що відповідає Claude Code, — це не єдиний кеш. Сервер генерує окремі кеші для Tools та System Prompt, незалежно від кешу Messages. Перевага такого дизайну: коли стек повідомлень порушується (наприклад, обрізання контексту, зміна повідомлень) і потребує перебудови, це не інвалідує одночасно кеші Tools та System Prompt, уникаючи повного перерахунку.
+
+Це стратегія оптимізації на стороні сервера — оскільки визначення Tools та System Prompt відносно стабільні під час звичайного використання і рідко змінюються, окреме кешування їх максимізує зменшення непотрібних витрат на перебудову. Тому, спостерігаючи за кешем, ви помітите, що окрім перебудови Tools, яка потребує повного оновлення всіх кешів, руйнування System Prompt та Messages все ще дозволяє успадковувати доступні кеші.
+
+## Життєвий цикл кешу
+
+- **Створення**: При першому запиті або після закінчення терміну дії кешу, API створює новий кеш (`cache_creation_input_tokens`)
+- **Влучення**: Наступні запити з ідентичним префіксом повторно використовують кеш (`cache_read_input_tokens`)
+- **Закінчення**: Кеш має TTL (час життя) 5 хвилин і автоматично закінчується після цього часу
+- **Перебудова**: Коли system prompt, список інструментів, модель або вміст повідомлень змінюються, ключ кешу не збігається, що спричиняє перебудову відповідного рівня

package/concepts/uk/MainAgent.md

@@ -0,0 +1,23 @@
+# MainAgent
+
+## Визначення
+
+MainAgent — це основний ланцюг запитів Claude Code у стані без agent team. Кожна взаємодія користувача з Claude Code генерує серію API-запитів, серед яких запити MainAgent формують ядро ланцюга розмови — вони несуть повний system prompt, визначення інструментів та історію повідомлень.
+
+## Спосіб ідентифікації
+
+У cc-viewer MainAgent ідентифікується через `req.mainAgent === true` і автоматично позначається `interceptor.js` під час перехоплення запиту.
+
+Умови визначення (повинні виконуватися всі):
+- Тіло запиту містить поле `system` (system prompt)
+- Тіло запиту містить масив `tools` (визначення інструментів)
+- system prompt містить характерний текст "Claude Code"
+
+## Відмінності від SubAgent
+
+| Характеристика | MainAgent | SubAgent |
+|----------------|-----------|----------|
+| system prompt | Повний основний prompt Claude Code | Скорочений prompt для конкретного завдання |
+| Масив tools | Містить усі доступні інструменти | Зазвичай лише кілька інструментів, необхідних для завдання |
+| Історія повідомлень | Накопичує повний контекст розмови | Лише повідомлення, пов'язані з підзавданням |
+| Поведінка кешу | Є prompt caching (5 хвилин TTL) | Зазвичай без кешу або з невеликим кешем |

package/concepts/uk/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/uk/QRCode.md

@@ -0,0 +1,25 @@
+# Мобільний доступ через QR-код
+
+## Як це працює
+
+CC Viewer запускає HTTP-сервер і генерує **адресу локальної мережі** (наприклад, `http://192.168.1.100:7008`). Відскануйте QR-код, щоб отримати доступ до Claude Code з телефону через ту ж мережу WiFi.
+
+## Чому не вдається підключитися?
+
+1. **Не в одній мережі** — Телефон і комп'ютер мають бути підключені до одного WiFi (один роутер/одна назва мережі)
+2. **Блокування файрвола** — Файрвол системи може блокувати вхідні з'єднання
+3. **Ізоляція корпоративної мережі** — Ізоляція AP може перешкоджати зв'язку між пристроями
+4. **Втручання VPN** — VPN може порушити мережевий маршрут
+
+## Повідомлення про безпеку
+
+> ⚠️ LAN-сервіс CC Viewer доступний усім пристроям в одній мережі.
+
+- Будьте обережні в **публічному WiFi**
+- CC Viewer використовує **автентифікацію за токеном** для захисту LAN-доступу
+- Рекомендується використовувати в довірених мережах
+
+## За межами LAN
+
+- **Інструменти тунелювання** — frp, ngrok, Tailscale та ін.
+- **Плагіни CC Viewer** — Налаштуйте проксі-сервер через систему плагінів

package/concepts/uk/ResponseFields.md

@@ -0,0 +1,50 @@
+# Опис полів Response Body
+
+Опис полів тіла відповіді Claude API `/v1/messages`.
+
+## Поля верхнього рівня
+
+| Поле | Тип | Опис |
+|------|------|------|
+| **model** | string | Фактична назва моделі, наприклад `claude-opus-4-6` |
+| **id** | string | Унікальний ідентифікатор відповіді, наприклад `msg_01Tgsr2QeH8AVXGoP2wAXRvU` |
+| **type** | string | Фіксоване значення `"message"` |
+| **role** | string | Фіксоване значення `"assistant"` |
+| **content** | array | Масив блоків вмісту виводу моделі, включаючи текст, виклики інструментів, процес мислення тощо |
+| **stop_reason** | string | Причина зупинки: `"end_turn"` (нормальне завершення), `"tool_use"` (потрібно виконати інструмент), `"max_tokens"` (досягнуто ліміт токенів) |
+| **stop_sequence** | string/null | Послідовність, що спричинила зупинку, зазвичай `null` |
+| **usage** | object | Статистика використання токенів (деталі нижче) |
+
+## Типи блоків content
+
+| Тип | Опис |
+|------|------|
+| **text** | Текстова відповідь моделі, містить поле `text` |
+| **tool_use** | Запит на виклик інструменту, містить `name` (назва інструменту), `input` (параметри), `id` (ідентифікатор виклику, використовується для зіставлення з tool_result) |
+| **thinking** | Розширений процес мислення (з'являється лише при увімкненому режимі thinking), містить поле `thinking` |
+
+## Деталі поля usage
+
+| Поле | Опис |
+|------|------|
+| **input_tokens** | Кількість вхідних токенів без влучення в кеш (тарифікуються за повною ціною) |
+| **cache_creation_input_tokens** | Кількість токенів, закешованих у цьому запиті (запис у кеш, тарифікується вище за звичайний ввід) |
+| **cache_read_input_tokens** | Кількість токенів із влученням у кеш (читання з кешу, тарифікується значно нижче за звичайний ввід) |
+| **output_tokens** | Кількість вихідних токенів моделі |
+| **service_tier** | Рівень обслуговування, наприклад `"standard"` |
+| **inference_geo** | Регіон виведення, наприклад `"not_available"` означає відсутність інформації про регіон |
+
+## Підполя cache_creation
+
+| Поле | Опис |
+|------|------|
+| **ephemeral_5m_input_tokens** | Кількість токенів короткострокового кешу з TTL 5 хвилин |
+| **ephemeral_1h_input_tokens** | Кількість токенів довгострокового кешу з TTL 1 година |
+
+> **Про тарифікацію кешу**: Ціна за одиницю `cache_read_input_tokens` значно нижча за `input_tokens`, тоді як ціна за одиницю `cache_creation_input_tokens` трохи вища за звичайний ввід. Тому підтримка високого відсотка влучень у кеш під час безперервних розмов може суттєво знизити витрати. За допомогою метрики "відсоток влучень" у cc-viewer можна зручно відстежувати цю пропорцію.
+
+## Значення stop_reason
+
+- **end_turn**: Модель нормально завершила відповідь
+- **tool_use**: Модель потребує виклику інструменту, content міститиме блок `tool_use`. У наступному запиті потрібно додати `tool_result` до messages для продовження розмови
+- **max_tokens**: Досягнуто ліміт `max_tokens`, відповідь обрізана і може бути неповною

package/concepts/uk/SubAgent-Search.md

@@ -0,0 +1,20 @@
+# SubAgent: Search
+
+## Визначення
+
+Search — це тип sub-agent, що породжується головним агентом Claude Code для виконання пошуку в кодовій базі. Він здійснює цільовий пошук файлів і вмісту за допомогою таких інструментів, як Glob, Grep і Read, а потім повертає результати батьківському агенту.
+
+## Поведінка
+
+- Породжується автоматично, коли головному агенту потрібно шукати або досліджувати кодову базу
+- Працює в ізольованому контексті з доступом лише для читання
+- Використовує Glob для пошуку файлів за шаблоном, Grep для пошуку у вмісті та Read для інспекції файлів
+- Повертає результати пошуку батьківському агенту для подальшої обробки
+
+## Коли з'являється
+
+Search sub-agents зазвичай з'являються, коли:
+
+1. Головному агенту потрібно знайти конкретні файли, функції або патерни коду
+2. Користувач запитує широке дослідження кодової бази
+3. Агент досліджує залежності, посилання або патерни використання

package/concepts/uk/Teammate.md

@@ -0,0 +1,26 @@
+# Teammate
+
+## Визначення
+
+Teammate — це колаборативний agent у режимі команди Claude Code Agent Team. Коли головний agent створює команду через `TeamCreate` і генерує teammate за допомогою інструменту `Agent`, кожен teammate працює як незалежний процес agent із власним контекстним вікном та набором інструментів, спілкуючись з членами команди через `SendMessage`.
+
+## Відмінності від SubAgent
+
+| Характеристика | Teammate | SubAgent |
+|------|----------|----------|
+| Життєвий цикл | Існує постійно, може отримувати кілька повідомлень | Одноразове завдання, знищується після завершення |
+| Спосіб комунікації | Двонаправлені повідомлення через SendMessage | Односпрямований виклик батько→дитина, повернення результату |
+| Контекст | Незалежний повний контекст, зберігається між раундами | Ізольований контекст завдання |
+| Модель співпраці | Командна співпраця, можуть спілкуватися між собою | Ієрархічна структура, взаємодія лише з батьківським agent |
+| Тип завдань | Складні багатокрокові завдання | Одиничні завдання: пошук, дослідження тощо |
+
+## Поведінка
+
+- Створюється головним agent (team lead) через інструмент `Agent` з призначенням `team_name`
+- Спільний список завдань через `TaskList` / `TaskGet` / `TaskUpdate`
+- Після кожного раунду виконання переходить у стан idle, очікуючи нове повідомлення для активації
+- Може бути коректно завершений через `shutdown_request`
+
+## Опис панелі статистики
+
+Панель статистики Teammate відображає кількість API-викликів кожного teammate. Стовпець `Name` містить ім'я teammate (наприклад, `reviewer-security`, `reviewer-pipeline`), стовпець `Кількість` — загальну кількість API-запитів, згенерованих цим teammate.

package/concepts/uk/Tool-Agent.md

@@ -0,0 +1,125 @@
+# Agent
+
+## Визначення
+
+Запускає підагента (SubAgent) для автономної обробки складних багатокрокових завдань. Підагенти — це незалежні підпроцеси, кожен з яких має власний набір інструментів та контекст. Agent — це перейменована версія інструменту Task у нових версіях Claude Code.
+
+## Параметри
+
+| Параметр | Тип | Обов'язковий | Опис |
+|----------|-----|--------------|------|
+| `prompt` | string | Так | Опис завдання для виконання підагентом |
+| `description` | string | Так | Короткий опис у 3-5 слів |
+| `subagent_type` | string | Так | Тип підагента, визначає доступний набір інструментів |
+| `model` | enum | Ні | Вказати модель (sonnet / opus / haiku), за замовчуванням успадковується від батьківського |
+| `max_turns` | integer | Ні | Максимальна кількість агентних раундів |
+| `run_in_background` | boolean | Ні | Чи запускати у фоновому режимі; фонові завдання повертають шлях output_file |
+| `resume` | string | Ні | ID агента для відновлення, продовжує з останнього виконання. Корисно для продовження попереднього підагента без втрати контексту |
+| `isolation` | enum | Ні | Режим ізоляції, `worktree` створює тимчасовий git worktree |
+
+## Типи підагентів
+
+| Тип | Призначення | Доступні інструменти |
+|-----|-------------|---------------------|
+| `Bash` | Виконання команд, операції git | Bash |
+| `general-purpose` | Загальні багатокрокові завдання | Усі інструменти |
+| `Explore` | Швидке дослідження кодової бази | Усі інструменти, крім Agent/Edit/Write/NotebookEdit/ExitPlanMode |
+| `Plan` | Проєктування плану реалізації | Усі інструменти, крім Agent/Edit/Write/NotebookEdit/ExitPlanMode |
+| `claude-code-guide` | Запитання-відповіді з посібника Claude Code | Glob, Grep, Read, WebFetch, WebSearch |
+| `statusline-setup` | Налаштування рядка стану | Read, Edit |
+
+## Сценарії використання
+
+**Підходить для:**
+- Складні завдання, що потребують багатокрокового автономного виконання
+- Дослідження кодової бази та глибокий аналіз (з типом Explore)
+- Паралельна робота, що потребує ізольованого середовища
+- Довготривалі завдання, що потребують фонового виконання
+
+**Не підходить для:**
+- Читання конкретного шляху файлу — використовуйте безпосередньо Read або Glob
+- Пошук у 2-3 відомих файлах — використовуйте безпосередньо Read
+- Пошук конкретного визначення класу — використовуйте безпосередньо Glob
+
+## Примітки
+
+- Після завершення підагент повертає одне повідомлення; його результати не видимі користувачу, основний агент повинен їх передати
+- Для підвищення ефективності можна запускати кілька паралельних викликів Agent в одному повідомленні
+- Прогрес фонових завдань перевіряється через інструмент TaskOutput
+- Тип Explore повільніший за прямий виклик Glob/Grep, використовуйте лише коли простого пошуку недостатньо
+- Використовуйте `run_in_background: true` для довготривалих завдань, що не потребують негайного результату; використовуйте режим переднього плану (за замовчуванням), коли результат потрібен перед продовженням
+- Параметр `resume` дозволяє продовжити раніше розпочату сесію підагента, зберігаючи накопичений контекст
+
+## Оригінальний текст
+
+<textarea readonly>Launch a new agent to handle complex, multi-step tasks autonomously.
+
+The Agent tool launches specialized agents (subprocesses) that autonomously handle complex tasks. Each agent type has specific capabilities and tools available to it.
+
+Available agent types and the tools they have access to:
+- general-purpose: General-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. When you are searching for a keyword or file and are not confident that you will find the right match in the first few tries use this agent to perform the search for you. (Tools: *)
+- statusline-setup: Use this agent to configure the user's Claude Code status line setting. (Tools: Read, Edit)
+- Explore: Fast agent specialized for exploring codebases. Use this when you need to quickly find files by patterns (eg. "src/components/**/*.tsx"), search code for keywords (eg. "API endpoints"), or answer questions about the codebase (eg. "how do API endpoints work?"). When calling this agent, specify the desired thoroughness level: "quick" for basic searches, "medium" for moderate exploration, or "very thorough" for comprehensive analysis across multiple locations and naming conventions. (Tools: All tools except Agent, ExitPlanMode, Edit, Write, NotebookEdit)
+- Plan: Software architect agent for designing implementation plans. Use this when you need to plan the implementation strategy for a task. Returns step-by-step plans, identifies critical files, and considers architectural trade-offs. (Tools: All tools except Agent, ExitPlanMode, Edit, Write, NotebookEdit)
+- claude-code-guide: Use this agent when the user asks questions ("Can Claude...", "Does Claude...", "How do I...") about: (1) Claude Code (the CLI tool) - features, hooks, slash commands, MCP servers, settings, IDE integrations, keyboard shortcuts; (2) Claude Agent SDK - building custom agents; (3) Claude API (formerly Anthropic API) - API usage, tool use, Anthropic SDK usage. **IMPORTANT:** Before spawning a new agent, check if there is already a running or recently completed claude-code-guide agent that you can resume using the "resume" parameter. (Tools: Glob, Grep, Read, WebFetch, WebSearch)
+
+When using the Agent tool, you must specify a subagent_type parameter to select which agent type to use.
+
+When NOT to use the Agent tool:
+- If you want to read a specific file path, use the Read or Glob tool instead of the Agent tool, to find the match more quickly
+- If you are searching for a specific class definition like "class Foo", use the Glob tool instead, to find the match more quickly
+- If you are searching for code within a specific file or set of 2-3 files, use the Read tool instead of the Agent tool, to find the match more quickly
+- Other tasks that are not related to the agent descriptions above
+
+Usage notes:
+- Always include a short description (3-5 words) summarizing what the agent will do
+- Launch multiple agents concurrently whenever possible, to maximize performance; to do that, use a single message with multiple tool uses
+- When the agent is done, it will return a single message back to you. The result returned by the agent is not visible to the user. To show the user the result, you should send a text message back to the user with a concise summary of the result.
+- You can optionally run agents in the background using the run_in_background parameter. When an agent runs in the background, you will be automatically notified when it completes — do NOT sleep, poll, or proactively check on its progress. Continue with other work or respond to the user instead.
+- **Foreground vs background**: Use foreground (default) when you need the agent's results before you can proceed — e.g., research agents whose findings inform your next steps. Use background when you have genuinely independent work to do in parallel.
+- Agents can be resumed using the `resume` parameter by passing the agent ID from a previous invocation. When resumed, the agent continues with its full previous context preserved. When NOT resuming, each invocation starts fresh and you should provide a detailed task description with all necessary context.
+- When the agent is done, it will return a single message back to you along with its agent ID. You can use this ID to resume the agent later if needed for follow-up work.
+- Provide clear, detailed prompts so the agent can work autonomously and return exactly the information you need.
+- Agents with "access to current context" can see the full conversation history before the tool call. When using these agents, you can write concise prompts that reference earlier context (e.g., "investigate the error discussed above") instead of repeating information. The agent will receive all prior messages and understand the context.
+- The agent's outputs should generally be trusted
+- Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, web fetches, etc.), since it is not aware of the user's intent
+- If the agent description mentions that it should be used proactively, then you should try your best to use it without the user having to ask for it first. Use your judgement.
+- If the user specifies that they want you to run agents "in parallel", you MUST send a single message with multiple Agent tool use content blocks. For example, if you need to launch both a build-validator agent and a test-runner agent in parallel, send a single message with both tool calls.
+- You can optionally set `isolation: "worktree"` to run the agent in a temporary git worktree, giving it an isolated copy of the repository. The worktree is automatically cleaned up if the agent makes no changes; if changes are made, the worktree path and branch are returned in the result.
+
+Example usage:
+
+<example_agent_descriptions>
+"test-runner": use this agent after you are done writing code to run tests
+"greeting-responder": use this agent to respond to user greetings with a friendly joke
+</example_agent_descriptions>
+
+<example>
+user: "Please write a function that checks if a number is prime"
+assistant: Sure let me write a function that checks if a number is prime
+assistant: First let me use the Write tool to write a function that checks if a number is prime
+assistant: I'm going to use the Write tool to write the following code:
+<code>
+function isPrime(n) {
+  if (n <= 1) return false
+  for (let i = 2; i * i <= n; i++) {
+    if (n % i === 0) return false
+  }
+  return true
+}
+</code>
+<commentary>
+Since a significant piece of code was written and the task was completed, now use the test-runner agent to run the tests
+</commentary>
+assistant: Now let me use the test-runner agent to run the tests
+assistant: Uses the Agent tool to launch the test-runner agent
+</example>
+
+<example>
+user: "Hello"
+<commentary>
+Since the user is greeting, use the greeting-responder agent to respond with a friendly joke
+</commentary>
+assistant: "I'm going to use the Agent tool to launch the greeting-responder agent"
+</example>
+</textarea>