diff --git a/uk/06-hooks/README.md b/uk/06-hooks/README.md new file mode 100644 index 0000000..44078d8 --- /dev/null +++ b/uk/06-hooks/README.md @@ -0,0 +1,1174 @@ + + + + + + + Claude How To + + +# Хуки + +Хуки — це автоматизовані скрипти, які виконуються у відповідь на конкретні події під час сесій Claude Code. Вони забезпечують автоматизацію, валідацію, управління дозволами та кастомні робочі процеси. + +## Огляд + +Хуки — це автоматичні дії (shell-команди, HTTP-вебхуки, LLM-промпти або оцінки субагентів), що виконуються автоматично при виникненні конкретних подій у Claude Code. Вони отримують JSON-вхід і повідомляють результати через коди виходу та JSON-вивід. + +**Ключові можливості:** +- Автоматизація на основі подій +- Введення/виведення на основі JSON +- Підтримка типів хуків: command, prompt, HTTP та agent +- Відповідність шаблонам (pattern matching) для хуків, специфічних для інструментів + +## Конфігурація + +Хуки налаштовуються у файлах налаштувань з конкретною структурою: + +- `~/.claude/settings.json` — налаштування користувача (усі проєкти) +- `.claude/settings.json` — налаштування проєкту (спільні, комітяться) +- `.claude/settings.local.json` — локальні налаштування проєкту (не комітяться) +- Керована політика (Managed policy) — загальноорганізаційні налаштування +- `hooks/hooks.json` плагіна — хуки з областю дії плагіна +- Frontmatter навичок/агентів — хуки часу життя компонентів + +### Базова структура конфігурації + +```json +{ + "hooks": { + "EventName": [ + { + "matcher": "ToolPattern", + "hooks": [ + { + "type": "command", + "command": "your-command-here", + "timeout": 60 + } + ] + } + ] + } +} +``` + +**Ключові поля:** + +| Поле | Опис | Приклад | +|------|------|---------| +| `matcher` | Шаблон для відповідності назвам інструментів (чутливий до регістру) | `"Write"`, `"Edit\|Write"`, `"*"` | +| `hooks` | Масив визначень хуків | `[{ "type": "command", ... }]` | +| `type` | Тип хука: `"command"` (bash), `"prompt"` (LLM), `"http"` (вебхук) або `"agent"` (субагент) | `"command"` | +| `command` | Shell-команда для виконання | `"$CLAUDE_PROJECT_DIR/.claude/hooks/format.sh"` | +| `timeout` | Необовʼязковий таймаут у секундах (за замовчуванням 60) | `30` | +| `once` | Якщо `true`, хук запускається лише один раз за сесію | `true` | + +### Шаблони matcher + +| Шаблон | Опис | Приклад | +|--------|------|---------| +| Точний рядок | Відповідає конкретному інструменту | `"Write"` | +| Regex-шаблон | Відповідає кільком інструментам | `"Edit\|Write"` | +| Підстановочний знак | Відповідає всім інструментам | `"*"` або `""` | +| MCP-інструменти | Шаблон сервера та інструмента | `"mcp__memory__.*"` | + +**Значення matcher для InstructionsLoaded:** + +| Значення matcher | Опис | +|-----------------|------| +| `session_start` | Інструкції завантажені при запуску сесії | +| `nested_traversal` | Інструкції завантажені при обході вкладених каталогів | +| `path_glob_match` | Інструкції завантажені через відповідність glob-шаблону шляху | + +## Типи хуків + +Claude Code підтримує чотири типи хуків: + +### Command-хуки + +Тип за замовчуванням. Виконує shell-команду та комунікує через JSON stdin/stdout і коди виходу. + +```json +{ + "type": "command", + "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/validate.py\"", + "timeout": 60 +} +``` + +### HTTP-хуки + +> Додано у v2.1.63. + +Віддалені вебхук-ендпоінти, які отримують той самий JSON-вхід, що й command-хуки. HTTP-хуки надсилають POST JSON на URL і отримують JSON-відповідь. HTTP-хуки маршрутизуються через пісочницю (sandbox), коли вона увімкнена. Інтерполяція змінних оточення в URL вимагає явного списку `allowedEnvVars` з міркувань безпеки. + +```json +{ + "hooks": { + "PostToolUse": [{ + "type": "http", + "url": "https://my-webhook.example.com/hook", + "matcher": "Write" + }] + } +} +``` + +**Ключові властивості:** +- `"type": "http"` — ідентифікує як HTTP-хук +- `"url"` — URL ендпоінту вебхука +- Маршрутизується через sandbox, коли sandbox увімкнено +- Вимагає явного списку `allowedEnvVars` для будь-якої інтерполяції змінних оточення в URL + +### Prompt-хуки + +Промпти, оцінювані LLM, де вміст хука є промптом, який оцінює Claude. Переважно використовуються з подіями `Stop` та `SubagentStop` для інтелектуальної перевірки завершення завдань. + +```json +{ + "type": "prompt", + "prompt": "Evaluate if Claude completed all requested tasks.", + "timeout": 30 +} +``` + +LLM оцінює промпт і повертає структуроване рішення (деталі див. у [Prompt-хуки](#prompt-хуки-1)). + +### Agent-хуки + +Хуки верифікації на основі субагентів, які створюють виділеного агента для оцінки умов або виконання складних перевірок. На відміну від prompt-хуків (однокрокова оцінка LLM), agent-хуки можуть використовувати інструменти та виконувати багатокрокове міркування. + +```json +{ + "type": "agent", + "prompt": "Verify the code changes follow our architecture guidelines. Check the relevant design docs and compare.", + "timeout": 120 +} +``` + +**Ключові властивості:** +- `"type": "agent"` — ідентифікує як agent-хук +- `"prompt"` — опис завдання для субагента +- Агент може використовувати інструменти (Read, Grep, Bash тощо) для оцінки +- Повертає структуроване рішення, аналогічне prompt-хукам + +## Події хуків + +Claude Code підтримує **26 подій хуків**: + +| Подія | Коли спрацьовує | Вхід matcher | Може блокувати | Типове використання | +|-------|----------------|-------------|----------------|---------------------| +| **SessionStart** | Початок/відновлення/очищення/компакція сесії | startup/resume/clear/compact | Ні | Налаштування середовища | +| **InstructionsLoaded** | Після завантаження CLAUDE.md або файлу правил | (немає) | Ні | Модифікація/фільтрація інструкцій | +| **UserPromptSubmit** | Користувач подає промпт | (немає) | Так | Валідація промптів | +| **PreToolUse** | Перед виконанням інструмента | Назва інструмента | Так (allow/deny/ask) | Валідація, модифікація вхідних даних | +| **PermissionRequest** | Показ діалогу дозволів | Назва інструмента | Так | Автозатвердження/відхилення | +| **PermissionDenied** | Користувач відхиляє запит дозволу | Назва інструмента | Ні | Логування, аналітика, політики | +| **PostToolUse** | Після успішного виконання інструмента | Назва інструмента | Ні | Контекст, зворотний звʼязок | +| **PostToolUseFailure** | Невдале виконання інструмента | Назва інструмента | Ні | Обробка помилок, логування | +| **Notification** | Надсилання сповіщення | Тип сповіщення | Ні | Кастомні сповіщення | +| **SubagentStart** | Створення субагента | Назва типу агента | Ні | Налаштування субагента | +| **SubagentStop** | Завершення субагента | Назва типу агента | Так | Валідація субагента | +| **Stop** | Claude завершує відповідь | (немає) | Так | Перевірка завершення завдання | +| **StopFailure** | Помилка API завершує хід | (немає) | Ні | Відновлення після помилок, логування | +| **TeammateIdle** | Неактивність учасника Agent Teams | (немає) | Так | Координація учасників | +| **TaskCompleted** | Завдання позначено як виконане | (немає) | Так | Дії після завершення завдання | +| **TaskCreated** | Завдання створене через TaskCreate | (немає) | Ні | Відстеження завдань, логування | +| **ConfigChange** | Зміна файлу конфігурації | (немає) | Так (крім policy) | Реакція на оновлення конфігурації | +| **CwdChanged** | Зміна робочого каталогу | (немає) | Ні | Налаштування для каталогу | +| **FileChanged** | Зміна відстежуваного файлу | (немає) | Ні | Моніторинг файлів, перебудова | +| **PreCompact** | Перед компакцією контексту | manual/auto | Ні | Дії перед компакцією | +| **PostCompact** | Після завершення компакції | (немає) | Ні | Дії після компакції | +| **WorktreeCreate** | Створення робочого дерева (worktree) | (немає) | Так (повернення шляху) | Ініціалізація worktree | +| **WorktreeRemove** | Видалення робочого дерева | (немає) | Ні | Очищення worktree | +| **Elicitation** | MCP-сервер запитує введення користувача | (немає) | Так | Валідація введення | +| **ElicitationResult** | Відповідь користувача на elicitation | (немає) | Так | Обробка відповіді | +| **SessionEnd** | Завершення сесії | (немає) | Ні | Очищення, фінальне логування | + +### PreToolUse + +Запускається після створення параметрів інструмента Claude і перед обробкою. Використовується для валідації або модифікації вхідних даних інструмента. + +**Конфігурація:** +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/validate-bash.py" + } + ] + } + ] + } +} +``` + +**Типові matcher:** `Task`, `Bash`, `Glob`, `Grep`, `Read`, `Edit`, `Write`, `WebFetch`, `WebSearch` + +**Управління виводом:** +- `permissionDecision`: `"allow"`, `"deny"` або `"ask"` +- `permissionDecisionReason`: Пояснення рішення +- `updatedInput`: Модифіковані вхідні параметри інструмента + +### PostToolUse + +Запускається одразу після завершення інструмента. Використовується для верифікації, логування або надання контексту назад Claude. + +**Конфігурація:** +```json +{ + "hooks": { + "PostToolUse": [ + { + "matcher": "Write|Edit", + "hooks": [ + { + "type": "command", + "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/security-scan.py" + } + ] + } + ] + } +} +``` + +**Управління виводом:** +- Рішення `"block"` подає Claude зворотний звʼязок +- `additionalContext`: Контекст, доданий для Claude + +### UserPromptSubmit + +Запускається, коли користувач подає промпт, перед тим як Claude його обробить. + +**Конфігурація:** +```json +{ + "hooks": { + "UserPromptSubmit": [ + { + "hooks": [ + { + "type": "command", + "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/validate-prompt.py" + } + ] + } + ] + } +} +``` + +**Управління виводом:** +- `decision`: `"block"` для запобігання обробці +- `reason`: Пояснення у разі блокування +- `additionalContext`: Контекст, доданий до промпта + +### Stop та SubagentStop + +Запускаються, коли Claude завершує відповідь (Stop) або субагент завершує роботу (SubagentStop). Підтримують оцінку на основі промптів для інтелектуальної перевірки завершення завдань. + +**Додаткове поле введення:** Обидва хуки `Stop` та `SubagentStop` отримують поле `last_assistant_message` у JSON-вході, що містить останнє повідомлення від Claude або субагента перед зупинкою. Це корисно для оцінки завершення завдання. + +**Конфігурація:** +```json +{ + "hooks": { + "Stop": [ + { + "hooks": [ + { + "type": "prompt", + "prompt": "Evaluate if Claude completed all requested tasks.", + "timeout": 30 + } + ] + } + ] + } +} +``` + +### SubagentStart + +Запускається при початку виконання субагента. Вхід matcher — назва типу агента, що дозволяє хукам націлюватися на конкретні типи субагентів. + +**Конфігурація:** +```json +{ + "hooks": { + "SubagentStart": [ + { + "matcher": "code-review", + "hooks": [ + { + "type": "command", + "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/subagent-init.sh" + } + ] + } + ] + } +} +``` + +### SessionStart + +Запускається при старті або відновленні сесії. Може зберігати змінні оточення. + +**Matcher:** `startup`, `resume`, `clear`, `compact` + +**Спеціальна можливість:** Використовуйте `CLAUDE_ENV_FILE` для збереження змінних оточення (також доступно в хуках `CwdChanged` та `FileChanged`): + +```bash +#!/bin/bash +if [ -n "$CLAUDE_ENV_FILE" ]; then + echo 'export NODE_ENV=development' >> "$CLAUDE_ENV_FILE" +fi +exit 0 +``` + +### SessionEnd + +Запускається при завершенні сесії для очищення або фінального логування. Не може блокувати завершення. + +**Значення поля reason:** +- `clear` — користувач очистив сесію +- `logout` — користувач вийшов із системи +- `prompt_input_exit` — користувач вийшов через введення промпта +- `other` — інша причина + +**Конфігурація:** +```json +{ + "hooks": { + "SessionEnd": [ + { + "hooks": [ + { + "type": "command", + "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/session-cleanup.sh\"" + } + ] + } + ] + } +} +``` + +### Подія Notification + +Оновлені matcher для подій сповіщень: +- `permission_prompt` — сповіщення про запит дозволу +- `idle_prompt` — сповіщення про стан простою +- `auth_success` — успішна автентифікація +- `elicitation_dialog` — діалог, показаний користувачу + +## Хуки з областю дії компонентів + +Хуки можна прикріплювати до конкретних компонентів (навички, агенти, команди) у їхньому frontmatter: + +**У SKILL.md, agent.md або command.md:** + +```yaml +--- +name: secure-operations +description: Perform operations with security checks +hooks: + PreToolUse: + - matcher: "Bash" + hooks: + - type: command + command: "./scripts/check.sh" + once: true # Запустити лише один раз за сесію +--- +``` + +**Підтримувані події для хуків компонентів:** `PreToolUse`, `PostToolUse`, `Stop` + +Це дозволяє визначати хуки безпосередньо в компоненті, що їх використовує, зберігаючи повʼязаний код разом. + +### Хуки у frontmatter субагента + +Коли хук `Stop` визначений у frontmatter субагента, він автоматично перетворюється на хук `SubagentStop` з областю дії цього субагента. Це гарантує, що хук зупинки спрацьовує лише коли завершує роботу саме цей субагент, а не при зупинці основної сесії. + +```yaml +--- +name: code-review-agent +description: Automated code review subagent +hooks: + Stop: + - hooks: + - type: prompt + prompt: "Verify the code review is thorough and complete." + # Наведений Stop-хук автоматично перетворюється на SubagentStop для цього субагента +--- +``` + +## Подія PermissionRequest + +Обробка запитів дозволів з кастомним форматом виводу: + +```json +{ + "hookSpecificOutput": { + "hookEventName": "PermissionRequest", + "decision": { + "behavior": "allow|deny", + "updatedInput": {}, + "message": "Custom message", + "interrupt": false + } + } +} +``` + +## Вхідні та вихідні дані хуків + +### JSON-вхід (через stdin) + +Усі хуки отримують JSON-вхід через stdin: + +```json +{ + "session_id": "abc123", + "transcript_path": "/path/to/transcript.jsonl", + "cwd": "/current/working/directory", + "permission_mode": "default", + "hook_event_name": "PreToolUse", + "tool_name": "Write", + "tool_input": { + "file_path": "/path/to/file.js", + "content": "..." + }, + "tool_use_id": "toolu_01ABC123...", + "agent_id": "agent-abc123", + "agent_type": "main", + "worktree": "/path/to/worktree" +} +``` + +**Загальні поля:** + +| Поле | Опис | +|------|------| +| `session_id` | Унікальний ідентифікатор сесії | +| `transcript_path` | Шлях до файлу транскрипту розмови | +| `cwd` | Поточний робочий каталог | +| `hook_event_name` | Назва події, що запустила хук | +| `agent_id` | Ідентифікатор агента, що запускає хук | +| `agent_type` | Тип агента (`"main"`, назва типу субагента тощо) | +| `worktree` | Шлях до git worktree, якщо агент працює в ньому | + +### Коди виходу + +| Код виходу | Значення | Поведінка | +|-----------|----------|----------| +| **0** | Успіх | Продовжити, розібрати JSON stdout | +| **2** | Блокуюча помилка | Заблокувати операцію, stderr показується як помилка | +| **Інші** | Неблокуюча помилка | Продовжити, stderr показується у verbose-режимі | + +### JSON-вивід (stdout, код виходу 0) + +```json +{ + "continue": true, + "stopReason": "Optional message if stopping", + "suppressOutput": false, + "systemMessage": "Optional warning message", + "hookSpecificOutput": { + "hookEventName": "PreToolUse", + "permissionDecision": "allow", + "permissionDecisionReason": "File is in allowed directory", + "updatedInput": { + "file_path": "/modified/path.js" + } + } +} +``` + +## Змінні оточення + +| Змінна | Доступність | Опис | +|--------|------------|------| +| `CLAUDE_PROJECT_DIR` | Усі хуки | Абсолютний шлях до кореня проєкту | +| `CLAUDE_ENV_FILE` | SessionStart, CwdChanged, FileChanged | Шлях до файлу для збереження змінних оточення | +| `CLAUDE_CODE_REMOTE` | Усі хуки | `"true"` при роботі у віддаленому середовищі | +| `${CLAUDE_PLUGIN_ROOT}` | Хуки плагінів | Шлях до каталогу плагіна | +| `${CLAUDE_PLUGIN_DATA}` | Хуки плагінів | Шлях до каталогу даних плагіна | +| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | Хуки SessionEnd | Налаштовуваний таймаут у мілісекундах для хуків SessionEnd (перевизначає стандартний) | + +## Prompt-хуки + +Для подій `Stop` та `SubagentStop` можна використовувати оцінку на основі LLM: + +```json +{ + "hooks": { + "Stop": [ + { + "hooks": [ + { + "type": "prompt", + "prompt": "Review if all tasks are complete. Return your decision.", + "timeout": 30 + } + ] + } + ] + } +} +``` + +**Схема відповіді LLM:** +```json +{ + "decision": "approve", + "reason": "All tasks completed successfully", + "continue": false, + "stopReason": "Task complete" +} +``` + +## Приклади + +### Приклад 1: Валідатор Bash-команд (PreToolUse) + +**Файл:** `.claude/hooks/validate-bash.py` + +```python +#!/usr/bin/env python3 +import json +import sys +import re + +BLOCKED_PATTERNS = [ + (r"\brm\s+-rf\s+/", "Blocking dangerous rm -rf / command"), + (r"\bsudo\s+rm", "Blocking sudo rm command"), +] + +def main(): + input_data = json.load(sys.stdin) + + tool_name = input_data.get("tool_name", "") + if tool_name != "Bash": + sys.exit(0) + + command = input_data.get("tool_input", {}).get("command", "") + + for pattern, message in BLOCKED_PATTERNS: + if re.search(pattern, command): + print(message, file=sys.stderr) + sys.exit(2) # Код виходу 2 = блокуюча помилка + + sys.exit(0) + +if __name__ == "__main__": + main() +``` + +**Конфігурація:** +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/validate-bash.py\"" + } + ] + } + ] + } +} +``` + +### Приклад 2: Сканер безпеки (PostToolUse) + +**Файл:** `.claude/hooks/security-scan.py` + +```python +#!/usr/bin/env python3 +import json +import sys +import re + +SECRET_PATTERNS = [ + (r"password\s*=\s*['\"][^'\"]+['\"]", "Potential hardcoded password"), + (r"api[_-]?key\s*=\s*['\"][^'\"]+['\"]", "Potential hardcoded API key"), +] + +def main(): + input_data = json.load(sys.stdin) + + tool_name = input_data.get("tool_name", "") + if tool_name not in ["Write", "Edit"]: + sys.exit(0) + + tool_input = input_data.get("tool_input", {}) + content = tool_input.get("content", "") or tool_input.get("new_string", "") + file_path = tool_input.get("file_path", "") + + warnings = [] + for pattern, message in SECRET_PATTERNS: + if re.search(pattern, content, re.IGNORECASE): + warnings.append(message) + + if warnings: + output = { + "hookSpecificOutput": { + "hookEventName": "PostToolUse", + "additionalContext": f"Security warnings for {file_path}: " + "; ".join(warnings) + } + } + print(json.dumps(output)) + + sys.exit(0) + +if __name__ == "__main__": + main() +``` + +### Приклад 3: Автоформатування коду (PostToolUse) + +**Файл:** `.claude/hooks/format-code.sh` + +```bash +#!/bin/bash + +# Читання JSON з stdin +INPUT=$(cat) +TOOL_NAME=$(echo "$INPUT" | python3 -c "import sys, json; print(json.load(sys.stdin).get('tool_name', ''))") +FILE_PATH=$(echo "$INPUT" | python3 -c "import sys, json; print(json.load(sys.stdin).get('tool_input', {}).get('file_path', ''))") + +if [ "$TOOL_NAME" != "Write" ] && [ "$TOOL_NAME" != "Edit" ]; then + exit 0 +fi + +# Форматування залежно від розширення файлу +case "$FILE_PATH" in + *.js|*.jsx|*.ts|*.tsx|*.json) + command -v prettier &>/dev/null && prettier --write "$FILE_PATH" 2>/dev/null + ;; + *.py) + command -v black &>/dev/null && black "$FILE_PATH" 2>/dev/null + ;; + *.go) + command -v gofmt &>/dev/null && gofmt -w "$FILE_PATH" 2>/dev/null + ;; +esac + +exit 0 +``` + +### Приклад 4: Валідатор промптів (UserPromptSubmit) + +**Файл:** `.claude/hooks/validate-prompt.py` + +```python +#!/usr/bin/env python3 +import json +import sys +import re + +BLOCKED_PATTERNS = [ + (r"delete\s+(all\s+)?database", "Dangerous: database deletion"), + (r"rm\s+-rf\s+/", "Dangerous: root deletion"), +] + +def main(): + input_data = json.load(sys.stdin) + prompt = input_data.get("user_prompt", "") or input_data.get("prompt", "") + + for pattern, message in BLOCKED_PATTERNS: + if re.search(pattern, prompt, re.IGNORECASE): + output = { + "decision": "block", + "reason": f"Blocked: {message}" + } + print(json.dumps(output)) + sys.exit(0) + + sys.exit(0) + +if __name__ == "__main__": + main() +``` + +### Приклад 5: Інтелектуальний Stop-хук (на основі промпта) + +```json +{ + "hooks": { + "Stop": [ + { + "hooks": [ + { + "type": "prompt", + "prompt": "Review if Claude completed all requested tasks. Check: 1) Were all files created/modified? 2) Were there unresolved errors? If incomplete, explain what's missing.", + "timeout": 30 + } + ] + } + ] + } +} +``` + +### Приклад 6: Трекер використання контексту (пара хуків) + +Відстеження споживання токенів на запит за допомогою хуків `UserPromptSubmit` (перед повідомленням) та `Stop` (після відповіді). + +**Файл:** `.claude/hooks/context-tracker.py` + +```python +#!/usr/bin/env python3 +""" +Context Usage Tracker — Відстежує споживання токенів на запит. + +Використовує UserPromptSubmit як хук "перед повідомленням" і Stop як хук "після відповіді" +для обчислення дельти використання токенів для кожного запиту. + +Методи підрахунку токенів: +1. Оцінка за символами (за замовчуванням): ~4 символи на токен, без залежностей +2. tiktoken (необовʼязково): Точніший (~90-95%), потребує: pip install tiktoken +""" +import json +import os +import sys +import tempfile + +# Конфігурація +CONTEXT_LIMIT = 128000 # Контекстне вікно Claude (налаштуйте для вашої моделі) +USE_TIKTOKEN = False # Встановіть True, якщо tiktoken встановлено для кращої точності + + +def get_state_file(session_id: str) -> str: + """Отримати шлях до тимчасового файлу для збереження лічильника токенів, ізольовано за сесією.""" + return os.path.join(tempfile.gettempdir(), f"claude-context-{session_id}.json") + + +def count_tokens(text: str) -> int: + """ + Підрахунок токенів у тексті. + + Використовує tiktoken з кодуванням p50k_base, якщо доступно (~90-95% точності), + інакше повертається до оцінки за символами (~80-90% точності). + """ + if USE_TIKTOKEN: + try: + import tiktoken + enc = tiktoken.get_encoding("p50k_base") + return len(enc.encode(text)) + except ImportError: + pass # Повернутися до оцінки + + # Оцінка на основі символів: ~4 символи на токен для англійської + return len(text) // 4 + + +def read_transcript(transcript_path: str) -> str: + """Читання та конкатенація всього вмісту з файлу транскрипту.""" + if not transcript_path or not os.path.exists(transcript_path): + return "" + + content = [] + with open(transcript_path, "r") as f: + for line in f: + try: + entry = json.loads(line.strip()) + # Витяг текстового вмісту з різних форматів повідомлень + if "message" in entry: + msg = entry["message"] + if isinstance(msg.get("content"), str): + content.append(msg["content"]) + elif isinstance(msg.get("content"), list): + for block in msg["content"]: + if isinstance(block, dict) and block.get("type") == "text": + content.append(block.get("text", "")) + except json.JSONDecodeError: + continue + + return "\n".join(content) + + +def handle_user_prompt_submit(data: dict) -> None: + """Хук перед повідомленням: зберегти поточний лічильник токенів перед запитом.""" + session_id = data.get("session_id", "unknown") + transcript_path = data.get("transcript_path", "") + + transcript_content = read_transcript(transcript_path) + current_tokens = count_tokens(transcript_content) + + # Зберегти в тимчасовий файл для подальшого порівняння + state_file = get_state_file(session_id) + with open(state_file, "w") as f: + json.dump({"pre_tokens": current_tokens}, f) + + +def handle_stop(data: dict) -> None: + """Хук після відповіді: обчислити дельту та повідомити про використання.""" + session_id = data.get("session_id", "unknown") + transcript_path = data.get("transcript_path", "") + + transcript_content = read_transcript(transcript_path) + current_tokens = count_tokens(transcript_content) + + # Завантажити лічильник перед повідомленням + state_file = get_state_file(session_id) + pre_tokens = 0 + if os.path.exists(state_file): + try: + with open(state_file, "r") as f: + state = json.load(f) + pre_tokens = state.get("pre_tokens", 0) + except (json.JSONDecodeError, IOError): + pass + + # Обчислити дельту + delta_tokens = current_tokens - pre_tokens + remaining = CONTEXT_LIMIT - current_tokens + percentage = (current_tokens / CONTEXT_LIMIT) * 100 + + # Повідомити про використання + method = "tiktoken" if USE_TIKTOKEN else "estimated" + print(f"Context ({method}): ~{current_tokens:,} tokens ({percentage:.1f}% used, ~{remaining:,} remaining)", file=sys.stderr) + if delta_tokens > 0: + print(f"This request: ~{delta_tokens:,} tokens", file=sys.stderr) + + +def main(): + data = json.load(sys.stdin) + event = data.get("hook_event_name", "") + + if event == "UserPromptSubmit": + handle_user_prompt_submit(data) + elif event == "Stop": + handle_stop(data) + + sys.exit(0) + + +if __name__ == "__main__": + main() +``` + +**Конфігурація:** +```json +{ + "hooks": { + "UserPromptSubmit": [ + { + "hooks": [ + { + "type": "command", + "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/context-tracker.py\"" + } + ] + } + ], + "Stop": [ + { + "hooks": [ + { + "type": "command", + "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/context-tracker.py\"" + } + ] + } + ] + } +} +``` + +**Як це працює:** +1. `UserPromptSubmit` спрацьовує перед обробкою промпта — зберігає поточний лічильник токенів +2. `Stop` спрацьовує після відповіді Claude — обчислює дельту та повідомляє про використання +3. Кожна сесія ізольована через `session_id` в імені тимчасового файлу + +**Методи підрахунку токенів:** + +| Метод | Точність | Залежності | Швидкість | +|-------|----------|------------|-----------| +| Оцінка за символами | ~80-90% | Немає | <1мс | +| tiktoken (p50k_base) | ~90-95% | `pip install tiktoken` | <10мс | + +> **Примітка:** Anthropic не випустили офіційний офлайн-токенізатор. Обидва методи є наближеннями. Транскрипт включає промпти користувача, відповіді Claude та вивід інструментів, але НЕ системні промпти або внутрішній контекст. + +### Приклад 7: Початкове налаштування дозволів Auto-Mode (одноразовий скрипт) + +Одноразовий скрипт налаштування, що додає до `~/.claude/settings.json` ~67 безпечних правил дозволів, еквівалентних базовому набору auto-mode Claude Code — без жодного хука, без запамʼятовування майбутніх виборів. Запустіть один раз; безпечно для повторного запуску (пропускає правила, що вже присутні). + +**Файл:** `09-advanced-features/setup-auto-mode-permissions.py` + +```bash +# Попередній перегляд того, що буде додано +python3 09-advanced-features/setup-auto-mode-permissions.py --dry-run + +# Застосувати +python3 09-advanced-features/setup-auto-mode-permissions.py +``` + +**Що додається:** + +| Категорія | Приклади | +|-----------|---------| +| Вбудовані інструменти | `Read(*)`, `Edit(*)`, `Write(*)`, `Glob(*)`, `Grep(*)`, `Agent(*)`, `WebSearch(*)` | +| Git читання | `Bash(git status:*)`, `Bash(git log:*)`, `Bash(git diff:*)` | +| Git запис (локально) | `Bash(git add:*)`, `Bash(git commit:*)`, `Bash(git checkout:*)` | +| Пакетні менеджери | `Bash(npm install:*)`, `Bash(pip install:*)`, `Bash(cargo build:*)` | +| Збірка та тестування | `Bash(make:*)`, `Bash(pytest:*)`, `Bash(go test:*)` | +| Загальні shell-команди | `Bash(ls:*)`, `Bash(cat:*)`, `Bash(find:*)`, `Bash(cp:*)`, `Bash(mv:*)` | +| GitHub CLI | `Bash(gh pr view:*)`, `Bash(gh pr create:*)`, `Bash(gh issue list:*)` | + +**Що навмисно виключено** (цей скрипт ніколи не додає): +- `rm -rf`, `sudo`, force push, `git reset --hard` +- `DROP TABLE`, `kubectl delete`, `terraform destroy` +- `npm publish`, `curl | bash`, деплої на продакшн + +## Хуки плагінів + +Плагіни можуть включати хуки у файлі `hooks/hooks.json`: + +**Файл:** `plugins/hooks/hooks.json` + +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh" + } + ] + } + ] + } +} +``` + +**Змінні оточення в хуках плагінів:** +- `${CLAUDE_PLUGIN_ROOT}` — шлях до каталогу плагіна +- `${CLAUDE_PLUGIN_DATA}` — шлях до каталогу даних плагіна + +Це дозволяє плагінам включати кастомні хуки валідації та автоматизації. + +## Хуки MCP-інструментів + +MCP-інструменти використовують шаблон `mcp____`: + +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "mcp__memory__.*", + "hooks": [ + { + "type": "command", + "command": "echo '{\"systemMessage\": \"Memory operation logged\"}'" + } + ] + } + ] + } +} +``` + +## Міркування безпеки + +### Застереження + +**ВИКОРИСТОВУЙТЕ НА ВЛАСНИЙ РИЗИК**: Хуки виконують довільні shell-команди. Ви несете повну відповідальність за: +- Команди, які ви налаштовуєте +- Дозволи на доступ/модифікацію файлів +- Потенційну втрату даних або пошкодження системи +- Тестування хуків у безпечних середовищах перед використанням на продакшні + +### Примітки щодо безпеки + +- **Потрібна довіра до робочого простору:** Команди виводу хуків `statusLine` та `fileSuggestion` тепер вимагають прийняття довіри до робочого простору перед набранням чинності. +- **HTTP-хуки та змінні оточення:** HTTP-хуки вимагають явного списку `allowedEnvVars` для використання інтерполяції змінних оточення в URL. Це запобігає випадковому витоку чутливих змінних оточення на віддалені ендпоінти. +- **Ієрархія керованих налаштувань:** Налаштування `disableAllHooks` тепер поважає ієрархію керованих налаштувань, тобто налаштування рівня організації можуть примусово вимкнути хуки, що не може бути перевизначено окремими користувачами. + +### Найкращі практики + +| Рекомендовано | Не рекомендовано | +|-------------|-----------------| +| Валідувати та санітизувати всі вхідні дані | Довіряти вхідним даним сліпо | +| Екранувати змінні shell: `"$VAR"` | Використовувати без лапок: `$VAR` | +| Блокувати обхід шляху (`..`) | Дозволяти довільні шляхи | +| Використовувати абсолютні шляхи з `$CLAUDE_PROJECT_DIR` | Жорстко кодувати шляхи | +| Пропускати чутливі файли (`.env`, `.git/`, ключі) | Обробляти всі файли | +| Тестувати хуки окремо спочатку | Деплоїти неперевірені хуки | +| Використовувати явний `allowedEnvVars` для HTTP-хуків | Відкривати всі змінні оточення для вебхуків | + +## Налагодження + +### Увімкнення режиму налагодження + +Запустіть Claude з прапорцем debug для детальних журналів хуків: + +```bash +claude --debug +``` + +### Verbose-режим + +Використовуйте `Ctrl+O` в Claude Code для увімкнення verbose-режиму та перегляду прогресу виконання хуків. + +### Тестування хуків окремо + +```bash +# Тест із зразковим JSON-вводом +echo '{"tool_name": "Bash", "tool_input": {"command": "ls -la"}}' | python3 .claude/hooks/validate-bash.py + +# Перевірка коду виходу +echo $? +``` + +## Повний приклад конфігурації + +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/validate-bash.py\"", + "timeout": 10 + } + ] + } + ], + "PostToolUse": [ + { + "matcher": "Write|Edit", + "hooks": [ + { + "type": "command", + "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/format-code.sh\"", + "timeout": 30 + }, + { + "type": "command", + "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/security-scan.py\"", + "timeout": 10 + } + ] + } + ], + "UserPromptSubmit": [ + { + "hooks": [ + { + "type": "command", + "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/validate-prompt.py\"" + } + ] + } + ], + "SessionStart": [ + { + "matcher": "startup", + "hooks": [ + { + "type": "command", + "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/session-init.sh\"" + } + ] + } + ], + "Stop": [ + { + "hooks": [ + { + "type": "prompt", + "prompt": "Verify all tasks are complete before stopping.", + "timeout": 30 + } + ] + } + ] + } +} +``` + +## Деталі виконання хуків + +| Аспект | Поведінка | +|--------|----------| +| **Таймаут** | 60 секунд за замовчуванням, налаштовується для кожної команди | +| **Паралелізація** | Усі відповідні хуки запускаються паралельно | +| **Дедуплікація** | Ідентичні команди хуків дедуплікуються | +| **Середовище** | Запускається в поточному каталозі з середовищем Claude Code | + +## Усунення несправностей + +### Хук не виконується +- Перевірте правильність синтаксису JSON-конфігурації +- Переконайтеся, що шаблон matcher відповідає назві інструмента +- Перевірте існування та виконуваність скрипта: `chmod +x script.sh` +- Запустіть `claude --debug` для перегляду журналів виконання хуків +- Переконайтеся, що хук читає JSON з stdin (не з аргументів команди) + +### Хук блокує несподівано +- Тестуйте хук зі зразковим JSON: `echo '{"tool_name": "Write", ...}' | ./hook.py` +- Перевірте код виходу: має бути 0 для дозволу, 2 для блокування +- Перевірте вивід stderr (показується при коді виходу 2) + +### Помилки парсингу JSON +- Завжди читайте з stdin, не з аргументів команди +- Використовуйте належний парсинг JSON (не маніпуляцію рядками) +- Обробляйте відсутні поля коректно + +## Встановлення + +### Крок 1: Створення каталогу хуків +```bash +mkdir -p ~/.claude/hooks +``` + +### Крок 2: Копіювання прикладів хуків +```bash +cp 06-hooks/*.sh ~/.claude/hooks/ +chmod +x ~/.claude/hooks/*.sh +``` + +### Крок 3: Налаштування у settings +Відредагуйте `~/.claude/settings.json` або `.claude/settings.json` з конфігурацією хуків, показаною вище. + +## Повʼязані концепції + +- **[Контрольні точки та відкат](../08-checkpoints/)** — збереження та відновлення стану розмови +- **[Слеш-команди](../01-slash-commands/)** — створення кастомних слеш-команд +- **[Навички](../03-skills/)** — повторно використовувані автономні можливості +- **[Субагенти](../04-subagents/)** — делеговане виконання завдань +- **[Плагіни](../07-plugins/)** — обʼєднані пакети розширень +- **[Розширені функції](../09-advanced-features/)** — дослідження розширених можливостей Claude Code + +## Додаткові ресурси + +- **[Офіційна документація хуків](https://code.claude.com/docs/en/hooks)** — повний довідник хуків +- **[Довідник CLI](https://code.claude.com/docs/en/cli-reference)** — документація інтерфейсу командного рядка +- **[Посібник з памʼяті](../02-memory/)** — конфігурація постійного контексту + +--- +**Останнє оновлення**: 9 квітня 2026 +**Версія Claude Code**: 2.1.97 +**Сумісні моделі**: Claude Sonnet 4.6, Claude Opus 4.6, Claude Haiku 4.5 diff --git a/uk/07-plugins/README.md b/uk/07-plugins/README.md new file mode 100644 index 0000000..1942d25 --- /dev/null +++ b/uk/07-plugins/README.md @@ -0,0 +1,953 @@ + + + + + + + Claude How To + + +# Плагіни Claude Code + +Ця папка містить повні приклади плагінів, які обʼєднують кілька функцій Claude Code у цілісні пакети, що встановлюються однією командою. + +## Огляд + +Плагіни Claude Code — це обʼєднані колекції кастомізацій (слеш-команди, субагенти, MCP-сервери та хуки), які встановлюються однією командою. Вони є механізмом розширення найвищого рівня — поєднуючи кілька функцій у цілісні пакети, якими можна ділитися. + +## Архітектура плагінів + +```mermaid +graph TB + A["Plugin"] + B["Slash Commands"] + C["Subagents"] + D["MCP Servers"] + E["Hooks"] + F["Configuration"] + + A -->|bundles| B + A -->|bundles| C + A -->|bundles| D + A -->|bundles| E + A -->|bundles| F +``` + +## Процес завантаження плагіна + +```mermaid +sequenceDiagram + participant User + participant Claude as Claude Code + participant Plugin as Plugin Marketplace + participant Install as Installation + participant SlashCmds as Slash Commands + participant Subagents + participant MCPServers as MCP Servers + participant Hooks + participant Tools as Configured Tools + + User->>Claude: /plugin install pr-review + Claude->>Plugin: Download plugin manifest + Plugin-->>Claude: Return plugin definition + Claude->>Install: Extract components + Install->>SlashCmds: Configure + Install->>Subagents: Configure + Install->>MCPServers: Configure + Install->>Hooks: Configure + SlashCmds-->>Tools: Ready to use + Subagents-->>Tools: Ready to use + MCPServers-->>Tools: Ready to use + Hooks-->>Tools: Ready to use + Tools-->>Claude: Plugin installed ✅ +``` + +## Типи та дистрибуція плагінів + +| Тип | Область | Спільний | Авторитет | Приклади | +|-----|---------|----------|-----------|----------| +| Офіційний | Глобальний | Усі користувачі | Anthropic | PR Review, Security Guidance | +| Спільнота | Публічний | Усі користувачі | Спільнота | DevOps, Data Science | +| Організація | Внутрішній | Члени команди | Компанія | Внутрішні стандарти, інструменти | +| Персональний | Індивідуальний | Один користувач | Розробник | Кастомні робочі процеси | + +## Структура визначення плагіна + +Маніфест плагіна використовує формат JSON у файлі `.claude-plugin/plugin.json`: + +```json +{ + "name": "my-first-plugin", + "description": "A greeting plugin", + "version": "1.0.0", + "author": { + "name": "Your Name" + }, + "homepage": "https://example.com", + "repository": "https://github.com/user/repo", + "license": "MIT" +} +``` + +## Приклад структури плагіна + +``` +my-plugin/ +├── .claude-plugin/ +│ └── plugin.json # Маніфест (назва, опис, версія, автор) +├── commands/ # Навички як Markdown-файли +│ ├── task-1.md +│ ├── task-2.md +│ └── workflows/ +├── agents/ # Визначення кастомних агентів +│ ├── specialist-1.md +│ ├── specialist-2.md +│ └── configs/ +├── skills/ # Навички агентів з файлами SKILL.md +│ ├── skill-1.md +│ └── skill-2.md +├── hooks/ # Обробники подій у hooks.json +│ └── hooks.json +├── .mcp.json # Конфігурації MCP-серверів +├── .lsp.json # Конфігурації LSP-серверів для інтелектуальної роботи з кодом +├── bin/ # Виконувані файли, додані до PATH інструменту Bash поки плагін увімкнено +├── settings.json # Стандартні налаштування при увімкненні плагіна (наразі підтримується лише ключ `agent`) +├── templates/ +│ └── issue-template.md +├── scripts/ +│ ├── helper-1.sh +│ └── helper-2.py +├── docs/ +│ ├── README.md +│ └── USAGE.md +└── tests/ + └── plugin.test.js +``` + +### Конфігурація LSP-сервера + +Плагіни можуть включати підтримку Language Server Protocol (LSP — протокол мовного сервера) для інтелектуальної роботи з кодом у реальному часі. LSP-сервери надають діагностику, навігацію по коду та інформацію про символи під час роботи. + +**Розташування конфігурації**: +- Файл `.lsp.json` у кореневому каталозі плагіна +- Інлайн-ключ `lsp` у `plugin.json` + +#### Довідник полів + +| Поле | Обовʼязкове | Опис | +|------|-------------|------| +| `command` | Так | Бінарний файл LSP-сервера (має бути в PATH) | +| `extensionToLanguage` | Так | Відповідність розширень файлів ідентифікаторам мов | +| `args` | Ні | Аргументи командного рядка для сервера | +| `transport` | Ні | Метод комунікації: `stdio` (за замовчуванням) або `socket` | +| `env` | Ні | Змінні оточення для процесу сервера | +| `initializationOptions` | Ні | Опції, що надсилаються під час ініціалізації LSP | +| `settings` | Ні | Конфігурація робочого простору, що передається серверу | +| `workspaceFolder` | Ні | Перевизначення шляху до папки робочого простору | +| `startupTimeout` | Ні | Максимальний час (мс) очікування запуску сервера | +| `shutdownTimeout` | Ні | Максимальний час (мс) для коректного завершення | +| `restartOnCrash` | Ні | Автоматичний перезапуск при збої сервера | +| `maxRestarts` | Ні | Максимальна кількість спроб перезапуску | + +#### Приклади конфігурацій + +**Go (gopls)**: + +```json +{ + "go": { + "command": "gopls", + "args": ["serve"], + "extensionToLanguage": { + ".go": "go" + } + } +} +``` + +**Python (pyright)**: + +```json +{ + "python": { + "command": "pyright-langserver", + "args": ["--stdio"], + "extensionToLanguage": { + ".py": "python", + ".pyi": "python" + } + } +} +``` + +**TypeScript**: + +```json +{ + "typescript": { + "command": "typescript-language-server", + "args": ["--stdio"], + "extensionToLanguage": { + ".ts": "typescript", + ".tsx": "typescriptreact", + ".js": "javascript", + ".jsx": "javascriptreact" + } + } +} +``` + +#### Доступні LSP-плагіни + +Офіційний маркетплейс включає попередньо налаштовані LSP-плагіни: + +| Плагін | Мова | Бінарний файл сервера | Команда встановлення | +|--------|------|----------------------|---------------------| +| `pyright-lsp` | Python | `pyright-langserver` | `pip install pyright` | +| `typescript-lsp` | TypeScript/JavaScript | `typescript-language-server` | `npm install -g typescript-language-server typescript` | +| `rust-lsp` | Rust | `rust-analyzer` | Встановлення через `rustup component add rust-analyzer` | + +#### Можливості LSP + +Після налаштування LSP-сервери надають: + +- **Миттєва діагностика** — помилки та попередження зʼявляються одразу після редагування +- **Навігація по коду** — перехід до визначення, пошук посилань, реалізацій +- **Інформація при наведенні** — сигнатури типів та документація при наведенні курсора +- **Список символів** — перегляд символів у поточному файлі або робочому просторі + +## Опції плагіна (v2.1.83+) + +Плагіни можуть оголошувати користувацькі опції в маніфесті через `userConfig`. Значення з позначкою `sensitive: true` зберігаються у системному сховищі ключів (keychain), а не в текстових файлах налаштувань: + +```json +{ + "name": "my-plugin", + "version": "1.0.0", + "userConfig": { + "apiKey": { + "description": "API key for the service", + "sensitive": true + }, + "region": { + "description": "Deployment region", + "default": "us-east-1" + } + } +} +``` + +## Постійні дані плагіна (`${CLAUDE_PLUGIN_DATA}`) (v2.1.78+) + +Плагіни мають доступ до каталогу постійного стану через змінну оточення `${CLAUDE_PLUGIN_DATA}`. Цей каталог є унікальним для кожного плагіна та зберігається між сесіями, що робить його придатним для кешів, баз даних та іншого постійного стану: + +```json +{ + "hooks": { + "PostToolUse": [ + { + "command": "node ${CLAUDE_PLUGIN_DATA}/track-usage.js" + } + ] + } +} +``` + +Каталог створюється автоматично при встановленні плагіна. Файли зберігаються до видалення плагіна. + +## Інлайн-плагін через налаштування (`source: 'settings'`) (v2.1.80+) + +Плагіни можна визначати інлайн у файлах налаштувань як записи маркетплейсу з полем `source: 'settings'`. Це дозволяє вбудовувати визначення плагіна безпосередньо, без окремого репозиторію або маркетплейсу: + +```json +{ + "pluginMarketplaces": [ + { + "name": "inline-tools", + "source": "settings", + "plugins": [ + { + "name": "quick-lint", + "source": "./local-plugins/quick-lint" + } + ] + } + ] +} +``` + +## Налаштування плагіна + +Плагіни можуть постачатися з файлом `settings.json` для стандартної конфігурації. Наразі підтримується ключ `agent`, який встановлює основного агента потоку для плагіна: + +```json +{ + "agent": "agents/specialist-1.md" +} +``` + +Коли плагін включає `settings.json`, його стандартні значення застосовуються при встановленні. Користувачі можуть перевизначити ці налаштування у своїй конфігурації проєкту або користувача. + +## Автономний vs плагін-підхід + +| Підхід | Назви команд | Конфігурація | Найкраще для | +|--------|-------------|--------------|--------------| +| **Автономний** | `/hello` | Ручне налаштування в CLAUDE.md | Персональне, специфічне для проєкту | +| **Плагіни** | `/plugin-name:hello` | Автоматичне через plugin.json | Поширення, дистрибуція, командна робота | + +Використовуйте **автономні слеш-команди** для швидких персональних робочих процесів. Використовуйте **плагіни**, коли хочете обʼєднати кілька функцій, поділитися з командою або опублікувати для дистрибуції. + +## Практичні приклади + +### Приклад 1: Плагін PR Review + +**Файл:** `.claude-plugin/plugin.json` + +```json +{ + "name": "pr-review", + "version": "1.0.0", + "description": "Complete PR review workflow with security, testing, and docs", + "author": { + "name": "Anthropic" + }, + "repository": "https://github.com/your-org/pr-review", + "license": "MIT" +} +``` + +**Файл:** `commands/review-pr.md` + +```markdown +--- +name: Review PR +description: Start comprehensive PR review with security and testing checks +--- + +# PR Review + +This command initiates a complete pull request review including: + +1. Security analysis +2. Test coverage verification +3. Documentation updates +4. Code quality checks +5. Performance impact assessment +``` + +**Файл:** `agents/security-reviewer.md` + +```yaml +--- +name: security-reviewer +description: Security-focused code review +tools: read, grep, diff +--- + +# Security Reviewer + +Specializes in finding security vulnerabilities: +- Authentication/authorization issues +- Data exposure +- Injection attacks +- Secure configuration +``` + +**Встановлення:** + +```bash +/plugin install pr-review + +# Результат: +# ✅ 3 слеш-команди встановлено +# ✅ 3 субагенти налаштовано +# ✅ 2 MCP-сервери підключено +# ✅ 4 хуки зареєстровано +# ✅ Готово до використання! +``` + +### Приклад 2: Плагін DevOps + +**Компоненти:** + +``` +devops-automation/ +├── commands/ +│ ├── deploy.md +│ ├── rollback.md +│ ├── status.md +│ └── incident.md +├── agents/ +│ ├── deployment-specialist.md +│ ├── incident-commander.md +│ └── alert-analyzer.md +├── mcp/ +│ ├── github-config.json +│ ├── kubernetes-config.json +│ └── prometheus-config.json +├── hooks/ +│ ├── pre-deploy.js +│ ├── post-deploy.js +│ └── on-error.js +└── scripts/ + ├── deploy.sh + ├── rollback.sh + └── health-check.sh +``` + +### Приклад 3: Плагін документації + +**Обʼєднані компоненти:** + +``` +documentation/ +├── commands/ +│ ├── generate-api-docs.md +│ ├── generate-readme.md +│ ├── sync-docs.md +│ └── validate-docs.md +├── agents/ +│ ├── api-documenter.md +│ ├── code-commentator.md +│ └── example-generator.md +├── mcp/ +│ ├── github-docs-config.json +│ └── slack-announce-config.json +└── templates/ + ├── api-endpoint.md + ├── function-docs.md + └── adr-template.md +``` + +## Маркетплейс плагінів + +Офіційний каталог плагінів, керований Anthropic — `anthropics/claude-plugins-official`. Адміністратори підприємств також можуть створювати приватні маркетплейси для внутрішньої дистрибуції. + +```mermaid +graph TB + A["Plugin Marketplace"] + B["Official
anthropics/claude-plugins-official"] + C["Community
Marketplace"] + D["Enterprise
Private Registry"] + + A --> B + A --> C + A --> D + + B -->|Categories| B1["Development"] + B -->|Categories| B2["DevOps"] + B -->|Categories| B3["Documentation"] + + C -->|Search| C1["DevOps Automation"] + C -->|Search| C2["Mobile Dev"] + C -->|Search| C3["Data Science"] + + D -->|Internal| D1["Company Standards"] + D -->|Internal| D2["Legacy Systems"] + D -->|Internal| D3["Compliance"] + + style A fill:#e1f5fe,stroke:#333,color:#333 + style B fill:#e8f5e9,stroke:#333,color:#333 + style C fill:#f3e5f5,stroke:#333,color:#333 + style D fill:#fff3e0,stroke:#333,color:#333 +``` + +### Конфігурація маркетплейсу + +Підприємства та просунуті користувачі можуть контролювати поведінку маркетплейсу через налаштування: + +| Налаштування | Опис | +|-------------|------| +| `extraKnownMarketplaces` | Додати додаткові джерела маркетплейсу крім стандартних | +| `strictKnownMarketplaces` | Контролювати, які маркетплейси дозволено додавати користувачам | +| `deniedPlugins` | Блок-список для запобігання встановленню конкретних плагінів (керований адміністратором) | + +### Додаткові функції маркетплейсу + +- **Стандартний таймаут git**: Збільшено з 30с до 120с для великих репозиторіїв плагінів +- **Кастомні npm-реєстри**: Плагіни можуть вказувати URL кастомних npm-реєстрів для розвʼязання залежностей +- **Фіксація версій**: Закріплення плагінів за конкретними версіями для відтворюваних середовищ + +### Схема визначення маркетплейсу + +Маркетплейси плагінів визначаються у `.claude-plugin/marketplace.json`: + +```json +{ + "name": "my-team-plugins", + "owner": "my-org", + "plugins": [ + { + "name": "code-standards", + "source": "./plugins/code-standards", + "description": "Enforce team coding standards", + "version": "1.2.0", + "author": "platform-team" + }, + { + "name": "deploy-helper", + "source": { + "source": "github", + "repo": "my-org/deploy-helper", + "ref": "v2.0.0" + }, + "description": "Deployment automation workflows" + } + ] +} +``` + +| Поле | Обовʼязкове | Опис | +|------|-------------|------| +| `name` | Так | Назва маркетплейсу в kebab-case | +| `owner` | Так | Організація або користувач, що підтримує маркетплейс | +| `plugins` | Так | Масив записів плагінів | +| `plugins[].name` | Так | Назва плагіна (kebab-case) | +| `plugins[].source` | Так | Джерело плагіна (рядок шляху або обʼєкт джерела) | +| `plugins[].description` | Ні | Короткий опис плагіна | +| `plugins[].version` | Ні | Рядок семантичної версії | +| `plugins[].author` | Ні | Імʼя автора плагіна | + +### Типи джерел плагінів + +Плагіни можуть завантажуватися з кількох місць: + +| Джерело | Синтаксис | Приклад | +|---------|-----------|---------| +| **Відносний шлях** | Рядок шляху | `"./plugins/my-plugin"` | +| **GitHub** | `{ "source": "github", "repo": "owner/repo" }` | `{ "source": "github", "repo": "acme/lint-plugin", "ref": "v1.0" }` | +| **Git URL** | `{ "source": "url", "url": "..." }` | `{ "source": "url", "url": "https://git.internal/plugin.git" }` | +| **Підкаталог Git** | `{ "source": "git-subdir", "url": "...", "path": "..." }` | `{ "source": "git-subdir", "url": "https://github.com/org/monorepo.git", "path": "packages/plugin" }` | +| **npm** | `{ "source": "npm", "package": "..." }` | `{ "source": "npm", "package": "@acme/claude-plugin", "version": "^2.0" }` | +| **pip** | `{ "source": "pip", "package": "..." }` | `{ "source": "pip", "package": "claude-data-plugin", "version": ">=1.0" }` | + +Джерела GitHub та git підтримують необовʼязкові поля `ref` (гілка/тег) та `sha` (хеш коміту) для фіксації версій. + +### Методи дистрибуції + +**GitHub (рекомендовано)**: +```bash +# Користувачі додають ваш маркетплейс +/plugin marketplace add owner/repo-name +``` + +**Інші git-сервіси** (потрібен повний URL): +```bash +/plugin marketplace add https://gitlab.com/org/marketplace-repo.git +``` + +**Приватні репозиторії**: Підтримуються через git credential helpers або токени оточення. Користувачі повинні мати доступ на читання до репозиторію. + +**Подання до офіційного маркетплейсу**: Подавайте плагіни до курованого Anthropic маркетплейсу для ширшої дистрибуції через [claude.ai/settings/plugins/submit](https://claude.ai/settings/plugins/submit) або [platform.claude.com/plugins/submit](https://platform.claude.com/plugins/submit). + +### Суворий режим (strict mode) + +Контроль взаємодії визначень маркетплейсу з локальними файлами `plugin.json`: + +| Налаштування | Поведінка | +|-------------|----------| +| `strict: true` (за замовчуванням) | Локальний `plugin.json` є авторитетним; запис маркетплейсу доповнює його | +| `strict: false` | Запис маркетплейсу є повним визначенням плагіна | + +**Обмеження організації** через `strictKnownMarketplaces`: + +| Значення | Ефект | +|----------|-------| +| Не встановлено | Без обмежень — користувачі можуть додавати будь-який маркетплейс | +| Порожній масив `[]` | Блокування — маркетплейси заборонені | +| Масив патернів | Білий список — дозволено лише маркетплейси, що відповідають патернам | + +```json +{ + "strictKnownMarketplaces": [ + "my-org/*", + "github.com/trusted-vendor/*" + ] +} +``` + +> **Увага**: У суворому режимі з `strictKnownMarketplaces` користувачі можуть встановлювати плагіни лише з маркетплейсів білого списку. Це корисно для корпоративних середовищ, що вимагають контрольованої дистрибуції плагінів. + +## Встановлення та життєвий цикл плагіна + +```mermaid +graph LR + A["Discover"] -->|Browse| B["Marketplace"] + B -->|Select| C["Plugin Page"] + C -->|View| D["Components"] + D -->|Install| E["/plugin install"] + E -->|Extract| F["Configure"] + F -->|Activate| G["Use"] + G -->|Check| H["Update"] + H -->|Available| G + G -->|Done| I["Disable"] + I -->|Later| J["Enable"] + J -->|Back| G +``` + +## Порівняння функцій плагінів + +| Функція | Слеш-команда | Навичка | Субагент | Плагін | +|---------|-------------|---------|----------|--------| +| **Встановлення** | Ручне копіювання | Ручне копіювання | Ручна конфігурація | Одна команда | +| **Час налаштування** | 5 хвилин | 10 хвилин | 15 хвилин | 2 хвилини | +| **Обʼєднання** | Один файл | Один файл | Один файл | Кілька | +| **Версіонування** | Ручне | Ручне | Ручне | Автоматичне | +| **Поширення в команді** | Копіювання файлу | Копіювання файлу | Копіювання файлу | ID встановлення | +| **Оновлення** | Ручне | Ручне | Ручне | Автоматично доступне | +| **Залежності** | Немає | Немає | Немає | Можуть включати | +| **Маркетплейс** | Ні | Ні | Ні | Так | +| **Дистрибуція** | Репозиторій | Репозиторій | Репозиторій | Маркетплейс | + +## CLI-команди плагінів + +Усі операції з плагінами доступні як CLI-команди: + +```bash +claude plugin install @ # Встановити з маркетплейсу +claude plugin uninstall # Видалити плагін +claude plugin list # Список встановлених плагінів +claude plugin enable # Увімкнути вимкнений плагін +claude plugin disable # Вимкнути плагін +claude plugin validate # Валідація структури плагіна +``` + +## Методи встановлення + +### З маркетплейсу +```bash +/plugin install plugin-name +# або з CLI: +claude plugin install plugin-name@marketplace-name +``` + +### Увімкнення / Вимкнення (з автовизначенням області) +```bash +/plugin enable plugin-name +/plugin disable plugin-name +``` + +### Локальний плагін (для розробки) +```bash +# CLI-прапорець для локального тестування (повторюваний для кількох плагінів) +claude --plugin-dir ./path/to/plugin +claude --plugin-dir ./plugin-a --plugin-dir ./plugin-b +``` + +### З Git-репозиторію +```bash +/plugin install github:username/repo +``` + +## Коли створювати плагін + +```mermaid +graph TD + A["Should I create a plugin?"] + A -->|Need multiple components| B{"Multiple commands
or subagents
or MCPs?"} + B -->|Yes| C["✅ Create Plugin"] + B -->|No| D["Use Individual Feature"] + A -->|Team workflow| E{"Share with
team?"} + E -->|Yes| C + E -->|No| F["Keep as Local Setup"] + A -->|Complex setup| G{"Needs auto
configuration?"} + G -->|Yes| C + G -->|No| D +``` + +### Випадки використання плагінів + +| Випадок | Рекомендація | Чому | +|---------|-------------|------| +| **Онбординг команди** | ✅ Плагін | Миттєве налаштування, усі конфігурації | +| **Налаштування фреймворку** | ✅ Плагін | Обʼєднує команди, специфічні для фреймворку | +| **Корпоративні стандарти** | ✅ Плагін | Централізована дистрибуція, контроль версій | +| **Швидка автоматизація** | ❌ Команда | Надмірна складність | +| **Одна предметна область** | ❌ Навичка | Занадто важко, використовуйте навичку | +| **Спеціалізований аналіз** | ❌ Субагент | Створіть вручну або використовуйте навичку | +| **Доступ до живих даних** | ❌ MCP | Автономний, не обʼєднуйте | + +## Тестування плагіна + +Перед публікацією протестуйте плагін локально за допомогою CLI-прапорця `--plugin-dir` (повторюваний для кількох плагінів): + +```bash +claude --plugin-dir ./my-plugin +claude --plugin-dir ./my-plugin --plugin-dir ./another-plugin +``` + +Це запускає Claude Code з завантаженим плагіном, дозволяючи: +- Перевірити доступність усіх слеш-команд +- Протестувати коректну роботу субагентів та агентів +- Підтвердити правильне підключення MCP-серверів +- Валідувати виконання хуків +- Перевірити конфігурації LSP-серверів +- Виявити помилки конфігурації + +## Гаряче перезавантаження (Hot-Reload) + +Плагіни підтримують гаряче перезавантаження під час розробки. При зміні файлів плагіна Claude Code може автоматично виявляти зміни. Також можна примусово перезавантажити командою: + +```bash +/reload-plugins +``` + +Це повторно зчитує всі маніфести плагінів, команди, агентів, навички, хуки та конфігурації MCP/LSP без перезапуску сесії. + +## Керовані налаштування для плагінів + +Адміністратори можуть контролювати поведінку плагінів в організації через керовані налаштування (managed settings): + +| Налаштування | Опис | +|-------------|------| +| `enabledPlugins` | Білий список плагінів, увімкнених за замовчуванням | +| `deniedPlugins` | Блок-список плагінів, які не можна встановити | +| `extraKnownMarketplaces` | Додаткові джерела маркетплейсу крім стандартних | +| `strictKnownMarketplaces` | Обмеження маркетплейсів, які дозволено додавати користувачам | +| `allowedChannelPlugins` | Контроль дозволених плагінів для кожного каналу випуску | + +Ці налаштування можна застосувати на рівні організації через файли керованої конфігурації, і вони мають пріоритет над налаштуваннями рівня користувача. + +## Безпека плагінів + +Субагенти плагінів працюють в обмеженій пісочниці (sandbox). Наступні ключі frontmatter **заборонені** у визначеннях субагентів плагінів: + +- `hooks` — субагенти не можуть реєструвати обробники подій +- `mcpServers` — субагенти не можуть налаштовувати MCP-сервери +- `permissionMode` — субагенти не можуть перевизначати модель дозволів + +Це гарантує, що плагіни не можуть підвищити привілеї або модифікувати хост-середовище за межами оголошеної області. + +## Публікація плагіна + +**Кроки для публікації:** + +1. Створити структуру плагіна з усіма компонентами +2. Написати маніфест `.claude-plugin/plugin.json` +3. Створити `README.md` з документацією +4. Протестувати локально за допомогою `claude --plugin-dir ./my-plugin` +5. Подати до маркетплейсу плагінів +6. Пройти перевірку та затвердження +7. Публікація в маркетплейсі +8. Користувачі можуть встановити однією командою + +**Приклад подання:** + +```markdown +# PR Review Plugin + +## Description +Complete PR review workflow with security, testing, and documentation checks. + +## What's Included +- 3 slash commands for different review types +- 3 specialized subagents +- GitHub and CodeQL MCP integration +- Automated security scanning hooks + +## Installation +```bash +/plugin install pr-review +``` + +## Features +✅ Security analysis +✅ Test coverage checking +✅ Documentation verification +✅ Code quality assessment +✅ Performance impact analysis + +## Usage +```bash +/review-pr +/check-security +/check-tests +``` + +## Requirements +- Claude Code 1.0+ +- GitHub access +- CodeQL (optional) +``` + +## Плагін vs ручна конфігурація + +**Ручне налаштування (2+ години):** +- Встановити слеш-команди одну за одною +- Створити субагентів окремо +- Налаштувати MCP окремо +- Встановити хуки вручну +- Задокументувати все +- Поширити в команді (сподіватися, що налаштують правильно) + +**З плагіном (2 хвилини):** +```bash +/plugin install pr-review +# ✅ Все встановлено та налаштовано +# ✅ Готово до використання одразу +# ✅ Команда може відтворити точну конфігурацію +``` + +## Найкращі практики + +### Рекомендовано ✅ +- Використовуйте зрозумілі, описові назви плагінів +- Включайте вичерпний README +- Версіонуйте плагін правильно (semver — семантичне версіонування) +- Тестуйте всі компоненти разом +- Документуйте вимоги чітко +- Надавайте приклади використання +- Включайте обробку помилок +- Тегуйте належним чином для виявлення +- Підтримуйте зворотну сумісність +- Тримайте плагіни зосередженими та цілісними +- Включайте вичерпні тести +- Документуйте всі залежності + +### Не рекомендовано ❌ +- Не обʼєднуйте неповʼязані функції +- Не зашивайте облікові дані в код +- Не пропускайте тестування +- Не забувайте про документацію +- Не створюйте надлишкових плагінів +- Не ігноруйте версіонування +- Не ускладнюйте залежності компонентів +- Не забувайте обробляти помилки коректно + +## Інструкції зі встановлення + +### Встановлення з маркетплейсу + +1. **Перегляд доступних плагінів:** + ```bash + /plugin list + ``` + +2. **Деталі плагіна:** + ```bash + /plugin info plugin-name + ``` + +3. **Встановлення плагіна:** + ```bash + /plugin install plugin-name + ``` + +### Встановлення з локального шляху + +```bash +/plugin install ./path/to/plugin-directory +``` + +### Встановлення з GitHub + +```bash +/plugin install github:username/repo +``` + +### Список встановлених плагінів + +```bash +/plugin list --installed +``` + +### Оновлення плагіна + +```bash +/plugin update plugin-name +``` + +### Вимкнення/Увімкнення плагіна + +```bash +# Тимчасове вимкнення +/plugin disable plugin-name + +# Повторне увімкнення +/plugin enable plugin-name +``` + +### Видалення плагіна + +```bash +/plugin uninstall plugin-name +``` + +## Повʼязані концепції + +Наступні функції Claude Code працюють разом з плагінами: + +- **[Слеш-команди](../01-slash-commands/)** — окремі команди, обʼєднані в плагіни +- **[Памʼять](../02-memory/)** — постійний контекст для плагінів +- **[Навички](../03-skills/)** — предметна експертиза, яку можна обгорнути в плагіни +- **[Субагенти](../04-subagents/)** — спеціалізовані агенти як компоненти плагінів +- **[MCP-сервери](../05-mcp/)** — інтеграції Model Context Protocol, обʼєднані в плагіни +- **[Хуки](../06-hooks/)** — обробники подій, що запускають робочі процеси плагінів + +## Повний приклад робочого процесу + +### Повний робочий процес плагіна PR Review + +``` +1. Користувач: /review-pr + +2. Плагін виконує: + ├── pre-review.js хук валідує git-репо + ├── GitHub MCP отримує дані PR + ├── security-reviewer субагент аналізує безпеку + ├── test-checker субагент перевіряє покриття + └── performance-analyzer субагент перевіряє продуктивність + +3. Результати синтезуються та представляються: + ✅ Безпека: Критичних проблем не виявлено + ⚠️ Тестування: Покриття 65% (рекомендовано 80%+) + ✅ Продуктивність: Значного впливу немає + 📝 Надано 12 рекомендацій +``` + +## Усунення несправностей + +### Плагін не встановлюється +- Перевірте сумісність версії Claude Code: `/version` +- Перевірте синтаксис `plugin.json` валідатором JSON +- Перевірте підключення до інтернету (для віддалених плагінів) +- Перевірте дозволи: `ls -la plugin/` + +### Компоненти не завантажуються +- Переконайтеся, що шляхи в `plugin.json` відповідають фактичній структурі каталогів +- Перевірте дозволи файлів: `chmod +x scripts/` +- Перегляньте синтаксис файлів компонентів +- Перевірте журнали: `/plugin debug plugin-name` + +### Збій підключення MCP +- Переконайтеся, що змінні оточення встановлені правильно +- Перевірте встановлення та працездатність MCP-сервера +- Протестуйте підключення MCP окремо за допомогою `/mcp test` +- Перегляньте конфігурацію MCP у каталозі `mcp/` + +### Команди недоступні після встановлення +- Переконайтеся, що плагін встановлено успішно: `/plugin list --installed` +- Перевірте, чи плагін увімкнено: `/plugin status plugin-name` +- Перезапустіть Claude Code: `exit` та відкрийте знову +- Перевірте конфлікти назв з існуючими командами + +### Проблеми з виконанням хуків +- Переконайтеся, що файли хуків мають правильні дозволи +- Перевірте синтаксис хуків та назви подій +- Перегляньте журнали хуків для деталей помилок +- Протестуйте хуки вручну, якщо можливо + +## Додаткові ресурси + +- [Офіційна документація плагінів](https://code.claude.com/docs/en/plugins) +- [Каталог плагінів](https://code.claude.com/docs/en/discover-plugins) +- [Маркетплейси плагінів](https://code.claude.com/docs/en/plugin-marketplaces) +- [Довідник плагінів](https://code.claude.com/docs/en/plugins-reference) +- [Довідник MCP-серверів](https://modelcontextprotocol.io/) +- [Посібник конфігурації субагентів](../04-subagents/README.md) +- [Довідник системи хуків](../06-hooks/README.md) + +--- +**Останнє оновлення**: 9 квітня 2026 +**Версія Claude Code**: 2.1.97 +**Сумісні моделі**: Claude Sonnet 4.6, Claude Opus 4.6, Claude Haiku 4.5 diff --git a/uk/09-advanced-features/README.md b/uk/09-advanced-features/README.md new file mode 100644 index 0000000..5705faf --- /dev/null +++ b/uk/09-advanced-features/README.md @@ -0,0 +1,1945 @@ + + + Claude How To + + +# Розширені функції + +Повний посібник з розширених можливостей Claude Code, включаючи режим планування, розширене мислення, автоматичний режим, фонові завдання, режими дозволів, режим друку (неінтерактивний), управління сесіями, інтерактивні функції, канали, голосовий ввід, дистанційне керування, веб-сесії, десктопний додаток, список завдань, підказки промптів, git worktrees, пісочницю, керовані налаштування та конфігурацію. + +## Зміст + +1. [Огляд](#огляд) +2. [Режим планування](#режим-планування) +3. [Розширене мислення](#розширене-мислення) +4. [Auto Mode](#auto-mode) +5. [Фонові завдання](#фонові-завдання) +6. [Заплановані завдання](#заплановані-завдання) +7. [Режими дозволів](#режими-дозволів) +8. [Headless Mode](#headless-mode) +9. [Управління сесіями](#управління-сесіями) +10. [Інтерактивні функції](#інтерактивні-функції) +11. [Голосовий ввід](#голосовий-ввід) +12. [Канали](#канали) +13. [Інтеграція Chrome](#інтеграція-chrome) +14. [Remote Control](#remote-control) +15. [Веб-сесії](#веб-сесії) +16. [Десктопний додаток](#десктопний-додаток) +17. [Список завдань](#список-завдань) +18. [Підказки промптів](#підказки-промптів) +19. [Git Worktrees](#git-worktrees) +20. [Пісочниця](#пісочниця) +21. [Керовані налаштування (Enterprise)](#керовані-налаштування-enterprise) +22. [Конфігурація та налаштування](#конфігурація-та-налаштування) +23. [Agent Teams](#agent-teams) +24. [Найкращі практики](#найкращі-практики) +25. [Додаткові ресурси](#додаткові-ресурси) + +--- + +## Огляд + +Розширені функції Claude Code доповнюють базові можливості плануванням, міркуванням, автоматизацією та механізмами контролю. Ці функції забезпечують складні робочі процеси для комплексних завдань розробки, ревʼю коду, автоматизації та управління кількома сесіями. + +**Ключові розширені функції:** +- **Режим планування**: Створення детальних планів реалізації перед кодуванням +- **Розширене мислення**: Глибоке міркування для складних проблем +- **Auto Mode**: Фоновий класифікатор безпеки перевіряє кожну дію перед виконанням (Research Preview) +- **Фонові завдання**: Виконання тривалих операцій без блокування розмови +- **Режими дозволів**: Контроль дій Claude (`default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, `bypassPermissions`) +- **Режим друку**: Неінтерактивний запуск Claude Code для автоматизації та CI/CD (`claude -p`) +- **Управління сесіями**: Управління кількома робочими сесіями +- **Інтерактивні функції**: Клавіатурні скорочення, багаторядковий ввід та історія команд +- **Голосовий ввід**: Push-to-talk голосовий ввід з підтримкою STT для 20 мов +- **Канали**: MCP-сервери надсилають повідомлення в активні сесії (Research Preview) +- **Remote Control**: Управління Claude Code з Claude.ai або додатку Claude +- **Веб-сесії**: Запуск Claude Code у браузері на claude.ai/code +- **Десктопний додаток**: Автономний додаток для візуального перегляду diff та кількох сесій +- **Список завдань**: Постійне відстеження завдань між стисненнями контексту +- **Підказки промптів**: Розумні підказки команд на основі контексту +- **Git Worktrees**: Ізольовані робочі дерева для паралельної роботи +- **Пісочниця**: Ізоляція файлової системи та мережі на рівні ОС +- **Керовані налаштування**: Корпоративне розгортання через plist, Registry або керовані файли +- **Конфігурація**: Налаштування поведінки за допомогою JSON-файлів конфігурації + +--- + +## Режим планування + +Режим планування дозволяє Claude продумати складні завдання перед їх реалізацією, створюючи детальний план, який ви можете переглянути та затвердити. + +### Що таке режим планування? + +Режим планування — це двофазний підхід: +1. **Фаза планування**: Claude аналізує завдання та створює детальний план реалізації +2. **Фаза реалізації**: Після затвердження Claude виконує план + +### Коли використовувати режим планування + +✅ Використовуйте для: +- Складного рефакторингу кількох файлів +- Реалізації нових функцій +- Архітектурних змін +- Міграцій баз даних +- Масштабних змін API + +❌ Не використовуйте для: +- Простого виправлення помилок +- Змін форматування +- Редагування одного файлу +- Швидких запитів + +### Активація режиму планування + +**Слеш-команда**: +```bash +/plan Implement user authentication system +``` + +**Прапорець CLI**: +```bash +claude --permission-mode plan +``` + +**Встановити за замовчуванням**: +```json +{ + "permissions": { + "defaultMode": "plan" + } +} +``` + +**Клавіатурне скорочення**: +- `Shift + Tab` — Перемикання режимів дозволів (включно з plan) +- `Alt + M` — Перемикання режимів дозволів (Windows/Linux) + +### Переваги режиму планування + +- **Структурований підхід до реалізації**: Детальна розбивка кроків реалізації +- **Перегляд та затвердження**: Затвердіть або скоригуйте план перед виконанням +- **Виявлення ризиків**: Визначення потенційних проблем до реалізації +- **Чіткі фази**: Організовані фази та етапи реалізації + +### Приклад: Реалізація функції + +``` +User: /plan Add a real-time notification system + +Claude: I'll create a plan for implementing real-time notifications. + +## Implementation Plan + +### Phase 1: Infrastructure Setup +1. Install WebSocket libraries (socket.io) +2. Set up WebSocket server +3. Configure connection management + +### Phase 2: Backend Implementation +4. Create notification service +5. Implement notification queue +6. Add database schema for notifications +7. Create API endpoints + +### Phase 3: Frontend Integration +8. Set up WebSocket client +9. Create notification UI components +10. Implement notification state management +11. Add notification permissions + +### Phase 4: Testing & Deployment +12. Write unit tests +13. Write integration tests +14. Update documentation +15. Deploy to staging + +Estimated time: 3-4 hours +Files to modify: 12 +New files to create: 8 + +Ready to proceed? (yes/no/modify plan) + +User: yes + +Claude: [Begins implementation following the plan] +``` + +### Модифікація планів + +``` +User: Modify the plan - skip the queue for now, we'll add it later + +Claude: Updated plan: +[Shows modified plan with queue removed] + +User: Looks good, proceed + +Claude: [Implements modified plan] +``` + +### Конфігурація режиму планування + +Режим планування активується через прапорець CLI або слеш-команду: + +```bash +# Активація режиму планування через CLI +claude --permission-mode plan + +# Або використовуйте слеш-команду /plan всередині REPL +/plan Implement user authentication system +``` + +**Псевдонім моделі для планування**: Використовуйте `opusplan` як псевдонім моделі, щоб використовувати Opus для планування та Sonnet для виконання: + +```bash +claude --model opusplan "design and implement the new API" +``` + +**Редагування плану зовні**: Натисніть `Ctrl+G`, щоб відкрити поточний план у зовнішньому редакторі для детальних змін. + +### Ultraplan + +Використовуйте `/ultraplan ` для наскрізного робочого процесу планування: Claude складає детальний план, відкриває його у браузері для перегляду, потім виконує план віддалено або повертає його у ваш термінал для локального виконання. + +--- + +## Розширене мислення + +Розширене мислення дозволяє Claude витрачати більше часу на обмірковування складних проблем перед наданням рішення. + +### Що таке розширене мислення? + +Розширене мислення — це цілеспрямований покроковий процес міркування, де Claude: +- Розбиває складні проблеми на частини +- Розглядає кілька підходів +- Оцінює компроміси +- Продумує граничні випадки + +### Активація розширеного мислення + +**Клавіатурне скорочення**: +- `Option + T` (macOS) / `Alt + T` (Windows/Linux) — Перемикання розширеного мислення + +**Автоматична активація**: +- Увімкнено за замовчуванням для всіх моделей (Opus 4.6, Sonnet 4.6, Haiku 4.5) +- Opus 4.6: Адаптивне міркування з рівнями зусиль: `low` (○), `medium` (◐), `high` (●), `max` (тільки Opus 4.6) +- Інші моделі: Фіксований бюджет до 31 999 токенів + +**Методи конфігурації**: +- Перемикання: `Alt+T` / `Option+T`, або через `/config` +- Перегляд міркувань: `Ctrl+O` (детальний режим) +- Встановлення зусиль: команда `/effort` або прапорець `--effort` + +**Власний бюджет**: +```bash +export MAX_THINKING_TOKENS=1024 +``` + +**Рівень зусиль** (тільки Opus 4.6): +```bash +export CLAUDE_CODE_EFFORT_LEVEL=high # low (○), medium (◐), high (●), або max (тільки Opus 4.6) +``` + +**Прапорець CLI**: +```bash +claude --effort high "complex architectural review" +``` + +**Слеш-команда**: +``` +/effort high +``` + +> **Примітка:** Ключове слово "ultrathink" у промптах активує режим глибокого міркування. Рівні зусиль `low`, `medium`, `high` та `max` (тільки Opus 4.6) контролюють обсяг міркувань Claude. + +### Переваги розширеного мислення + +- **Глибоке міркування**: Більше часу на обдумування складних проблем +- **Кращі архітектурні рішення**: Обґрунтовані рішення з комплексною оцінкою +- **Розгляд граничних випадків**: Продумування потенційних проблем і сценаріїв +- **Ретельний аналіз**: Структурований підхід до вирішення складних проблем + +### Приклад: Архітектурне рішення + +``` +User: /think Should we use microservices or a monolith for our e-commerce platform? + +Claude: Let me think through this architectural decision carefully... + + +## Context Analysis +- Team size: 5 developers +- Expected traffic: 10k daily users initially +- Need to scale to 100k+ users +- Limited DevOps resources +- 6-month timeline to MVP + +## Approach 1: Microservices +Pros: ++ Independent scaling ++ Technology flexibility ++ Team independence ++ Fault isolation + +Cons: +- Operational complexity +- Network overhead +- Distributed tracing needed +- Requires DevOps expertise +- Slower initial development + +## Approach 2: Monolith +Pros: ++ Simpler deployment ++ Faster initial development ++ Easier debugging ++ Lower operational overhead ++ Single codebase + +Cons: +- Scaling challenges later +- All-or-nothing deployments +- Technology lock-in +- Potential for tight coupling + +## Decision Factors +1. Team size (5 devs) → Favors monolith +2. DevOps resources (limited) → Favors monolith +3. Timeline (6 months) → Favors monolith +4. Future scale (100k users) → Achievable with monolith + caching +5. Complexity budget → Limited + +## Recommendation +Start with a **modular monolith**: +- Single deployment unit +- Clear module boundaries +- Clean interfaces between modules +- Prepare for future extraction to microservices if needed + +This gives you: +✓ Fast initial development +✓ Low operational complexity +✓ Option to extract services later +✓ Clear architecture + +Migration path: When you reach 50k+ users or specific modules need independent scaling, extract those modules into microservices. + + +**Recommendation**: Implement a modular monolith with clean module boundaries. + +This approach balances your current constraints (team size, timeline, DevOps resources) with future scalability needs. You can migrate specific modules to microservices later when there's a clear business need. +``` + +### Конфігурація розширеного мислення + +Розширене мислення контролюється через змінні оточення, клавіатурні скорочення та прапорці CLI: + +```bash +# Встановлення бюджету токенів мислення +export MAX_THINKING_TOKENS=16000 + +# Встановлення рівня зусиль (тільки Opus 4.6): low (○), medium (◐), high (●), або max (тільки Opus 4.6) +export CLAUDE_CODE_EFFORT_LEVEL=high +``` + +Перемикання під час сесії за допомогою `Alt+T` / `Option+T`, встановлення зусиль через `/effort` або конфігурація через `/config`. + +--- + +## Auto Mode + +Auto Mode — це режим дозволів Research Preview (березень 2026), який використовує фоновий класифікатор безпеки для перевірки кожної дії перед виконанням. Він дозволяє Claude працювати автономно, блокуючи небезпечні операції. + +### Вимоги + +- **План**: Team, Enterprise або API (недоступно на планах Pro або Max) +- **Модель**: Claude Sonnet 4.6 або Opus 4.6 +- **Провайдер**: Тільки Anthropic API (не підтримується на Bedrock, Vertex або Foundry) +- **Класифікатор**: Працює на Claude Sonnet 4.6 (додаткова вартість токенів) + +### Увімкнення Auto Mode + +```bash +# Розблокування auto mode за допомогою прапорця CLI +claude --enable-auto-mode + +# Потім перемикайте через Shift+Tab у REPL +``` + +Або встановіть як режим дозволів за замовчуванням: + +```bash +claude --permission-mode auto +``` + +Встановлення через конфігурацію: +```json +{ + "permissions": { + "defaultMode": "auto" + } +} +``` + +### Як працює класифікатор + +Фоновий класифікатор оцінює кожну дію в такому порядку: + +1. **Правила дозволу/заборони** — Спочатку перевіряються явні правила дозволів +2. **Читання/редагування автоматично затверджуються** — Читання та редагування файлів проходять автоматично +3. **Класифікатор** — Фоновий класифікатор перевіряє дію +4. **Запасний варіант** — Повертається до запиту після 3 послідовних або 20 загальних блокувань + +### Заблоковані дії за замовчуванням + +Auto mode блокує наступне за замовчуванням: + +| Заблокована дія | Приклад | +|----------------|---------| +| Встановлення через pipe-to-shell | `curl \| bash` | +| Надсилання конфіденційних даних назовні | API-ключі, облікові дані через мережу | +| Деплой на продакшн | Команди деплою на продакшн | +| Масове видалення | `rm -rf` на великих директоріях | +| Зміни IAM | Зміни дозволів та ролей | +| Force push у main | `git push --force origin main` | + +### Дозволені дії за замовчуванням + +| Дозволена дія | Приклад | +|----------------|---------| +| Локальні операції з файлами | Читання, запис, редагування файлів проєкту | +| Встановлення оголошених залежностей | `npm install`, `pip install` з маніфесту | +| HTTP тільки для читання | `curl` для отримання документації | +| Push у поточну гілку | `git push origin feature-branch` | + +### Конфігурація Auto Mode + +**Вивести правила за замовчуванням у JSON**: +```bash +claude auto-mode defaults +``` + +**Налаштування довіреної інфраструктури** через керовану настройку `autoMode.environment` для корпоративних розгортань. Це дозволяє адміністраторам визначати довірені середовища CI/CD, цілі деплою та шаблони інфраструктури. + +### Запасна поведінка + +Коли класифікатор невпевнений, auto mode повертається до запиту користувача: +- Після **3 послідовних** блокувань класифікатором +- Після **20 загальних** блокувань класифікатором за сесію + +Це гарантує, що користувач завжди зберігає контроль, коли класифікатор не може впевнено затвердити дію. + +### Посів дозволів Auto-Mode без Team-плану + +Якщо у вас немає Team-плану або ви хочете простіший підхід без фонового класифікатора, ви можете наповнити ваш `~/.claude/settings.json` консервативним базовим набором безпечних правил дозволів. Скрипт починає з правил тільки для читання та локального інспектування, потім дозволяє вам додавати редагування, тести, локальний запис у git, встановлення пакетів та дії запису GitHub лише за потреби. + +**Файл:** `09-advanced-features/setup-auto-mode-permissions.py` + +```bash +# Попередній перегляд змін (без запису) +python3 09-advanced-features/setup-auto-mode-permissions.py --dry-run + +# Застосувати консервативний базовий набір +python3 09-advanced-features/setup-auto-mode-permissions.py + +# Додавати більше можливостей лише за потреби +python3 09-advanced-features/setup-auto-mode-permissions.py --include-edits --include-tests +python3 09-advanced-features/setup-auto-mode-permissions.py --include-git-write --include-packages +``` + +Скрипт додає правила в таких категоріях: + +| Категорія | Приклади | +|----------|---------| +| Базові інструменти тільки для читання | `Read(*)`, `Glob(*)`, `Grep(*)`, `Agent(*)`, `WebSearch(*)`, `WebFetch(*)` | +| Локальне інспектування | `Bash(git status:*)`, `Bash(git log:*)`, `Bash(git diff:*)`, `Bash(cat:*)` | +| Опціональне редагування | `Edit(*)`, `Write(*)`, `NotebookEdit(*)` | +| Опціональні тести/збірка | `Bash(pytest:*)`, `Bash(python3 -m pytest:*)`, `Bash(cargo test:*)` | +| Опціональний запис у git | `Bash(git add:*)`, `Bash(git commit:*)`, `Bash(git stash:*)` | +| Git (локальний запис) | `Bash(git add:*)`, `Bash(git commit:*)`, `Bash(git checkout:*)` | +| Менеджери пакетів | `Bash(npm install:*)`, `Bash(pip install:*)`, `Bash(cargo build:*)` | +| Збірка та тести | `Bash(make:*)`, `Bash(pytest:*)`, `Bash(go test:*)` | +| Звичайні shell-команди | `Bash(ls:*)`, `Bash(cat:*)`, `Bash(find:*)`, `Bash(cp:*)`, `Bash(mv:*)` | +| GitHub CLI | `Bash(gh pr view:*)`, `Bash(gh pr create:*)`, `Bash(gh issue list:*)` | + +Небезпечні операції (`rm -rf`, `sudo`, force push, `DROP TABLE`, `terraform destroy` тощо) навмисно виключені. Скрипт ідемпотентний — повторний запуск не дублює правила. + +--- + +## Фонові завдання + +Фонові завдання дозволяють виконувати тривалі операції без блокування вашої розмови. + +### Що таке фонові завдання? + +Фонові завдання виконуються асинхронно, поки ви продовжуєте працювати: +- Тривалі набори тестів +- Процеси збірки +- Міграції баз даних +- Скрипти деплою +- Інструменти аналізу + +**Базове використання:** +```bash +User: Run tests in background + +Claude: Started task bg-1234 + +/task list # Показати всі завдання +/task status bg-1234 # Перевірити прогрес +/task show bg-1234 # Переглянути вивід +/task cancel bg-1234 # Скасувати завдання +``` + +### Запуск фонових завдань + +``` +User: Run the full test suite in the background + +Claude: Starting tests in background (task-id: bg-1234) +You can continue working while tests run. + +[You can continue the conversation] + +User: Meanwhile, let's refactor the auth module + +Claude: [Works on auth module while tests run in background] + +[Later, when tests complete] + +Claude: 📢 Background task bg-1234 completed: +✅ 245 tests passed +❌ 3 tests failed +View results: /task show bg-1234 +``` + +### Управління фоновими завданнями + +**Список активних завдань**: +``` +User: /task list + +Active background tasks: +1. [bg-1234] Running tests (50% complete, 2min remaining) +2. [bg-1235] Building Docker image (25% complete, 8min remaining) +3. [bg-1236] Deploying to staging (90% complete, 30sec remaining) +``` + +**Перевірка статусу завдання**: +``` +User: /task status bg-1234 + +Task bg-1234: Running tests +Status: In progress +Progress: 120/245 tests (49%) +Started: 2025-11-08 10:30:15 +Estimated completion: 2025-11-08 10:34:22 +``` + +**Перегляд виводу завдання**: +``` +User: /task show bg-1234 + +[Shows live output from the test run] +``` + +**Скасування завдання**: +``` +User: /task cancel bg-1234 + +Cancelled background task bg-1234 +``` + +### Приклад: Паралельна розробка + +``` +User: Run the build in the background + +Claude: Starting build... (task-id: bg-5001) + +User: Also run the linter in background + +Claude: Starting linter... (task-id: bg-5002) + +User: While those run, let's implement the new API endpoint + +Claude: [Implements API endpoint while build and linter run] + +[10 minutes later] + +Claude: 📢 Build completed successfully (bg-5001) +📢 Linter found 12 issues (bg-5002) + +User: Show me the linter issues + +Claude: [Shows linter output from bg-5002] +``` + +### Конфігурація + +```json +{ + "backgroundTasks": { + "enabled": true, + "maxConcurrentTasks": 5, + "notifyOnCompletion": true, + "autoCleanup": true, + "logOutput": true + } +} +``` + +--- + +## Заплановані завдання + +Заплановані завдання дозволяють автоматично запускати промпти за розкладом або як одноразові нагадування. Завдання привʼязані до сесії — вони працюють, поки Claude Code активний, і очищуються при завершенні сесії. Доступно з v2.1.72+. + +### Команда `/loop` + +```bash +# Явний інтервал +/loop 5m check if the deployment finished + +# Природна мова +/loop check build status every 30 minutes +``` + +Також підтримуються стандартні 5-польні cron-вирази для точного планування. + +### Одноразові нагадування + +Встановлення нагадувань, які спрацьовують один раз у визначений час: + +``` +remind me at 3pm to push the release branch +in 45 minutes, run the integration tests +``` + +### Управління запланованими завданнями + +| Інструмент | Опис | +|------|-------------| +| `CronCreate` | Створити нове заплановане завдання | +| `CronList` | Показати всі активні заплановані завдання | +| `CronDelete` | Видалити заплановане завдання | + +**Обмеження та поведінка**: +- До **50 запланованих завдань** на сесію +- Привʼязані до сесії — очищуються при завершенні сесії +- Повторювані завдання автоматично закінчуються через **3 дні** +- Завдання спрацьовують лише під час роботи Claude Code — пропущені запуски не компенсуються + +### Деталі поведінки + +| Аспект | Деталь | +|--------|--------| +| **Джитер повторюваних** | До 10% від інтервалу (макс. 15 хвилин) | +| **Джитер одноразових** | До 90 секунд на межах :00/:30 | +| **Пропущені запуски** | Без компенсації — пропускаються, якщо Claude Code не працював | +| **Збереження** | Не зберігаються між перезапусками | + +### Хмарні заплановані завдання + +Використовуйте `/schedule` для створення хмарних запланованих завдань, які працюють на інфраструктурі Anthropic: + +``` +/schedule daily at 9am run the test suite and report failures +``` + +Хмарні заплановані завдання зберігаються між перезапусками і не потребують локально запущеного Claude Code. + +### Вимкнення запланованих завдань + +```bash +export CLAUDE_CODE_DISABLE_CRON=1 +``` + +### Приклад: Моніторинг деплою + +``` +/loop 5m check the deployment status of the staging environment. + If the deploy succeeded, notify me and stop looping. + If it failed, show the error logs. +``` + +> **Порада**: Заплановані завдання привʼязані до сесії. Для постійної автоматизації, яка переживає перезапуски, використовуйте CI/CD пайплайни, GitHub Actions або заплановані завдання десктопного додатку. + +--- + +## Режими дозволів + +Режими дозволів контролюють, які дії Claude може виконувати без явного схвалення. + +### Доступні режими дозволів + +| Режим | Поведінка | +|---|---| +| `default` | Тільки читання файлів; запитує дозвіл на всі інші дії | +| `acceptEdits` | Читання та редагування файлів; запитує дозвіл на команди | +| `plan` | Тільки читання файлів (режим дослідження, без редагувань) | +| `auto` | Усі дії з перевірками фонового класифікатора безпеки (Research Preview) | +| `bypassPermissions` | Усі дії, без перевірки дозволів (небезпечно) | +| `dontAsk` | Виконуються лише попередньо затверджені інструменти; всі інші відхиляються | + +Перемикайте режими через `Shift+Tab` у CLI. Встановіть режим за замовчуванням через прапорець `--permission-mode` або налаштування `permissions.defaultMode`. + +### Методи активації + +**Клавіатурне скорочення**: +```bash +Shift + Tab # Перемикання між усіма 6 режимами +``` + +**Слеш-команда**: +```bash +/plan # Увійти в режим планування +``` + +**Прапорець CLI**: +```bash +claude --permission-mode plan +claude --permission-mode auto +``` + +**Налаштування**: +```json +{ + "permissions": { + "defaultMode": "auto" + } +} +``` + +### Приклади режимів дозволів + +#### Режим Default +Claude запитує підтвердження на значущі дії: + +``` +User: Fix the bug in auth.ts + +Claude: I need to modify src/auth.ts to fix the bug. +The change will update the password validation logic. + +Approve this change? (yes/no/show) +``` + +#### Режим Plan +Перегляд плану реалізації перед виконанням: + +``` +User: /plan Implement user authentication system + +Claude: I'll create a plan for implementing authentication. + +## Implementation Plan +[Detailed plan with phases and steps] + +Ready to proceed? (yes/no/modify) +``` + +#### Режим Accept Edits +Автоматичне прийняття змін у файлах: + +``` +User: acceptEdits +User: Fix the bug in auth.ts + +Claude: [Makes changes without asking] +``` + +### Випадки використання + +**Ревʼю коду**: +``` +User: claude --permission-mode plan +User: Review this PR and suggest improvements + +Claude: [Reads code, provides feedback, but cannot modify] +``` + +**Парне програмування**: +``` +User: claude --permission-mode default +User: Let's implement the feature together + +Claude: [Asks for approval before each change] +``` + +**Автоматизовані завдання**: +``` +User: claude --permission-mode acceptEdits +User: Fix all linting issues in the codebase + +Claude: [Auto-accepts file edits without asking] +``` + +--- + +## Headless Mode + +Режим друку (`claude -p`) дозволяє запускати Claude Code без інтерактивного вводу, ідеально для автоматизації та CI/CD. Це неінтерактивний режим, що замінює старий прапорець `--headless`. + +### Що таке режим друку? + +Режим друку забезпечує: +- Автоматизоване виконання скриптів +- Інтеграцію з CI/CD +- Пакетну обробку +- Виконання запланованих завдань + +### Запуск у режимі друку (неінтерактивний) + +```bash +# Запуск конкретного завдання +claude -p "Run all tests" + +# Обробка переданого вмісту +cat error.log | claude -p "Analyze these errors" + +# Інтеграція CI/CD (GitHub Actions) +- name: AI Code Review + run: claude -p "Review PR" +``` + +### Додаткові приклади використання режиму друку + +```bash +# Запуск завдання з захопленням виводу +claude -p "Run all tests and generate coverage report" + +# Зі структурованим виводом +claude -p --output-format json "Analyze code quality" + +# З вводом через stdin +echo "Analyze code quality" | claude -p "explain this" +``` + +### Приклад: Інтеграція CI/CD + +**GitHub Actions**: +```yaml +# .github/workflows/code-review.yml +name: AI Code Review + +on: [pull_request] + +jobs: + review: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Install Claude Code + run: npm install -g @anthropic-ai/claude-code + + - name: Run Claude Code Review + env: + ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} + run: | + claude -p --output-format json \ + --max-turns 3 \ + "Review this PR for: + - Code quality issues + - Security vulnerabilities + - Performance concerns + - Test coverage + Output results as JSON" > review.json + + - name: Post Review Comment + uses: actions/github-script@v7 + with: + script: | + const fs = require('fs'); + const review = JSON.parse(fs.readFileSync('review.json', 'utf8')); + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: JSON.stringify(review, null, 2) + }); +``` + +### Конфігурація режиму друку + +Режим друку (`claude -p`) підтримує кілька прапорців для автоматизації: + +```bash +# Обмеження автономних ходів +claude -p --max-turns 5 "refactor this module" + +# Структурований вивід JSON +claude -p --output-format json "analyze this codebase" + +# З валідацією схеми +claude -p --json-schema '{"type":"object","properties":{"issues":{"type":"array"}}}' \ + "find bugs in this code" + +# Вимкнення збереження сесії +claude -p --no-session-persistence "one-off analysis" +``` + +--- + +## Управління сесіями + +Ефективне управління кількома сесіями Claude Code. + +### Команди управління сесіями + +| Команда | Опис | +|---------|-------------| +| `/resume` | Відновити розмову за ID або назвою | +| `/rename` | Назвати поточну сесію | +| `/fork` | Розгалужити поточну сесію в нову гілку | +| `claude -c` | Продовжити останню розмову | +| `claude -r "session"` | Відновити сесію за назвою або ID | + +### Відновлення сесій + +**Продовжити останню розмову**: +```bash +claude -c +``` + +**Відновити іменовану сесію**: +```bash +claude -r "auth-refactor" "finish this PR" +``` + +**Перейменувати поточну сесію** (всередині REPL): +``` +/rename auth-refactor +``` + +### Розгалуження сесій + +Розгалужте сесію, щоб спробувати альтернативний підхід без втрати оригіналу: + +``` +/fork +``` + +Або з CLI: +```bash +claude --resume auth-refactor --fork-session "try OAuth instead" +``` + +### Збереження сесій + +Сесії автоматично зберігаються і можуть бути відновлені: + +```bash +# Продовжити останню розмову +claude -c + +# Відновити конкретну сесію за назвою або ID +claude -r "auth-refactor" + +# Відновити та розгалужити для експериментів +claude --resume auth-refactor --fork-session "alternative approach" +``` + +--- + +## Інтерактивні функції + +### Клавіатурні скорочення + +Claude Code підтримує клавіатурні скорочення для ефективності. Ось повний довідник з офіційної документації: + +| Скорочення | Опис | +|----------|-------------| +| `Ctrl+C` | Скасувати поточний ввід/генерацію | +| `Ctrl+D` | Вийти з Claude Code | +| `Ctrl+G` | Редагувати план у зовнішньому редакторі | +| `Ctrl+L` | Очистити екран терміналу | +| `Ctrl+O` | Перемкнути детальний вивід (перегляд міркувань) | +| `Ctrl+R` | Зворотний пошук в історії | +| `Ctrl+T` | Перемкнути перегляд списку завдань | +| `Ctrl+B` | Перевести завдання у фоновий режим | +| `Esc+Esc` | Відкотити код/розмову | +| `Shift+Tab` / `Alt+M` | Перемикання режимів дозволів | +| `Option+P` / `Alt+P` | Перемкнути модель | +| `Option+T` / `Alt+T` | Перемкнути розширене мислення | + +**Редагування рядка (стандартні скорочення readline):** + +| Скорочення | Дія | +|----------|--------| +| `Ctrl + A` | Перейти на початок рядка | +| `Ctrl + E` | Перейти на кінець рядка | +| `Ctrl + K` | Вирізати до кінця рядка | +| `Ctrl + U` | Вирізати до початку рядка | +| `Ctrl + W` | Видалити слово назад | +| `Ctrl + Y` | Вставити (yank) | +| `Tab` | Автодоповнення | +| `↑ / ↓` | Історія команд | + +### Кастомізація клавіатурних скорочень + +Створюйте власні клавіатурні скорочення, запустивши `/keybindings`, що відкриває `~/.claude/keybindings.json` для редагування (v2.1.18+). + +**Формат конфігурації**: + +```json +{ + "$schema": "https://www.schemastore.org/claude-code-keybindings.json", + "bindings": [ + { + "context": "Chat", + "bindings": { + "ctrl+e": "chat:externalEditor", + "ctrl+u": null, + "ctrl+k ctrl+s": "chat:stash" + } + }, + { + "context": "Confirmation", + "bindings": { + "ctrl+a": "confirmation:yes" + } + } + ] +} +``` + +Встановіть привʼязку в `null`, щоб відвʼязати скорочення за замовчуванням. + +### Доступні контексти + +Клавіатурні скорочення привʼязані до конкретних контекстів UI: + +| Контекст | Ключові дії | +|---------|-------------| +| **Chat** | `submit`, `cancel`, `cycleMode`, `modelPicker`, `thinkingToggle`, `undo`, `externalEditor`, `stash`, `imagePaste` | +| **Confirmation** | `yes`, `no`, `previous`, `next`, `nextField`, `cycleMode`, `toggleExplanation` | +| **Global** | `interrupt`, `exit`, `toggleTodos`, `toggleTranscript` | +| **Autocomplete** | `accept`, `dismiss`, `next`, `previous` | +| **HistorySearch** | `search`, `previous`, `next` | +| **Settings** | Навігація налаштуваннями | +| **Tabs** | Перемикання та управління вкладками | +| **Help** | Навігація панеллю допомоги | + +Загалом 18 контекстів, включаючи `Transcript`, `Task`, `ThemePicker`, `Attachments`, `Footer`, `MessageSelector`, `DiffDialog`, `ModelPicker` та `Select`. + +### Підтримка акордів + +Клавіатурні скорочення підтримують послідовності акордів (комбінації з кількох клавіш): + +``` +"ctrl+k ctrl+s" → Двоклавішна послідовність: натисніть ctrl+k, потім ctrl+s +"ctrl+shift+p" → Одночасне натискання модифікаторів +``` + +**Синтаксис клавіш**: +- **Модифікатори**: `ctrl`, `alt` (або `opt`), `shift`, `meta` (або `cmd`) +- **Великі літери включають Shift**: `K` еквівалентно `shift+k` +- **Спеціальні клавіші**: `escape`, `enter`, `return`, `tab`, `space`, `backspace`, `delete`, клавіші стрілок + +### Зарезервовані та конфліктні клавіші + +| Клавіша | Статус | Примітки | +|-----|--------|-------| +| `Ctrl+C` | Зарезервовано | Неможливо перепривʼязати (переривання) | +| `Ctrl+D` | Зарезервовано | Неможливо перепривʼязати (вихід) | +| `Ctrl+B` | Конфлікт терміналу | Префіксна клавіша tmux | +| `Ctrl+A` | Конфлікт терміналу | Префіксна клавіша GNU Screen | +| `Ctrl+Z` | Конфлікт терміналу | Призупинення процесу | + +> **Порада**: Якщо скорочення не працює, перевірте конфлікти з вашим емулятором терміналу або мультиплексором. + +### Tab-доповнення + +Claude Code забезпечує інтелектуальне tab-доповнення: + +``` +User: /rew +→ /rewind + +User: /plu +→ /plugin + +User: /plugin +→ /plugin install +→ /plugin enable +→ /plugin disable +``` + +### Історія команд + +Доступ до попередніх команд: + +``` +User: <↑> # Попередня команда +User: <↓> # Наступна команда +User: Ctrl+R # Пошук в історії + +(reverse-i-search)`test': run all tests +``` + +### Багаторядковий ввід + +Для складних запитів використовуйте багаторядковий режим: + +```bash +User: \ +> Long complex prompt +> spanning multiple lines +> \end +``` + +**Приклад:** + +``` +User: \ +> Implement a user authentication system +> with the following requirements: +> - JWT tokens +> - Email verification +> - Password reset +> - 2FA support +> \end + +Claude: [Processes the multi-line request] +``` + +### Inline-редагування + +Редагування команд перед відправкою: + +``` +User: Deploy to prodcutionuction + +[Edit in-place before sending] +``` + +### Режим Vim + +Увімкнення Vi/Vim-клавіатурних привʼязок для редагування тексту: + +**Активація**: +- Використовуйте команду `/vim` або `/config` для увімкнення +- Перемикання режимів: `Esc` для NORMAL, `i/a/o` для INSERT + +**Клавіші навігації**: +- `h` / `l` — Рух вліво/вправо +- `j` / `k` — Рух вниз/вгору +- `w` / `b` / `e` — Рух по словах +- `0` / `$` — Перейти на початок/кінець рядка +- `gg` / `G` — Перейти на початок/кінець тексту + +**Текстові обʼєкти**: +- `iw` / `aw` — Внутрішнє/зовнішнє слово +- `i"` / `a"` — Внутрішній/зовнішній рядок у лапках +- `i(` / `a(` — Внутрішнє/зовнішнє у дужках + +### Режим Bash + +Виконання shell-команд безпосередньо з префіксом `!`: + +```bash +! npm test +! git status +! cat src/index.js +``` + +Використовуйте це для швидкого виконання команд без перемикання контексту. + +--- + +## Голосовий ввід + +Голосовий ввід забезпечує push-to-talk голосове введення для Claude Code, дозволяючи промовляти ваші промпти замість друкування. + +### Активація голосового вводу + +``` +/voice +``` + +### Можливості + +| Можливість | Опис | +|---------|-------------| +| **Push-to-talk** | Утримуйте клавішу для запису, відпустіть для відправки | +| **20 мов** | Розпізнавання мовлення підтримує 20 мов | +| **Власна клавіша** | Налаштуйте клавішу push-to-talk через `/keybindings` | +| **Вимога облікового запису** | Потрібен обліковий запис Claude.ai для обробки STT | + +### Конфігурація + +Налаштуйте клавішу push-to-talk у файлі привʼязок (`/keybindings`). Голосовий ввід використовує ваш обліковий запис Claude.ai для обробки мовлення в текст. + +--- + +## Канали + +Канали — це функція Research Preview, яка надсилає події від зовнішніх сервісів у запущену сесію Claude Code через MCP-сервери. Джерела включають Telegram, Discord, iMessage та довільні вебхуки, дозволяючи Claude реагувати на повідомлення в реальному часі без опитування. + +### Підписка на канали + +```bash +# Підписка на плагіни каналів при запуску +claude --channels discord,telegram + +# Підписка на кілька джерел +claude --channels discord,telegram,imessage,webhooks +``` + +### Підтримувані інтеграції + +| Інтеграція | Опис | +|-------------|-------------| +| **Discord** | Отримання та відповіді на повідомлення Discord у вашій сесії | +| **Telegram** | Отримання та відповіді на повідомлення Telegram у вашій сесії | +| **iMessage** | Отримання сповіщень iMessage у вашій сесії | +| **Webhooks** | Отримання подій від довільних джерел вебхуків | + +### Конфігурація + +Налаштуйте канали прапорцем `--channels` при запуску. Для корпоративних розгортань використовуйте керовану настройку для контролю дозволених плагінів каналів: + +```json +{ + "allowedChannelPlugins": ["discord", "telegram"] +} +``` + +Керована настройка `allowedChannelPlugins` контролює, які плагіни каналів дозволені в організації. + +### Як це працює + +1. MCP-сервери діють як плагіни каналів, що підключаються до зовнішніх сервісів +2. Вхідні повідомлення та події надсилаються в активну сесію Claude Code +3. Claude може читати та відповідати на повідомлення в контексті сесії +4. Плагіни каналів мають бути затверджені через керовану настройку `allowedChannelPlugins` +5. Опитування не потрібне — події надсилаються в реальному часі + +--- + +## Інтеграція Chrome + +Інтеграція Chrome підключає Claude Code до вашого браузера Chrome або Microsoft Edge для автоматизації та відлагодження веб-сторінок у реальному часі. Це бета-функція, доступна з v2.0.73+ (підтримка Edge додана в v1.0.36+). + +### Увімкнення інтеграції Chrome + +**При запуску**: + +```bash +claude --chrome # Увімкнути зʼєднання з Chrome +claude --no-chrome # Вимкнути зʼєднання з Chrome +``` + +**Всередині сесії**: + +``` +/chrome +``` + +Оберіть "Enabled by default" для активації інтеграції Chrome для всіх майбутніх сесій. Claude Code використовує стан входу вашого браузера, тому може взаємодіяти з автентифікованими веб-додатками. + +### Можливості + +| Можливість | Опис | +|------------|-------------| +| **Відлагодження в реальному часі** | Читання логів консолі, інспектування DOM-елементів, відлагодження JavaScript в реальному часі | +| **Перевірка дизайну** | Порівняння відрендерених сторінок з макетами дизайну | +| **Валідація форм** | Тестування відправки форм, валідації вводу та обробки помилок | +| **Тестування веб-додатків** | Взаємодія з автентифікованими додатками (Gmail, Google Docs, Notion тощо) | +| **Витягування даних** | Збір та обробка контенту з веб-сторінок | +| **Запис сесії** | Запис взаємодій з браузером у GIF-файли | + +### Дозволи на рівні сайтів + +Розширення Chrome управляє доступом до окремих сайтів. Надавайте або відкликайте доступ для конкретних сайтів у будь-який час через спливаюче вікно розширення. Claude Code взаємодіє лише з сайтами, які ви явно дозволили. + +### Як це працює + +Claude Code керує браузером у видимому вікні — ви можете спостерігати за діями в реальному часі. Коли браузер натрапляє на сторінку входу або CAPTCHA, Claude зупиняється і чекає, поки ви вручну обробите це, перш ніж продовжити. + +### Відомі обмеження + +- **Підтримка браузерів**: Тільки Chrome та Edge — Brave, Arc та інші браузери на базі Chromium не підтримуються +- **WSL**: Недоступно у Windows Subsystem for Linux +- **Сторонні провайдери**: Не підтримується з провайдерами API Bedrock, Vertex або Foundry +- **Idle service worker**: Service worker розширення Chrome може переходити у неактивний стан під час тривалих сесій + +> **Порада**: Інтеграція Chrome є бета-функцією. Підтримка браузерів може розширитись у майбутніх релізах. + +--- + +## Remote Control + +Remote Control дозволяє продовжити локально запущену сесію Claude Code з телефону, планшета або будь-якого браузера. Ваша локальна сесія продовжує працювати на вашому компʼютері — нічого не переміщується у хмару. Доступно на планах Pro, Max, Team та Enterprise (v2.1.51+). + +### Запуск Remote Control + +**З CLI**: + +```bash +# Запуск із назвою сесії за замовчуванням +claude remote-control + +# Запуск із власною назвою +claude remote-control --name "Auth Refactor" +``` + +**Зсередини сесії**: + +``` +/remote-control +/remote-control "Auth Refactor" +``` + +**Доступні прапорці**: + +| Прапорець | Опис | +|------|-------------| +| `--name "title"` | Власна назва сесії для зручної ідентифікації | +| `--verbose` | Показувати детальні логи зʼєднання | +| `--sandbox` | Увімкнути ізоляцію файлової системи та мережі | +| `--no-sandbox` | Вимкнути пісочницю (за замовчуванням) | + +### Підключення до сесії + +Три способи підключення з іншого пристрою: + +1. **URL сесії** — Виводиться в термінал при запуску сесії; відкрийте у будь-якому браузері +2. **QR-код** — Натисніть `пробіл` після запуску для відображення QR-коду для сканування +3. **Пошук за назвою** — Перегляньте ваші сесії на claude.ai/code або у мобільному додатку Claude (iOS/Android) + +### Безпека + +- **Жодних вхідних портів** не відкривається на вашому компʼютері +- **Тільки вихідний HTTPS** через TLS +- **Обмежені облікові дані** — кілька короткоживучих токенів з вузькою областю дії +- **Ізоляція сесій** — кожна віддалена сесія незалежна + +### Remote Control проти Claude Code у вебі + +| Аспект | Remote Control | Claude Code у вебі | +|--------|---------------|-------------------| +| **Виконання** | Працює на вашому компʼютері | Працює у хмарі Anthropic | +| **Локальні інструменти** | Повний доступ до локальних MCP-серверів, файлів та CLI | Без локальних залежностей | +| **Випадок використання** | Продовження локальної роботи з іншого пристрою | Початок роботи з нуля в будь-якому браузері | + +### Обмеження + +- Одна віддалена сесія на екземпляр Claude Code +- Термінал має залишатись відкритим на хост-машині +- Сесія закінчується через ~10 хвилин, якщо мережа недоступна + +### Випадки використання + +- Управління Claude Code з мобільного пристрою або планшета, перебуваючи далеко від робочого місця +- Використання багатшого UI claude.ai зі збереженням локального виконання інструментів +- Швидке ревʼю коду на ходу з повним локальним середовищем розробки + +--- + +## Веб-сесії + +Веб-сесії дозволяють запускати Claude Code безпосередньо у браузері на claude.ai/code або створювати веб-сесії з CLI. + +### Створення веб-сесії + +```bash +# Створення нової веб-сесії з CLI +claude --remote "implement the new API endpoints" +``` + +Це запускає сесію Claude Code на claude.ai, до якої можна отримати доступ з будь-якого браузера. + +### Відновлення веб-сесій локально + +Якщо ви почали сесію у вебі і хочете продовжити локально: + +```bash +# Відновити веб-сесію в локальному терміналі +claude --teleport +``` + +Або зсередини інтерактивного REPL: +``` +/teleport +``` + +### Випадки використання + +- Почати роботу на одному компʼютері і продовжити на іншому +- Поділитися URL сесії з членами команди +- Використовувати веб-UI для візуального перегляду diff, потім перемкнутися на термінал для виконання + +--- + +## Десктопний додаток + +Десктопний додаток Claude Code надає автономний додаток з візуальним переглядом diff, паралельними сесіями та інтегрованими конекторами. Доступний для macOS та Windows (плани Pro, Max, Team та Enterprise). + +### Встановлення + +Завантажте з [claude.ai](https://claude.ai) для вашої платформи: +- **macOS**: Універсальна збірка (Apple Silicon та Intel) +- **Windows**: Інсталятори для x64 та ARM64 + +Дивіться [Desktop Quickstart](https://code.claude.com/docs/en/desktop-quickstart) для інструкцій з налаштування. + +### Передача з CLI + +Передайте поточну CLI-сесію в десктопний додаток: + +``` +/desktop +``` + +### Основні функції + +| Функція | Опис | +|---------|-------------| +| **Перегляд diff** | Візуальний перегляд файл за файлом з inline-коментарями; Claude читає коментарі та вносить виправлення | +| **Попередній перегляд додатку** | Автозапуск dev-серверів з вбудованим браузером для живої перевірки | +| **Моніторинг PR** | Інтеграція GitHub CLI з автовиправленням помилок CI та автозлиттям при проходженні перевірок | +| **Паралельні сесії** | Кілька сесій у бічній панелі з автоматичною ізоляцією Git worktree | +| **Заплановані завдання** | Повторювані завдання (щогодини, щодня, у робочі дні, щотижня), що працюють при відкритому додатку | +| **Багатий рендеринг** | Рендеринг коду, markdown та діаграм з підсвіткою синтаксису | + +### Конфігурація попереднього перегляду додатку + +Налаштуйте поведінку dev-сервера в `.claude/launch.json`: + +```json +{ + "command": "npm run dev", + "port": 3000, + "readyPattern": "ready on", + "persistCookies": true +} +``` + +### Конектори + +Підключення зовнішніх сервісів для багатшого контексту: + +| Конектор | Можливість | +|-----------|------------| +| **GitHub** | Моніторинг PR, трекінг issues, ревʼю коду | +| **Slack** | Сповіщення, контекст каналів | +| **Linear** | Трекінг issues, управління спринтами | +| **Notion** | Документація, доступ до бази знань | +| **Asana** | Управління завданнями, трекінг проєктів | +| **Calendar** | Обізнаність про розклад, контекст зустрічей | + +> **Примітка**: Конектори недоступні для віддалених (хмарних) сесій. + +### Віддалені та SSH-сесії + +- **Віддалені сесії**: Працюють на хмарній інфраструктурі Anthropic; продовжуються навіть після закриття додатку. Доступні з claude.ai/code або мобільного додатку Claude +- **SSH-сесії**: Підключення до віддалених машин через SSH з повним доступом до віддаленої файлової системи та інструментів. Claude Code повинен бути встановлений на віддаленій машині + +### Режими дозволів у десктопному додатку + +Десктопний додаток підтримує ті самі 4 режими дозволів, що й CLI: + +| Режим | Поведінка | +|------|----------| +| **Ask permissions** (за замовчуванням) | Перегляд та затвердження кожного редагування та команди | +| **Auto accept edits** | Редагування файлів автозатверджуються; команди потребують ручного затвердження | +| **Plan mode** | Перегляд підходу перед будь-якими змінами | +| **Bypass permissions** | Автоматичне виконання (лише у пісочниці, контролюється адміністратором) | + +### Корпоративні функції + +- **Консоль адміністратора**: Контроль доступу до вкладки Code та налаштувань дозволів для організації +- **Розгортання через MDM**: Розгортання через MDM на macOS або MSIX на Windows +- **Інтеграція SSO**: Вимога єдиного входу для членів організації +- **Керовані налаштування**: Централізоване управління конфігурацією команди та доступністю моделей + +--- + +## Список завдань + +Функція списку завдань забезпечує постійне відстеження завдань, яке переживає стиснення контексту (коли історія розмови обрізається для вміщення в контекстне вікно). + +### Перемикання списку завдань + +Натисніть `Ctrl+T` для перемикання перегляду списку завдань під час сесії. + +### Постійні завдання + +Завдання зберігаються між стисненнями контексту, гарантуючи, що тривалі робочі елементи не втрачаються при обрізці контексту розмови. Це особливо корисно для складних, багатоетапних реалізацій. + +### Іменовані директорії завдань + +Використовуйте змінну оточення `CLAUDE_CODE_TASK_LIST_ID` для створення іменованих директорій завдань, спільних між сесіями: + +```bash +export CLAUDE_CODE_TASK_LIST_ID=my-project-sprint-3 +``` + +Це дозволяє кільком сесіям використовувати один список завдань, що корисно для командних робочих процесів або проєктів з кількома сесіями. + +--- + +## Підказки промптів + +Підказки промптів відображають напівпрозорі приклади команд на основі вашої git-історії та поточного контексту розмови. + +### Як це працює + +- Підказки зʼявляються як напівпрозорий текст під вашим вводом +- Натисніть `Tab` для прийняття підказки +- Натисніть `Enter` для прийняття та негайної відправки +- Підказки враховують контекст, використовуючи git-історію та стан розмови + +### Вимкнення підказок промптів + +```bash +export CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=false +``` + +--- + +## Git Worktrees + +Git Worktrees дозволяють запускати Claude Code в ізольованому робочому дереві, забезпечуючи паралельну роботу на різних гілках без stash або перемикання. + +### Запуск у Worktree + +```bash +# Запуск Claude Code в ізольованому робочому дереві +claude --worktree +# або +claude -w +``` + +### Розташування Worktree + +Робочі дерева створюються за адресою: +``` +/.claude/worktrees/ +``` + +### Sparse Checkout для монорепозиторіїв + +Використовуйте налаштування `worktree.sparsePaths` для виконання sparse-checkout у монорепозиторіях, зменшуючи використання диску та час клонування: + +```json +{ + "worktree": { + "sparsePaths": ["packages/my-package", "shared/"] + } +} +``` + +### Інструменти та хуки Worktree + +| Елемент | Опис | +|------|-------------| +| `ExitWorktree` | Інструмент для виходу та очищення поточного робочого дерева | +| `WorktreeCreate` | Подія хуку при створенні робочого дерева | +| `WorktreeRemove` | Подія хуку при видаленні робочого дерева | + +### Автоочищення + +Якщо в робочому дереві не було зроблено змін, воно автоматично очищується при завершенні сесії. + +### Випадки використання + +- Робота над feature-гілкою зі збереженням незміненої основної гілки +- Запуск тестів в ізоляції без впливу на робочу директорію +- Спроба експериментальних змін у одноразовому середовищі +- Sparse-checkout конкретних пакетів у монорепозиторіях для швидшого запуску + +--- + +## Пісочниця + +Пісочниця забезпечує ізоляцію файлової системи та мережі на рівні ОС для Bash-команд, що виконуються Claude Code. Це доповнює правила дозволів і забезпечує додатковий рівень безпеки. + +### Увімкнення пісочниці + +**Слеш-команда**: +``` +/sandbox +``` + +**Прапорці CLI**: +```bash +claude --sandbox # Увімкнути пісочницю +claude --no-sandbox # Вимкнути пісочницю +``` + +### Налаштування конфігурації + +| Налаштування | Опис | +|---------|-------------| +| `sandbox.enabled` | Увімкнути або вимкнути пісочницю | +| `sandbox.failIfUnavailable` | Зупинитись, якщо пісочницю неможливо активувати | +| `sandbox.filesystem.allowWrite` | Шляхи з дозволом на запис | +| `sandbox.filesystem.allowRead` | Шляхи з дозволом на читання | +| `sandbox.filesystem.denyRead` | Шляхи з забороною читання | +| `sandbox.enableWeakerNetworkIsolation` | Увімкнути слабшу ізоляцію мережі на macOS | + +### Приклад конфігурації + +```json +{ + "sandbox": { + "enabled": true, + "failIfUnavailable": true, + "filesystem": { + "allowWrite": ["/Users/me/project"], + "allowRead": ["/Users/me/project", "/usr/local/lib"], + "denyRead": ["/Users/me/.ssh", "/Users/me/.aws"] + }, + "enableWeakerNetworkIsolation": true + } +} +``` + +### Як це працює + +- Bash-команди виконуються у пісочниці з обмеженим доступом до файлової системи +- Мережевий доступ може бути ізольований для запобігання небажаним зовнішнім зʼєднанням +- Працює разом з правилами дозволів для глибокого захисту +- На macOS використовуйте `sandbox.enableWeakerNetworkIsolation` для мережевих обмежень (повна ізоляція мережі недоступна на macOS) + +### Випадки використання + +- Безпечний запуск ненадійного або згенерованого коду +- Запобігання випадковим змінам файлів за межами проєкту +- Обмеження мережевого доступу під час автоматизованих завдань + +--- + +## Керовані налаштування (Enterprise) + +Керовані налаштування дозволяють корпоративним адміністраторам розгортати конфігурацію Claude Code по всій організації за допомогою платформних засобів управління. + +### Методи розгортання + +| Платформа | Метод | Починаючи з | +|----------|--------|-------| +| macOS | Керовані plist-файли (MDM) | v2.1.51+ | +| Windows | Реєстр Windows | v2.1.51+ | +| Кросплатформний | Керовані файли конфігурації | v2.1.51+ | +| Кросплатформний | Керовані drop-ins (директорія `managed-settings.d/`) | v2.1.83+ | + +### Керовані Drop-ins + +Починаючи з v2.1.83, адміністратори можуть розгортати кілька файлів керованих налаштувань у директорію `managed-settings.d/`. Файли обʼєднуються в алфавітному порядку, дозволяючи модульну конфігурацію між командами: + +``` +~/.claude/managed-settings.d/ + 00-org-defaults.json + 10-team-policies.json + 20-project-overrides.json +``` + +### Доступні керовані налаштування + +| Налаштування | Опис | +|---------|-------------| +| `disableBypassPermissionsMode` | Заборонити користувачам вмикати обхід дозволів | +| `availableModels` | Обмежити моделі, доступні для вибору | +| `allowedChannelPlugins` | Контролювати дозволені плагіни каналів | +| `autoMode.environment` | Налаштувати довірену інфраструктуру для auto mode | +| Власні політики | Організаційні політики дозволів та інструментів | + +### Приклад: macOS Plist + +```xml + + + + + disableBypassPermissionsMode + + availableModels + + claude-sonnet-4-6 + claude-haiku-4-5 + + + +``` + +--- + +## Конфігурація та налаштування + +### Розташування файлів конфігурації + +1. **Глобальна конфігурація**: `~/.claude/config.json` +2. **Конфігурація проєкту**: `./.claude/config.json` +3. **Конфігурація користувача**: `~/.config/claude-code/settings.json` + +### Повний приклад конфігурації + +**Конфігурація основних розширених функцій:** + +```json +{ + "permissions": { + "mode": "default" + }, + "hooks": { + "PreToolUse:Edit": "eslint --fix ${file_path}", + "PostToolUse:Write": "~/.claude/hooks/security-scan.sh" + }, + "mcp": { + "enabled": true, + "servers": { + "github": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-github"] + } + } + } +} +``` + +**Розширений приклад конфігурації:** + +```json +{ + "permissions": { + "mode": "default", + "allowedTools": ["Bash(git log:*)", "Read"], + "disallowedTools": ["Bash(rm -rf:*)"] + }, + + "hooks": { + "PreToolUse": [{ "matcher": "Edit", "hooks": ["eslint --fix ${file_path}"] }], + "PostToolUse": [{ "matcher": "Write", "hooks": ["~/.claude/hooks/security-scan.sh"] }], + "Stop": [{ "hooks": ["~/.claude/hooks/notify.sh"] }] + }, + + "mcp": { + "enabled": true, + "servers": { + "github": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-github"], + "env": { + "GITHUB_TOKEN": "${GITHUB_TOKEN}" + } + } + } + } +} +``` + +### Змінні оточення + +Перевизначення конфігурації через змінні оточення: + +```bash +# Вибір моделі +export ANTHROPIC_MODEL=claude-opus-4-6 +export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-6 +export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6 +export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5 + +# Конфігурація API +export ANTHROPIC_API_KEY=sk-ant-... + +# Конфігурація мислення +export MAX_THINKING_TOKENS=16000 +export CLAUDE_CODE_EFFORT_LEVEL=high + +# Перемикачі функцій +export CLAUDE_CODE_DISABLE_AUTO_MEMORY=true +export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=true +export CLAUDE_CODE_DISABLE_CRON=1 +export CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=true +export CLAUDE_CODE_DISABLE_TERMINAL_TITLE=true +export CLAUDE_CODE_DISABLE_1M_CONTEXT=true +export CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=true +export CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=false +export CLAUDE_CODE_ENABLE_TASKS=true +export CLAUDE_CODE_SIMPLE=true # Встановлюється прапорцем --bare + +# Конфігурація MCP +export MAX_MCP_OUTPUT_TOKENS=50000 +export ENABLE_TOOL_SEARCH=true + +# Управління завданнями +export CLAUDE_CODE_TASK_LIST_ID=my-project-tasks + +# Agent teams (експериментально) +export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 + +# Конфігурація субагентів та плагінів +export CLAUDE_CODE_SUBAGENT_MODEL=sonnet +export CLAUDE_CODE_PLUGIN_SEED_DIR=./my-plugins +export CLAUDE_CODE_NEW_INIT=1 + +# Підпроцеси та стрімінг +export CLAUDE_CODE_SUBPROCESS_ENV_SCRUB="SECRET_KEY,DB_PASSWORD" +export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=80 +export CLAUDE_STREAM_IDLE_TIMEOUT_MS=30000 +export ANTHROPIC_CUSTOM_MODEL_OPTION=my-custom-model +export SLASH_COMMAND_TOOL_CHAR_BUDGET=50000 +``` + +### Команди управління конфігурацією + +``` +User: /config +[Opens interactive configuration menu] +``` + +Команда `/config` надає інтерактивне меню для перемикання налаштувань, таких як: +- Розширене мислення увімк./вимк. +- Детальний вивід +- Режим дозволів +- Вибір моделі + +### Конфігурація на рівні проєкту + +Створіть `.claude/config.json` у вашому проєкті: + +```json +{ + "hooks": { + "PreToolUse": [{ "matcher": "Bash", "hooks": ["npm test && npm run lint"] }] + }, + "permissions": { + "mode": "default" + }, + "mcp": { + "servers": { + "project-db": { + "command": "mcp-postgres", + "env": { + "DATABASE_URL": "${PROJECT_DB_URL}" + } + } + } + } +} +``` + +--- + +## Agent Teams + +Agent Teams — це експериментальна функція, яка дозволяє кільком екземплярам Claude Code співпрацювати над завданням. Вимкнена за замовчуванням. + +### Увімкнення Agent Teams + +Увімкнення через змінну оточення або налаштування: + +```bash +# Змінна оточення +export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 +``` + +Або додайте до вашого JSON-файлу налаштувань: + +```json +{ + "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" +} +``` + +### Як працюють Agent Teams + +- **Лідер команди** координує загальне завдання та делегує підзавдання товаришам по команді +- **Товариші по команді** працюють незалежно, кожен зі своїм контекстним вікном +- **Спільний список завдань** забезпечує самокоординацію між членами команди +- Використовуйте визначення субагентів (`.claude/agents/` або прапорець `--agents`) для визначення ролей та спеціалізацій товаришів + +### Режими відображення + +Agent Teams підтримують два режими відображення, що налаштовуються прапорцем `--teammate-mode`: + +| Режим | Опис | +|------|-------------| +| `in-process` (за замовчуванням) | Товариші працюють у тому ж процесі терміналу | +| `tmux` | Кожен товариш отримує окрему розділену панель (потрібен tmux або iTerm2) | +| `auto` | Автоматичний вибір найкращого режиму відображення | + +```bash +# Використання tmux для відображення товаришів +claude --teammate-mode tmux + +# Явне використання in-process режиму +claude --teammate-mode in-process +``` + +### Випадки використання + +- Великі завдання рефакторингу, де різні товариші обробляють різні модулі +- Паралельне ревʼю коду та реалізація +- Координовані зміни кількох файлів по всій кодовій базі + +> **Примітка**: Agent Teams є експериментальною функцією і може змінитися у майбутніх релізах. Дивіться [code.claude.com/docs/en/agent-teams](https://code.claude.com/docs/en/agent-teams) для повного довідника. + +--- + +## Найкращі практики + +### Режим планування +- ✅ Використовуйте для складних багатоетапних завдань +- ✅ Переглядайте плани перед затвердженням +- ✅ Модифікуйте плани за потреби +- ❌ Не використовуйте для простих завдань + +### Розширене мислення +- ✅ Використовуйте для архітектурних рішень +- ✅ Використовуйте для вирішення складних проблем +- ✅ Переглядайте процес мислення +- ❌ Не використовуйте для простих запитів + +### Фонові завдання +- ✅ Використовуйте для тривалих операцій +- ✅ Моніторте прогрес завдань +- ✅ Коректно обробляйте помилки завдань +- ❌ Не запускайте занадто багато паралельних завдань + +### Дозволи +- ✅ Використовуйте `plan` для ревʼю коду (тільки читання) +- ✅ Використовуйте `default` для інтерактивної розробки +- ✅ Використовуйте `acceptEdits` для автоматизованих робочих процесів +- ✅ Використовуйте `auto` для автономної роботи із запобіжниками безпеки +- ❌ Не використовуйте `bypassPermissions` без крайньої необхідності + +### Сесії +- ✅ Використовуйте окремі сесії для різних завдань +- ✅ Зберігайте важливі стани сесій +- ✅ Очищайте старі сесії +- ❌ Не змішуйте неповʼязану роботу в одній сесії + +--- + +## Додаткові ресурси + +Для отримання додаткової інформації про Claude Code та повʼязані функції: + +- [Офіційна документація інтерактивного режиму](https://code.claude.com/docs/en/interactive-mode) +- [Офіційна документація Headless Mode](https://code.claude.com/docs/en/headless) +- [Довідник CLI](https://code.claude.com/docs/en/cli-reference) +- [Посібник з контрольних точок](../08-checkpoints/) — Управління сесіями та відкат +- [Слеш-команди](../01-slash-commands/) — Довідник команд +- [Посібник з памʼяті](../02-memory/) — Постійний контекст +- [Посібник з навичок](../03-skills/) — Автономні можливості +- [Посібник з субагентів](../04-subagents/) — Делеговане виконання завдань +- [Посібник з MCP](../05-mcp/) — Доступ до зовнішніх даних +- [Посібник з хуків](../06-hooks/) — Автоматизація на основі подій +- [Посібник з плагінів](../07-plugins/) — Пакетні розширення +- [Офіційна документація запланованих завдань](https://code.claude.com/docs/en/scheduled-tasks) +- [Офіційна документація інтеграції Chrome](https://code.claude.com/docs/en/chrome) +- [Офіційна документація Remote Control](https://code.claude.com/docs/en/remote-control) +- [Офіційна документація клавіатурних скорочень](https://code.claude.com/docs/en/keybindings) +- [Офіційна документація десктопного додатку](https://code.claude.com/docs/en/desktop) +- [Офіційна документація Agent Teams](https://code.claude.com/docs/en/agent-teams) + +--- +**Останнє оновлення**: 9 квітня 2026 +**Версія Claude Code**: 2.1.97 +**Сумісні моделі**: Claude Sonnet 4.6, Claude Opus 4.6, Claude Haiku 4.5 diff --git a/uk/10-cli/README.md b/uk/10-cli/README.md new file mode 100644 index 0000000..403b187 --- /dev/null +++ b/uk/10-cli/README.md @@ -0,0 +1,841 @@ + + + + + + + Claude How To + + +# Довідник CLI + +## Огляд + +Claude Code CLI (інтерфейс командного рядка — основний інструмент для роботи з терміналом) — це головний спосіб взаємодії з Claude Code. Він надає потужні опції для виконання запитів, управління сесіями, конфігурації моделей та інтеграції Claude у ваші робочі процеси розробки. + +## Архітектура + +```mermaid +graph TD + A["User Terminal"] -->|"claude [options] [query]"| B["Claude Code CLI"] + B -->|Interactive| C["REPL Mode"] + B -->|"--print"| D["Print Mode (SDK)"] + B -->|"--resume"| E["Session Resume"] + C -->|Conversation| F["Claude API"] + D -->|Single Query| F + E -->|Load Context| F + F -->|Response| G["Output"] + G -->|text/json/stream-json| H["Terminal/Pipe"] +``` + +## CLI-команди + +| Команда | Опис | Приклад | +|---------|------|---------| +| `claude` | Запуск інтерактивного REPL (циклу читання-виконання-виводу) | `claude` | +| `claude "query"` | Запуск REPL з початковим промптом | `claude "explain this project"` | +| `claude -p "query"` | Print-режим — запит і вихід | `claude -p "explain this function"` | +| `cat file \| claude -p "query"` | Обробка вмісту через pipe (конвеєр) | `cat logs.txt \| claude -p "explain"` | +| `claude -c` | Продовжити останню розмову | `claude -c` | +| `claude -c -p "query"` | Продовжити в print-режимі | `claude -c -p "check for type errors"` | +| `claude -r "" "query"` | Відновити сесію за ID або назвою | `claude -r "auth-refactor" "finish this PR"` | +| `claude update` | Оновити до останньої версії | `claude update` | +| `claude mcp` | Налаштування MCP-серверів | Див. [документацію MCP](../05-mcp/) | +| `claude mcp serve` | Запуск Claude Code як MCP-сервера | `claude mcp serve` | +| `claude agents` | Список усіх налаштованих субагентів | `claude agents` | +| `claude auto-mode defaults` | Вивести стандартні правила auto mode як JSON | `claude auto-mode defaults` | +| `claude remote-control` | Запуск сервера Remote Control | `claude remote-control` | +| `claude plugin` | Управління плагінами (встановлення, увімкнення, вимкнення) | `claude plugin install my-plugin` | +| `claude auth login` | Вхід (підтримує `--email`, `--sso`) | `claude auth login --email user@example.com` | +| `claude auth logout` | Вихід з поточного облікового запису | `claude auth logout` | +| `claude auth status` | Перевірка статусу авторизації (код виходу 0 = увійшов, 1 = ні) | `claude auth status` | + +## Основні прапорці + +| Прапорець | Опис | Приклад | +|-----------|------|---------| +| `-p, --print` | Вивести відповідь без інтерактивного режиму | `claude -p "query"` | +| `-c, --continue` | Завантажити останню розмову | `claude --continue` | +| `-r, --resume` | Відновити конкретну сесію за ID або назвою | `claude --resume auth-refactor` | +| `-v, --version` | Показати номер версії | `claude -v` | +| `-w, --worktree` | Запуск в ізольованому git worktree (робочому дереві) | `claude -w` | +| `-n, --name` | Відображувана назва сесії | `claude -n "auth-refactor"` | +| `--from-pr ` | Відновити сесії, привʼязані до GitHub PR | `claude --from-pr 42` | +| `--remote "task"` | Створити веб-сесію на claude.ai | `claude --remote "implement API"` | +| `--remote-control, --rc` | Інтерактивна сесія з Remote Control | `claude --rc` | +| `--teleport` | Відновити веб-сесію локально | `claude --teleport` | +| `--teammate-mode` | Режим відображення Agent Teams | `claude --teammate-mode tmux` | +| `--bare` | Мінімальний режим (без хуків, навичок, плагінів, MCP, auto memory, CLAUDE.md) | `claude --bare` | +| `--enable-auto-mode` | Розблокувати auto permission mode | `claude --enable-auto-mode` | +| `--channels` | Підписка на MCP channel plugins | `claude --channels discord,telegram` | +| `--chrome` / `--no-chrome` | Увімкнути/вимкнути інтеграцію з браузером Chrome | `claude --chrome` | +| `--effort` | Встановити рівень зусиль мислення | `claude --effort high` | +| `--init` / `--init-only` | Запуск хуків ініціалізації | `claude --init` | +| `--maintenance` | Запуск хуків обслуговування та вихід | `claude --maintenance` | +| `--disable-slash-commands` | Вимкнути всі навички та слеш-команди | `claude --disable-slash-commands` | +| `--no-session-persistence` | Вимкнути збереження сесії (print mode) | `claude -p --no-session-persistence "query"` | + +### Інтерактивний vs Print-режим + +```mermaid +graph LR + A["claude"] -->|Default| B["Interactive REPL"] + A -->|"-p flag"| C["Print Mode"] + B -->|Features| D["Multi-turn conversation
Tab completion
History
Slash commands"] + C -->|Features| E["Single query
Scriptable
Pipeable
JSON output"] +``` + +**Інтерактивний режим** (за замовчуванням): +```bash +# Запуск інтерактивної сесії +claude + +# Запуск з початковим промптом +claude "explain the authentication flow" +``` + +**Print-режим** (неінтерактивний): +```bash +# Один запит, потім вихід +claude -p "what does this function do?" + +# Обробка вмісту файлу +cat error.log | claude -p "explain this error" + +# Ланцюжок з іншими інструментами +claude -p "list todos" | grep "URGENT" +``` + +## Модель та конфігурація + +| Прапорець | Опис | Приклад | +|-----------|------|---------| +| `--model` | Встановити модель (sonnet, opus, haiku або повна назва) | `claude --model opus` | +| `--fallback-model` | Автоматичний фолбек (запасна модель) при перевантаженні | `claude -p --fallback-model sonnet "query"` | +| `--agent` | Вказати агента для сесії | `claude --agent my-custom-agent` | +| `--agents` | Визначити кастомних субагентів через JSON | Див. [Конфігурація агентів](#конфігурація-агентів) | +| `--effort` | Встановити рівень зусиль (low, medium, high, max) | `claude --effort high` | + +### Приклади вибору моделі + +```bash +# Opus 4.6 для складних завдань +claude --model opus "design a caching strategy" + +# Haiku 4.5 для швидких завдань +claude --model haiku -p "format this JSON" + +# Повна назва моделі +claude --model claude-sonnet-4-6-20250929 "review this code" + +# З фолбеком для надійності +claude -p --model opus --fallback-model sonnet "analyze architecture" + +# opusplan (Opus планує, Sonnet виконує) +claude --model opusplan "design and implement the caching layer" +``` + +## Кастомізація системного промпта + +| Прапорець | Опис | Приклад | +|-----------|------|---------| +| `--system-prompt` | Замінити весь стандартний промпт | `claude --system-prompt "You are a Python expert"` | +| `--system-prompt-file` | Завантажити промпт з файлу (print mode) | `claude -p --system-prompt-file ./prompt.txt "query"` | +| `--append-system-prompt` | Додати до стандартного промпта | `claude --append-system-prompt "Always use TypeScript"` | + +### Приклади системного промпта + +```bash +# Повністю кастомна персона +claude --system-prompt "You are a senior security engineer. Focus on vulnerabilities." + +# Додавання конкретних інструкцій +claude --append-system-prompt "Always include unit tests with code examples" + +# Завантаження складного промпта з файлу +claude -p --system-prompt-file ./prompts/code-reviewer.txt "review main.py" +``` + +### Порівняння прапорців системного промпта + +| Прапорець | Поведінка | Інтерактивний | Print | +|-----------|----------|---------------|-------| +| `--system-prompt` | Замінює весь стандартний системний промпт | ✅ | ✅ | +| `--system-prompt-file` | Замінює промптом з файлу | ❌ | ✅ | +| `--append-system-prompt` | Додає до стандартного системного промпта | ✅ | ✅ | + +**Використовуйте `--system-prompt-file` лише в print-режимі. Для інтерактивного режиму використовуйте `--system-prompt` або `--append-system-prompt`.** + +## Управління інструментами та дозволами + +| Прапорець | Опис | Приклад | +|-----------|------|---------| +| `--tools` | Обмежити доступні вбудовані інструменти | `claude -p --tools "Bash,Edit,Read" "query"` | +| `--allowedTools` | Інструменти, що виконуються без запиту дозволу | `"Bash(git log:*)" "Read"` | +| `--disallowedTools` | Інструменти, видалені з контексту | `"Bash(rm:*)" "Edit"` | +| `--dangerously-skip-permissions` | Пропустити всі запити дозволів | `claude --dangerously-skip-permissions` | +| `--permission-mode` | Починати у вказаному режимі дозволів | `claude --permission-mode auto` | +| `--permission-prompt-tool` | MCP-інструмент для обробки дозволів | `claude -p --permission-prompt-tool mcp_auth "query"` | +| `--enable-auto-mode` | Розблокувати auto permission mode | `claude --enable-auto-mode` | + +### Приклади дозволів + +```bash +# Режим тільки для читання — код-рев'ю +claude --permission-mode plan "review this codebase" + +# Обмеження до безпечних інструментів +claude --tools "Read,Grep,Glob" -p "find all TODO comments" + +# Дозволити конкретні git-команди без запитів +claude --allowedTools "Bash(git status:*)" "Bash(git log:*)" + +# Заблокувати небезпечні операції +claude --disallowedTools "Bash(rm -rf:*)" "Bash(git push --force:*)" +``` + +## Вивід та формат + +| Прапорець | Опис | Опції | Приклад | +|-----------|------|-------|---------| +| `--output-format` | Формат виводу (print mode) | `text`, `json`, `stream-json` | `claude -p --output-format json "query"` | +| `--input-format` | Формат вводу (print mode) | `text`, `stream-json` | `claude -p --input-format stream-json` | +| `--verbose` | Увімкнути детальне логування | | `claude --verbose` | +| `--include-partial-messages` | Включити потокові (streaming) події | Потребує `stream-json` | `claude -p --output-format stream-json --include-partial-messages "query"` | +| `--json-schema` | Отримати валідований JSON за схемою | | `claude -p --json-schema '{"type":"object"}' "query"` | +| `--max-budget-usd` | Максимальні витрати для print mode | | `claude -p --max-budget-usd 5.00 "query"` | + +### Приклади формату виводу + +```bash +# Звичайний текст (за замовчуванням) +claude -p "explain this code" + +# JSON для програмного використання +claude -p --output-format json "list all functions in main.py" + +# Потоковий JSON для обробки в реальному часі +claude -p --output-format stream-json "generate a long report" + +# Структурований вивід із валідацією за схемою +claude -p --json-schema '{"type":"object","properties":{"bugs":{"type":"array"}}}' \ + "find bugs in this code and return as JSON" +``` + +## Робочий простір та каталог + +| Прапорець | Опис | Приклад | +|-----------|------|---------| +| `--add-dir` | Додати додаткові робочі каталоги | `claude --add-dir ../apps ../lib` | +| `--setting-sources` | Джерела налаштувань через кому | `claude --setting-sources user,project` | +| `--settings` | Завантажити налаштування з файлу або JSON | `claude --settings ./settings.json` | +| `--plugin-dir` | Завантажити плагіни з каталогу (повторюваний) | `claude --plugin-dir ./my-plugin` | + +### Приклад роботи з кількома каталогами + +```bash +# Робота в кількох каталогах проєкту одночасно +claude --add-dir ../frontend ../backend ../shared "find all API endpoints" + +# Завантаження кастомних налаштувань +claude --settings '{"model":"opus","verbose":true}' "complex task" +``` + +## Конфігурація MCP + +| Прапорець | Опис | Приклад | +|-----------|------|---------| +| `--mcp-config` | Завантажити MCP-сервери з JSON | `claude --mcp-config ./mcp.json` | +| `--strict-mcp-config` | Використовувати тільки вказану MCP-конфігурацію | `claude --strict-mcp-config --mcp-config ./mcp.json` | +| `--channels` | Підписка на MCP channel plugins | `claude --channels discord,telegram` | + +### Приклади MCP + +```bash +# Завантаження GitHub MCP-сервера +claude --mcp-config ./github-mcp.json "list open PRs" + +# Суворий режим — тільки вказані сервери +claude --strict-mcp-config --mcp-config ./production-mcp.json "deploy to staging" +``` + +## Управління сесіями + +| Прапорець | Опис | Приклад | +|-----------|------|---------| +| `--session-id` | Використовувати конкретний ID сесії (UUID) | `claude --session-id "550e8400-..."` | +| `--fork-session` | Створити нову сесію при відновленні | `claude --resume abc123 --fork-session` | + +### Приклади сесій + +```bash +# Продовжити останню розмову +claude -c + +# Відновити іменовану сесію +claude -r "feature-auth" "continue implementing login" + +# Форк сесії для експериментів +claude --resume feature-auth --fork-session "try alternative approach" + +# Використання конкретного ID сесії +claude --session-id "550e8400-e29b-41d4-a716-446655440000" "continue" +``` + +### Форк сесії + +Створення відгалуження від існуючої сесії для експериментів: + +```bash +# Форк сесії для альтернативного підходу +claude --resume abc123 --fork-session "try alternative implementation" + +# Форк з кастомним повідомленням +claude -r "feature-auth" --fork-session "test with different architecture" +``` + +**Випадки використання:** +- Спроба альтернативних реалізацій без втрати оригінальної сесії +- Паралельне експериментування з різними підходами +- Створення відгалужень від успішної роботи для варіацій +- Тестування зламуючих змін (breaking changes) без впливу на основну сесію + +Оригінальна сесія залишається без змін, а форк стає новою незалежною сесією. + +## Розширені функції + +| Прапорець | Опис | Приклад | +|-----------|------|---------| +| `--chrome` | Увімкнути інтеграцію з браузером Chrome | `claude --chrome` | +| `--no-chrome` | Вимкнути інтеграцію з Chrome | `claude --no-chrome` | +| `--ide` | Автопідключення до IDE, якщо доступна | `claude --ide` | +| `--max-turns` | Обмежити кількість агентних кроків (неінтерактивний режим) | `claude -p --max-turns 3 "query"` | +| `--debug` | Увімкнути режим налагодження з фільтрацією | `claude --debug "api,mcp"` | +| `--enable-lsp-logging` | Увімкнути детальне логування LSP | `claude --enable-lsp-logging` | +| `--betas` | Beta-заголовки для API-запитів | `claude --betas interleaved-thinking` | +| `--plugin-dir` | Завантажити плагіни з каталогу (повторюваний) | `claude --plugin-dir ./my-plugin` | +| `--enable-auto-mode` | Розблокувати auto permission mode | `claude --enable-auto-mode` | +| `--effort` | Встановити рівень зусиль мислення | `claude --effort high` | +| `--bare` | Мінімальний режим (без хуків, навичок, плагінів, MCP, auto memory, CLAUDE.md) | `claude --bare` | +| `--channels` | Підписка на MCP channel plugins | `claude --channels discord` | +| `--tmux` | Створити tmux-сесію для worktree | `claude --tmux` | +| `--fork-session` | Створити новий ID сесії при відновленні | `claude --resume abc --fork-session` | +| `--max-budget-usd` | Максимальні витрати (print mode) | `claude -p --max-budget-usd 5.00 "query"` | +| `--json-schema` | Валідований JSON-вивід | `claude -p --json-schema '{"type":"object"}' "q"` | + +### Приклади розширених функцій + +```bash +# Обмежити автономні дії +claude -p --max-turns 5 "refactor this module" + +# Налагодження API-викликів +claude --debug "api" "test query" + +# Увімкнути інтеграцію з IDE +claude --ide "help me with this file" +``` + +## Конфігурація агентів + +Прапорець `--agents` приймає JSON-обʼєкт, що визначає кастомних субагентів для сесії. + +### Формат JSON для агентів + +```json +{ + "agent-name": { + "description": "Обовʼязково: коли викликати цього агента", + "prompt": "Обовʼязково: системний промпт для агента", + "tools": ["Необовʼязково", "масив", "інструментів"], + "model": "необовʼязково: sonnet|opus|haiku" + } +} +``` + +**Обовʼязкові поля:** +- `description` — опис природною мовою, коли використовувати цього агента +- `prompt` — системний промпт, що визначає роль та поведінку агента + +**Необовʼязкові поля:** +- `tools` — масив доступних інструментів (якщо не вказано, успадковує всі) + - Формат: `["Read", "Grep", "Glob", "Bash"]` +- `model` — модель: `sonnet`, `opus` або `haiku` + +### Повний приклад агентів + +```json +{ + "code-reviewer": { + "description": "Expert code reviewer. Use proactively after code changes.", + "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.", + "tools": ["Read", "Grep", "Glob", "Bash"], + "model": "sonnet" + }, + "debugger": { + "description": "Debugging specialist for errors and test failures.", + "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes.", + "tools": ["Read", "Edit", "Bash", "Grep"], + "model": "opus" + }, + "documenter": { + "description": "Documentation specialist for generating guides.", + "prompt": "You are a technical writer. Create clear, comprehensive documentation.", + "tools": ["Read", "Write"], + "model": "haiku" + } +} +``` + +### Приклади команд з агентами + +```bash +# Визначення кастомних агентів інлайн +claude --agents '{ + "security-auditor": { + "description": "Security specialist for vulnerability analysis", + "prompt": "You are a security expert. Find vulnerabilities and suggest fixes.", + "tools": ["Read", "Grep", "Glob"], + "model": "opus" + } +}' "audit this codebase for security issues" + +# Завантаження агентів з файлу +claude --agents "$(cat ~/.claude/agents.json)" "review the auth module" + +# Комбінація з іншими прапорцями +claude -p --agents "$(cat agents.json)" --model sonnet "analyze performance" +``` + +### Пріоритет агентів + +При наявності кількох визначень агентів вони завантажуються в такому порядку пріоритету: +1. **CLI-визначені** (прапорець `--agents`) — для конкретної сесії +2. **Рівень користувача** (`~/.claude/agents/`) — для всіх проєктів +3. **Рівень проєкту** (`.claude/agents/`) — для поточного проєкту + +CLI-визначені агенти перевизначають агентів рівня користувача та проєкту на час сесії. + +--- + +## Високоцінні сценарії використання + +### 1. Інтеграція CI/CD + +Використання Claude Code у CI/CD-пайплайнах (конвеєрах безперервної інтеграції/доставки) для автоматизованого код-рев'ю, тестування та документації. + +**Приклад GitHub Actions:** + +```yaml +name: AI Code Review + +on: [pull_request] + +jobs: + review: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Install Claude Code + run: npm install -g @anthropic-ai/claude-code + + - name: Run Code Review + env: + ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} + run: | + claude -p --output-format json \ + --max-turns 1 \ + "Review the changes in this PR for: + - Security vulnerabilities + - Performance issues + - Code quality + Output as JSON with 'issues' array" > review.json + + - name: Post Review Comment + uses: actions/github-script@v7 + with: + script: | + const fs = require('fs'); + const review = JSON.parse(fs.readFileSync('review.json', 'utf8')); + // Обробка та публікація коментарів рев'ю +``` + +**Пайплайн Jenkins:** + +```groovy +pipeline { + agent any + stages { + stage('AI Review') { + steps { + sh ''' + claude -p --output-format json \ + --max-turns 3 \ + "Analyze test coverage and suggest missing tests" \ + > coverage-analysis.json + ''' + } + } + } +} +``` + +### 2. Pipe-обробка скриптів + +Обробка файлів, журналів та даних через Claude для аналізу. + +**Аналіз журналів:** + +```bash +# Аналіз журналів помилок +tail -1000 /var/log/app/error.log | claude -p "summarize these errors and suggest fixes" + +# Пошук патернів у журналах доступу +cat access.log | claude -p "identify suspicious access patterns" + +# Аналіз git-історії +git log --oneline -50 | claude -p "summarize recent development activity" +``` + +**Обробка коду:** + +```bash +# Рев'ю конкретного файлу +cat src/auth.ts | claude -p "review this authentication code for security issues" + +# Генерація документації +cat src/api/*.ts | claude -p "generate API documentation in markdown" + +# Пошук TODO та пріоритезація +grep -r "TODO" src/ | claude -p "prioritize these TODOs by importance" +``` + +### 3. Мультисесійні робочі процеси + +Управління складними проєктами з кількома потоками розмов. + +```bash +# Запуск сесії для гілки функції +claude -r "feature-auth" "let's implement user authentication" + +# Пізніше — продовження сесії +claude -r "feature-auth" "add password reset functionality" + +# Форк для альтернативного підходу +claude --resume feature-auth --fork-session "try OAuth instead" + +# Переключення між різними сесіями функцій +claude -r "feature-payments" "continue with Stripe integration" +``` + +### 4. Кастомна конфігурація агентів + +Визначення спеціалізованих агентів для робочих процесів вашої команди. + +```bash +# Збереження конфігурації агентів у файл +cat > ~/.claude/agents.json << 'EOF' +{ + "reviewer": { + "description": "Code reviewer for PR reviews", + "prompt": "Review code for quality, security, and maintainability.", + "model": "opus" + }, + "documenter": { + "description": "Documentation specialist", + "prompt": "Generate clear, comprehensive documentation.", + "model": "sonnet" + }, + "refactorer": { + "description": "Code refactoring expert", + "prompt": "Suggest and implement clean code refactoring.", + "tools": ["Read", "Edit", "Glob"] + } +} +EOF + +# Використання агентів у сесії +claude --agents "$(cat ~/.claude/agents.json)" "review the auth module" +``` + +### 5. Пакетна обробка + +Обробка кількох запитів з однаковими налаштуваннями. + +```bash +# Обробка кількох файлів +for file in src/*.ts; do + echo "Processing $file..." + claude -p --model haiku "summarize this file: $(cat $file)" >> summaries.md +done + +# Пакетне код-рев'ю +find src -name "*.py" -exec sh -c ' + echo "## $1" >> review.md + cat "$1" | claude -p "brief code review" >> review.md +' _ {} \; + +# Генерація тестів для всіх модулів +for module in $(ls src/modules/); do + claude -p "generate unit tests for src/modules/$module" > "tests/$module.test.ts" +done +``` + +### 6. Безпечна розробка + +Використання контролю дозволів для безпечної роботи. + +```bash +# Аудит безпеки тільки для читання +claude --permission-mode plan \ + --tools "Read,Grep,Glob" \ + "audit this codebase for security vulnerabilities" + +# Блокування небезпечних команд +claude --disallowedTools "Bash(rm:*)" "Bash(curl:*)" "Bash(wget:*)" \ + "help me clean up this project" + +# Обмежена автоматизація +claude -p --max-turns 2 \ + --allowedTools "Read" "Glob" \ + "find all hardcoded credentials" +``` + +### 7. JSON API інтеграція + +Використання Claude як програмного API для ваших інструментів з парсингом через `jq`. + +```bash +# Структурований аналіз +claude -p --output-format json \ + --json-schema '{"type":"object","properties":{"functions":{"type":"array"},"complexity":{"type":"string"}}}' \ + "analyze main.py and return function list with complexity rating" + +# Інтеграція з jq для обробки +claude -p --output-format json "list all API endpoints" | jq '.endpoints[]' + +# Використання в скриптах +RESULT=$(claude -p --output-format json "is this code secure? answer with {secure: boolean, issues: []}" < code.py) +if echo "$RESULT" | jq -e '.secure == false' > /dev/null; then + echo "Security issues found!" + echo "$RESULT" | jq '.issues[]' +fi +``` + +### Приклади парсингу jq + +Парсинг та обробка JSON-виводу Claude за допомогою `jq`: + +```bash +# Витяг конкретних полів +claude -p --output-format json "analyze this code" | jq '.result' + +# Фільтрація елементів масиву +claude -p --output-format json "list issues" | jq -r '.issues[] | select(.severity=="high")' + +# Витяг кількох полів +claude -p --output-format json "describe the project" | jq -r '.{name, version, description}' + +# Конвертація в CSV +claude -p --output-format json "list functions" | jq -r '.functions[] | [.name, .lineCount] | @csv' + +# Умовна обробка +claude -p --output-format json "check security" | jq 'if .vulnerabilities | length > 0 then "UNSAFE" else "SAFE" end' + +# Витяг вкладених значень +claude -p --output-format json "analyze performance" | jq '.metrics.cpu.usage' + +# Обробка всього масиву +claude -p --output-format json "find todos" | jq '.todos | length' + +# Трансформація виводу +claude -p --output-format json "list improvements" | jq 'map({title: .title, priority: .priority})' +``` + +--- + +## Моделі + +Claude Code підтримує кілька моделей з різними можливостями: + +| Модель | ID | Контекстне вікно | Примітки | +|--------|-----|-----------------|----------| +| Opus 4.6 | `claude-opus-4-6` | 1M токенів | Найпотужніша, адаптивні рівні зусиль | +| Sonnet 4.6 | `claude-sonnet-4-6` | 1M токенів | Баланс швидкості та можливостей | +| Haiku 4.5 | `claude-haiku-4-5` | 1M токенів | Найшвидша, оптимальна для швидких завдань | + +### Вибір моделі + +```bash +# Використання коротких назв +claude --model opus "complex architectural review" +claude --model sonnet "implement this feature" +claude --model haiku -p "format this JSON" + +# Використання alias opusplan (Opus планує, Sonnet виконує) +claude --model opusplan "design and implement the API" + +# Перемикання на швидкий режим під час сесії +/fast +``` + +### Рівні зусиль (Opus 4.6) + +Opus 4.6 підтримує адаптивне міркування з рівнями зусиль: + +```bash +# Через прапорець CLI +claude --effort high "complex review" + +# Через слеш-команду +/effort high + +# Через змінну оточення +export CLAUDE_CODE_EFFORT_LEVEL=high # low, medium, high або max (лише Opus 4.6) +``` + +Ключове слово "ultrathink" у промптах активує глибоке міркування. Рівень `max` — ексклюзивний для Opus 4.6. + +--- + +## Ключові змінні оточення + +| Змінна | Опис | +|--------|------| +| `ANTHROPIC_API_KEY` | API-ключ для автентифікації | +| `ANTHROPIC_MODEL` | Перевизначення стандартної моделі | +| `ANTHROPIC_CUSTOM_MODEL_OPTION` | Кастомна опція моделі для API | +| `ANTHROPIC_DEFAULT_OPUS_MODEL` | Перевизначення стандартного ID моделі Opus | +| `ANTHROPIC_DEFAULT_SONNET_MODEL` | Перевизначення стандартного ID моделі Sonnet | +| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | Перевизначення стандартного ID моделі Haiku | +| `MAX_THINKING_TOKENS` | Бюджет токенів розширеного мислення | +| `CLAUDE_CODE_EFFORT_LEVEL` | Рівень зусиль (`low`/`medium`/`high`/`max`) | +| `CLAUDE_CODE_SIMPLE` | Мінімальний режим, встановлюється прапорцем `--bare` | +| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | Вимкнути автоматичне оновлення CLAUDE.md | +| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | Вимкнути виконання фонових завдань | +| `CLAUDE_CODE_DISABLE_CRON` | Вимкнути заплановані/cron-завдання | +| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | Вимкнути git-інструкції | +| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | Вимкнути оновлення заголовка терміналу | +| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | Вимкнути контекстне вікно 1M токенів | +| `CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK` | Вимкнути фолбек без стрімінгу | +| `CLAUDE_CODE_ENABLE_TASKS` | Увімкнути функцію списку завдань | +| `CLAUDE_CODE_TASK_LIST_ID` | Іменований каталог завдань, спільний між сесіями | +| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | Увімкнути/вимкнути пропозиції промптів (`true`/`false`) | +| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | Увімкнути експериментальні Agent Teams | +| `CLAUDE_CODE_NEW_INIT` | Використовувати новий потік ініціалізації | +| `CLAUDE_CODE_SUBAGENT_MODEL` | Модель для виконання субагентів | +| `CLAUDE_CODE_PLUGIN_SEED_DIR` | Каталог для seed-файлів плагінів | +| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | Змінні оточення для видалення з підпроцесів | +| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | Перевизначити відсоток автокомпакції | +| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | Таймаут простою потоку в мілісекундах | +| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | Бюджет символів для інструментів слеш-команд | +| `ENABLE_TOOL_SEARCH` | Увімкнути пошук інструментів | +| `MAX_MCP_OUTPUT_TOKENS` | Максимум токенів для виводу MCP-інструмента | + +--- + +## Швидкий довідник + +### Найпоширеніші команди + +```bash +# Інтерактивна сесія +claude + +# Швидке питання +claude -p "how do I..." + +# Продовжити розмову +claude -c + +# Обробити файл +cat file.py | claude -p "review this" + +# JSON-вивід для скриптів +claude -p --output-format json "query" +``` + +### Комбінації прапорців + +| Сценарій | Команда | +|----------|---------| +| Швидке код-рев'ю | `cat file \| claude -p "review"` | +| Структурований вивід | `claude -p --output-format json "query"` | +| Безпечне дослідження | `claude --permission-mode plan` | +| Автономність з безпекою | `claude --enable-auto-mode --permission-mode auto` | +| CI/CD інтеграція | `claude -p --max-turns 3 --output-format json` | +| Відновлення роботи | `claude -r "session-name"` | +| Кастомна модель | `claude --model opus "complex task"` | +| Мінімальний режим | `claude --bare "quick query"` | +| Ліміт бюджету | `claude -p --max-budget-usd 2.00 "analyze code"` | + +--- + +## Усунення несправностей + +### Команда не знайдена + +**Проблема:** `claude: command not found` + +**Рішення:** +- Встановіть Claude Code: `npm install -g @anthropic-ai/claude-code` +- Перевірте, що PATH включає глобальний bin-каталог npm +- Спробуйте запуск з повним шляхом: `npx claude` + +### Проблеми з API-ключем + +**Проблема:** Помилка автентифікації + +**Рішення:** +- Встановіть API-ключ: `export ANTHROPIC_API_KEY=your-key` +- Перевірте валідність ключа та наявність достатнього балансу +- Перевірте дозволи ключа для запитуваної моделі + +### Сесія не знайдена + +**Проблема:** Неможливо відновити сесію + +**Рішення:** +- Перегляньте доступні сесії, щоб знайти правильну назву/ID +- Сесії можуть закінчуватися після періоду неактивності +- Використовуйте `-c` для продовження останньої сесії + +### Проблеми з форматом виводу + +**Проблема:** JSON-вивід пошкоджений + +**Рішення:** +- Використовуйте `--json-schema` для примусового дотримання структури +- Додайте явні інструкції щодо JSON у промпті +- Використовуйте `--output-format json` (а не просто просіть JSON у промпті) + +### Відмова в дозволі + +**Проблема:** Виконання інструменту заблоковане + +**Рішення:** +- Перевірте налаштування `--permission-mode` +- Перегляньте прапорці `--allowedTools` та `--disallowedTools` +- Використовуйте `--dangerously-skip-permissions` для автоматизації (з обережністю) + +--- + +## Додаткові ресурси + +- **[Офіційний довідник CLI](https://code.claude.com/docs/en/cli-reference)** — повний довідник команд +- **[Документація Headless Mode](https://code.claude.com/docs/en/headless)** — автоматизоване виконання +- **[Слеш-команди](../01-slash-commands/)** — кастомні ярлики в Claude +- **[Посібник з памʼяті](../02-memory/)** — постійний контекст через CLAUDE.md +- **[Протокол MCP](../05-mcp/)** — інтеграція зовнішніх інструментів +- **[Розширені функції](../09-advanced-features/)** — режим планування, розширене мислення +- **[Посібник субагентів](../04-subagents/)** — делеговане виконання завдань + +--- + +*Частина серії посібників [Claude How To](../)* + +--- +**Останнє оновлення**: 9 квітня 2026 +**Версія Claude Code**: 2.1.97 +**Сумісні моделі**: Claude Sonnet 4.6, Claude Opus 4.6, Claude Haiku 4.5