---
title: "Як працює Claude Code"
url: "https://romankryvolapov.com/uk/claude-code-how-it-works/"
description: "Claude Code зсередини: цикл агента, інструменти читання, правки й пошуку, контекст і його стиснення, пам'ять, правила, скіли, субагенти, хуки, MCP і плагіни, що лежить у теці .claude і на диску, дозволи, пісочниця, браузер і керування комп'ютером, фонові та хмарні сесії, робота на віддаленій машині та порівняння з іншими харнесами."
language: uk
published: 2026-11-19
updated: 2026-11-19
---
**Привіт!**

У мене на сайті вже є три статті про Claude Code: [довідник команд і налаштувань](/uk/claude-code-commands-and-settings/), [розбір хуків](/uk/claude-code-hooks/) і [практики роботи](/uk/claude-code-best-practices/). Усі три відповідають на питання «що натиснути і як налаштувати». Ця відповідає на інше питання: як воно влаштоване всередині.

Навіщо це знати. Claude Code виглядає як чат у терміналі, але за чатом стоїть доволі велика машина: десятки інструментів, кілька видів пам'яті, правила, скіли, субагенти, хуки, дозволи, пісочниця, фонові та хмарні сесії. Поки не розумієш, як ці частини пов'язані, налаштування здаються набором випадкових перемикачів. Коли розумієш, більшість із них стають очевидними.

Стаття йде від простого до складного. Спочатку — що відбувається між вашим повідомленням і відповіддю. Потім — чим агент читає, править і шукає. Потім — усе, що живе в теці проєкту і в домашній теці на диску. Потім — безпека та ізоляція. І наприкінці — де все це можна запускати: від ноутбука до віртуальної машини в мережі, і чим Claude Code відрізняється від схожих інструментів.

Усе описане звірено з офіційною документацією та з установленою в мене версією 2.1.328 у листопаді 2026 року. Claude Code виходить кілька разів на тиждень, тому дрібні деталі змінюються швидко, а будова загалом — повільно. Шляхи на диску я показую так, як вони виглядають у мене на Windows, а поруч кажу, де це на macOS і Linux.

## Модель і харнес: хто що робить

Почнемо з головного розподілу. У Claude Code дві частини, і їх постійно плутають.

**Модель** — це нейромережа Claude на серверах Anthropic. Вона вміє одне: отримати текст і видати текст. Вона не бачить ваш диск, не може запустити команду і нічого не пам'ятає між запитами.

**Харнес** (harness, «обв'язка») — це програма `claude`, яка працює на вашому комп'ютері. Саме її ви встановлюєте. Вона читає файли, запускає команди, показує інтерфейс, питає дозволи, зберігає історію і вирішує, що надіслати моделі в кожному запиті.

Модель думає, харнес робить. Пов'язані вони через **інструменти** (tools). Інструмент — це функція, яку харнес уміє виконати: «прочитай файл», «запусти команду», «знайди рядок». Харнес описує моделі список інструментів, а модель у відповіді може написати не звичайний текст, а прохання: «викличи інструмент читання з таким-то шляхом». Харнес виконує прохання і повертає моделі результат.

```text
        ваш комп'ютер                          сервери Anthropic
┌──────────────────────────────┐            ┌────────────────────┐
│  харнес (програма claude)    │  запит →   │                    │
│                              │            │   модель Claude    │
│  інтерфейс, дозволи,         │ ← відповідь│                    │
│  історія, налаштування       │            └────────────────────┘
│            │                 │
│      інструменти             │
│  ┌─────────┬───────┬───────┐ │
│  │ файли   │ shell │ веб   │ │
│  └─────────┴───────┴───────┘ │
└──────────────────────────────┘
```

З цієї схеми випливає висновок, який знадобиться далі багато разів. Ваш код не «завантажується в Claude». Він лежить на диску, і на сервери йде лише те, що харнес поклав у запит: ваші повідомлення, прочитані файли, вивід команд. Решту модель не бачила.

І другий висновок. Одна й та сама модель у різних харнесах працює по-різному, бо в них різні інструменти, різні системні інструкції та по-різному влаштована робота з контекстом. Наскільки сильно це впливає на результат, я розбирав у [порівнянні харнесів](/uk/ai-agent-harnesses/).

## Цикл агента: що відбувається після Enter

Звичайний чат влаштований так: питання — відповідь. Агент влаштований інакше: питання — багато кроків — відповідь. Ці кроки називають циклом агента.

Розберемо на прикладі. Ви написали: «тест авторизації падає, полагодь».

1. Харнес збирає запит: системні інструкції, описи інструментів, інструкції проєкту, вашу фразу. Надсилає моделі.
2. Модель відповідає не текстом, а викликом інструмента: «запусти тести авторизації».
3. Харнес перевіряє, чи можна це робити без дозволу. Якщо не можна — питає вас. Потім запускає команду і отримує вивід.
4. Харнес надсилає моделі новий запит: усе попереднє плюс вивід тестів.
5. Модель бачить помилку і просить знайти в коді функцію, що впала. Харнес шукає і повертає результат.
6. Модель просить прочитати файл. Потім просить замінити в ньому один рядок на інший. Потім знову запустити тести.
7. Тести пройшли. Модель відповідає звичайним текстом: що було не так і що вона виправила. Викликів інструментів у відповіді немає — хід закінчено.

Документація описує цей цикл трьома фазами: **зібрати контекст → діяти → перевірити результат**. Фази йдуть не строго по черзі: що робити далі, модель вирішує після кожного кроку, дивлячись на те, що повернув попередній.

Три деталі, які варто знати.

**Кожен запит несе всю розмову цілком.** Модель нічого не пам'ятає між запитами, тому на кроці 6 харнес заново надсилає їй усе з кроку 1. Звідси росте вся тема контексту, стиснення й вартості — про неї нижче.

**Виклики бувають паралельними.** Якщо моделі треба прочитати п'ять файлів, вона просить усі п'ять в одній відповіді, і харнес виконує їх одночасно.

**Втрутитися можна будь-якої миті.** Esc зупиняє поточний виклик і повертає керування вам. А якщо просто надрукувати повідомлення, поки агент працює, він прочитає його після поточних викликів, у тому самому ході. Це зручний спосіб поправити курс, не уриваючи роботу.

## Що модель бачить на початку сесії

Перед вашим першим повідомленням у запиті вже лежить чимало. Важливо розуміти, що саме, бо кожен рядок там оплачується в кожному запиті й впливає на поведінку.

| Що | Звідки береться | Коли завантажується |
|---|---|---|
| Системний промпт | вбудований у Claude Code | завжди |
| Описи вбудованих інструментів | вбудовані | завжди |
| Відомості про середовище | робоча тека, ОС, гілка git, незакомічені зміни, останні коміти | завжди |
| Інструкції проєкту | файли `CLAUDE.md` і правила без прив'язки до шляхів | завжди |
| Автопам'ять | початок файлу `MEMORY.md` | завжди |
| Список скілів | лише назва й опис кожного | завжди; тіло — за викликом |
| MCP-сервери | лише назви інструментів та інструкції сервера | завжди; схеми — на вимогу |
| Стиль виводу | вибраний output style | якщо заданий |

Тонкість щодо інструкцій проєкту. `CLAUDE.md` не стає частиною системного промпту. Він приходить моделі як повідомлення користувача одразу після системного промпту. Тому це саме інструкції, яких модель зазвичай дотримується, а не жорстка конфігурація. Для того, що має виконуватися завжди і без винятків, є хуки та правила дозволів — механізми харнеса, а не тексту.

Подивитися, із чого складається контекст просто зараз, можна командою `/context`: вона малює сітку і показує, скільки займають інструменти, пам'ять, скіли та сама розмова.

## Інструменти: чим агент працює

Інструментів понад тридцять. Запам'ятовувати всі не треба, але основні корисно знати за назвами: ці самі назви пишуться в правилах дозволів і в хуках.

| Група | Інструменти | Питають дозвіл |
|---|---|---|
| Файли | `Read`, `Edit`, `Write`, `NotebookEdit` | читання — ні, правка — так |
| Пошук | `Grep`, `Glob`, `LSP` | ні |
| Команди | `Bash`, `PowerShell`, `Monitor` | так, крім свідомо безпечних команд |
| Веб | `WebFetch`, `WebSearch` | так |
| Агенти | `Agent`, `SendMessage`, `ListAgents`, `Workflow` | здебільшого ні |
| Планування | `EnterPlanMode`, `ExitPlanMode`, `TaskCreate` та інші, `AskUserQuestion` | ні |
| Розширення | `Skill`, `ToolSearch`, інструменти MCP-серверів | залежить від скіла й сервера |
| Розклад | `CronCreate`, `CronList`, `CronDelete`, `ScheduleWakeup` | ні |
| Робочі копії | `EnterWorktree`, `ExitWorktree` | вхід — так |

Тепер по черзі про ті, з яких складається майже вся робота.

### Читання файлів

Усі приклади цього розділу зняті з маленького навчального проєкту. У ньому п'ять файлів: модуль сесій, два обробники API, тест і зібраний бандл у теці `dist`, яку внесено до `.gitignore`.

```text
demo/
├── .gitignore            node_modules/ і dist/
├── dist/bundle.js
├── src/
│   ├── auth/session.ts
│   └── api/
│       ├── login.ts
│       └── profile.ts
└── tests/session.test.ts
```

Виклик інструмента — це JSON із параметрами: саме в такому вигляді модель його й надсилає, а назву інструмента я підписую над блоком. Переведення рядка всередині значення записується як `\n`, це звичайне правило JSON. Відповіді показано такими, якими їх повернув харнес; довгі абсолютні шляхи скорочено до відносних.

`Read` приймає шлях до файлу й повертає його вміст. Біля кожного рядка ліворуч стоїть його номер:

```json title="виклик Read"
{
  "file_path": "src/auth/session.ts"
}
```

```typescript title="відповідь Read"
1	import { db } from '../db';
2	
3	const TTL = 60 * 60;
4	
5	export function createSession(userId: string) {
6	  const token = crypto.randomUUID();
7	  db.sessions.insert({ token, userId, expiresAt: Date.now() + TTL * 1000 });
8	  return token;
9	}
10	
11	export function findSession(token: string) {
12	  const session = db.sessions.find(token);
13	  if (!session) {
14	    return null;
15	  }
16	  if (session.expiresAt < Date.now()) {
17	    return null;
18	  }
19	  return session;
20	}
```

Номери рядків потрібні моделі, щоб орієнтуватися й посилатися на місце у файлі. До самого файлу вони, звісно, не входять, і під час правки модель мусить їх відкинути.

Великий файл цілком читати не варто. У `Read` є два необов'язкові параметри: з якого рядка почати і скільки рядків узяти. Так агент читає лише потрібну функцію:

```json title="виклик Read"
{
  "file_path": "src/auth/session.ts",
  "offset": 11,
  "limit": 6
}
```

```typescript title="відповідь Read"
11	export function findSession(token: string) {
12	  const session = db.sessions.find(token);
13	  if (!session) {
14	    return null;
15	  }
16	  if (session.expiresAt < Date.now()) {
```

Зазвичай це виглядає так: пошук повідомив, що потрібне міститься в рядку 340 файлу на дві тисячі рядків, і агент читає рядки з 320 по 380, а не весь файл.

Обмеження такі. За один виклик повертається до 25 тисяч токенів. Файл більший за 256 КБ цілком без явної вказівки не читається: агент отримає відмову і прочитає його частинами. Якщо файлу немає, відповідь — звичайна помилка, і модель бачить її як результат виклику:

```text languages="відповідь Read"
File does not exist. Note: your current working directory is D:\projects\demo.
```

На цю підказку про робочу теку варто звернути увагу. Найчастіша причина такої помилки — відносний шлях, порахований не від тієї теки. Тому інструменти роботи з файлами вимагають абсолютних шляхів.

Читає `Read` не лише текст. Картинку (PNG, JPEG, GIF, WebP) модель побачить як зображення: так агент дивиться на скриншоти й макети. PDF читається посторінково, блокнот Jupyter — клітинками разом із виводом. Двійкові формати на кшталт `.xlsx` чи `.zip` інструмент не відкриє: для них агент пише невеликий скрипт.

### Редагування: точна заміна рядка

Це найменш очевидна частина, і на ній варто затриматися.

Агент не переписує файл цілком і не створює патч у форматі diff. Інструмент `Edit` приймає три речі: шлях, старий фрагмент і новий фрагмент. Харнес знаходить у файлі старий фрагмент і замінює його новим.

Найпростіший випадок — змінити один рядок. Сесія має жити добу, а не годину:

```json title="виклик Edit"
{
  "file_path": "src/auth/session.ts",
  "old_string": "const TTL = 60 * 60;",
  "new_string": "const TTL = 60 * 60 * 24;"
}
```

```text languages="відповідь Edit"
The file src/auth/session.ts has been updated successfully.
```

Відповідь коротка: вміст файлу назад не повертається. Модель і так знає, що тепер у файлі, бо сама написала новий фрагмент.

У цієї схеми три правила, і всі три — захист від тихого псування коду. Розберемо кожне на прикладі.

**Правило перше: збіг точний.** Жодних регулярних виразів і «приблизно схоже». Припустімо, модель з пам'яті вирішила, що у файлі написано `const TTL = 3600;`:

```json title="виклик Edit"
{
  "file_path": "src/auth/session.ts",
  "old_string": "const TTL = 3600;",
  "new_string": "const TTL = 86400;"
}
```

```text languages="відповідь Edit"
String to replace not found in file.
String: const TTL = 3600;
```

Правка не застосувалася, файл не зачеплено. Модель бачить помилку, перечитує файл і повторює виклик уже зі справжнім текстом. Те саме станеться, якщо відрізняється бодай один пробіл у відступі або замість пробілів стоїть табуляція. Це дратує, коли дивишся збоку, але альтернатива гірша: «розумна» заміна за приблизним збігом іноді потрапляла б не в те місце, і ви дізналися б про це за тиждень.

**Правило друге: фрагмент має зустрічатися у файлі один раз.** У нашому файлі рядок `return null;` є двічі. Спробуємо замінити його:

```json title="виклик Edit"
{
  "file_path": "src/auth/session.ts",
  "old_string": "    return null;",
  "new_string": "    return undefined;"
}
```

```text languages="відповідь Edit"
Found 2 matches of the string to replace, but replace_all is false.
To replace all occurrences, set replace_all to true. To replace only one
occurrence, please provide more context to uniquely identify the instance.
String:     return null;
```

Харнес не став вгадувати, яке з двох місць мали на увазі. Далі в моделі два шляхи.

Якщо потрібне одне конкретне місце, вона бере в `old_string` більше навколишнього коду — стільки, щоб фрагмент став єдиним. Наприклад, треба видаляти прострочену сесію перед поверненням. Рядок `return null;` модель захоплює разом з умовою над ним:

```json title="виклик Edit"
{
  "file_path": "src/auth/session.ts",
  "old_string": "  if (session.expiresAt < Date.now()) {\n    return null;",
  "new_string": "  if (session.expiresAt < Date.now()) {\n    db.sessions.delete(token);\n    return null;"
}
```

Тепер фрагмент із двох рядків зустрічається у файлі один раз, і правка проходить. Зверніть увагу, що `new_string` повторює незмінені рядки: інструмент не «вставляє рядок», він замінює один шматок тексту іншим.

Якщо ж потрібні всі входження — наприклад, під час перейменування змінної в межах файлу — модель ставить прапорець:

```json title="виклик Edit"
{
  "file_path": "src/auth/session.ts",
  "old_string": "session",
  "new_string": "userSession",
  "replace_all": true
}
```

Тут видно й підступ: така заміна зачепить і `db.sessions`, перетворивши його на `db.userSessions`. Заміна текстова, про синтаксис мови вона нічого не знає. Тому для перейменувань по всьому проєкту агент зазвичай бере інструмент мовного сервера, а не текстову заміну.

**Правило третє: спочатку прочитати, потім правити.** Спершу воно було жорстким: правка файлу, який не читався в цій розмові, відхилялася. Сенс у тому, щоб модель правила те, що реально лежить на диску, а не те, що їй здається. У новітніх моделей вимогу послаблено: якщо вміст уже відомий — з виводу пошуку чи команди `cat` — окреме читання не обов'язкове. На старіших моделях воно потрібне завжди, а для блокнотів Jupyter і для файлів, прочитаних лише частково, — на будь-яких.

Звідси ж випливає ще один захист. Якщо між читанням і правкою файл змінився на диску — ви зберегли його в редакторі або спрацював форматер — фрагмент із `old_string` може вже не знайтися, і правка чесно впаде з помилкою «не знайдено», а не затре ваші зміни.

**Кілька правок в одному файлі** — це кілька викликів поспіль. Кожен наступний працює вже зі зміненим файлом. Тому модель стежить, щоб друга правка не шукала текст, який перша щойно замінила.

Чому не diff. Формат diff вимагає від моделі точно порахувати номери рядків, а в рахунку моделі помиляються. Заміна «знайди цей текст» номерів не потребує взагалі, і помилка в ній завжди гучна: або фрагмент знайшовся рівно один раз, або правки немає.

#### Створення й перезапис: Write

`Write` приймає шлях і повний вміст. Якщо файлу немає, він створюється разом із відсутніми теками. Якщо є — перезаписується цілком.

```json title="виклик Write"
{
  "file_path": "src/auth/cleanup.ts",
  "content": "import { db } from '../db';\n\nexport function removeExpired() {\n  db.sessions.deleteWhere((s) => s.expiresAt < Date.now());\n}\n"
}
```

Дописати в кінець файлу цим інструментом не можна: він завжди кладе весь текст. Тому для правки наявного файлу майже завжди обирається `Edit`, і причин дві. По-перше, ціна: щоб змінити один рядок у файлі на тисячу рядків через `Write`, моделі довелося б заново надрукувати всю тисячу. По-друге, ризик: передруковуючи великий файл, модель може непомітно втратити або «покращити» шматок, який чіпати не просили. `Edit` фізично не може змінити нічого, крім названого фрагмента.

`Write` залишається для двох випадків: новий файл і повне переписування, коли від старого вмісту майже нічого не лишається.

#### Видалення, перейменування, перенесення

Окремих інструментів для цього немає. Видалити файл, перейменувати його чи перенести в іншу теку агент може лише командою оболонки: `rm`, `mv`, `git mv`. Це важливо з двох причин. Такі дії йдуть через дозволи для команд, а не для правок. І відкат за чекпоінтами їх не бачить — про це в розділі про відкат.

#### Що ви бачите в інтерфейсі

Кожну правку харнес показує як звичний diff: червоним прибрані рядки, зеленим додані. У ручному режимі під ним питання з трьома варіантами: застосувати, застосувати й більше не питати про правки в цій сесії, відмовити й пояснити агентові, що не так. Відмова з поясненням — нормальний робочий інструмент: агент отримує ваш текст як результат виклику і робить інакше.

Якщо відкрито IDE з розширенням, diff показується у вікні редактора, а не в терміналі.

А перед кожною правкою харнес зберігає попередню версію файлу — про це в розділі про відкат.

### Пошук: індексу немає

Багато хто чекає, що агент під час першого запуску «індексує проєкт»: будує базу ембедингів чи граф коду, як це роблять деякі редактори. Claude Code цього не робить. Постійного індексу в нього немає.

Натомість агент шукає так само, як шукала б людина в терміналі, тільки швидше й наполегливіше:

Інструментів пошуку два: один шукає файли за назвою, інший — за вмістом.

**`Glob` — пошук за назвою.** Приймає маску шляху й повертає список файлів:

```json title="виклик Glob"
{
  "pattern": "**/*.ts"
}
```

```text languages="відповідь Glob"
src/auth/session.ts
src/api/login.ts
src/api/profile.ts
tests/session.test.ts
```

Дві зірочки означають «будь-яка глибина вкладеності». Результат відсортовано за часом зміни, і видається не більше ста файлів. Типові маски: `src/**/*.test.ts` — усі тести, `**/package.json` — усі пакети монорепозиторію, `**/*config*` — усе, що схоже на конфігурацію.

**`Grep` — пошук за вмістом.** Приймає регулярний вираз. Усередині це ripgrep, дуже швидка утиліта пошуку. У нього три режими, і агент вибирає їх по черзі, від дешевого до докладного.

Перший режим — лише назви файлів. Він увімкнений типово і майже нічого не коштує за токенами. Питання «де взагалі використовується ця функція»:

```json title="виклик Grep"
{
  "pattern": "findSession"
}
```

```text languages="відповідь Grep"
Found 3 files
tests/session.test.ts
src/api/profile.ts
src/auth/session.ts
```

Зверніть увагу: у теці `dist` лежить бандл, де це слово теж є, але у видачу він не потрапив. Теку внесено до `.gitignore`, а `Grep` ігноровані файли пропускає.

Другий режим — самі рядки з номерами та сусідніми рядками для контексту. Тут же пошук звужується маскою: лише вихідники, без тестів. Дужку у зразку екрановано, бо це регулярний вираз:

```json title="виклик Grep"
{
  "pattern": "findSession\\(",
  "glob": "src/**/*.ts",
  "output_mode": "content",
  "-C": 1
}
```

```text languages="відповідь Grep"
src/api/profile.ts-3-export function profile(token: string) {
src/api/profile.ts:4:  const session = findSession(token);
src/api/profile.ts-5-  return session ? { userId: session.userId } : null;
--
src/auth/session.ts-10-
src/auth/session.ts:11:export function findSession(token: string) {
src/auth/session.ts-12-  const session = db.sessions.find(token);
```

Рядок із двокрапками — збіг, рядки з дефісами — контекст навколо. Параметр `-C: 1` означає один рядок до і один після. Цього часто досить, щоб зрозуміти місце, не відкриваючи файл.

Третій режим — кількість. Питання «скільки разів це зустрічається»:

```json title="виклик Grep"
{
  "pattern": "return null",
  "output_mode": "count"
}
```

```text languages="відповідь Grep"
src/auth/session.ts:2

Found 2 total occurrences across 1 file.
```

Так агент оцінює масштаб до початку роботи: одна справа поправити два місця, інша — двісті.

Далі агент читає знайдене і, якщо треба, шукає знову, уже точніше. На реальній задачі це ланцюжок із кількох кроків: знайти визначення функції → знайти, хто її викликає → прочитати код, що викликає → знайти тести.

Такий підхід називають агентним пошуком. У нього є ціна: кожен пошук — це крок циклу й токени. І є переваги: немає індексу, який застаріває, результат завжди відповідає диску, і нічого з вашого коду не йде в стороннє сховище.

Дві деталі, що економлять час, коли агент «не знаходить очевидне»:

- `Grep` пропускає файли з `.gitignore`. `Glob` типово не пропускає. Тому файл з ігнорованої теки знаходиться за назвою, але не за вмістом.
- На macOS, Linux і в WSL окремих інструментів `Grep` і `Glob` у наборі немає: там агент користується командами `find` і `grep` через shell, а Claude Code підставляє під них вбудовані швидкі реалізації. На Windows це окремі інструменти. Поведінка одна, назви в логах різні.

Якщо хочеться саме семантики — «знайди всі місця, де викликається цей метод», а не «знайди текст» — для цього є інструмент `LSP`. Він підключає мовний сервер, той самий, що працює у вашій IDE, і дає перехід до визначення, пошук посилань і помилки типів одразу після правки. Вмикається плагіном під конкретну мову; про це в розділі про плагіни.

### Команди: Bash і PowerShell

`Bash` виконує команду оболонки й повертає вивід. Через нього агент робить усе, для чого немає окремого інструмента: збірка, тести, git, пакетні менеджери, скрипти.

Як він поводиться:

- **Кожна команда — окремий процес.** Змінні середовища з однієї команди в наступну не переходять. Робоча тека переходить, поки ви всередині проєкту; вийшли за його межі — наступна команда знову стартує з проєкту.
- **Ваш профіль підхоплюється.** На старті сесії Claude Code знімає відбиток вашої оболонки — аліаси, функції, налаштування — і застосовує його до команд.
- **Є таймаут.** Типово дві хвилини, модель може попросити до десяти.
- **Довге йде у фон.** Збірку чи сервер агент запускає у фоні й продовжує працювати; коли процес завершиться, харнес повідомить йому про це. Команда, що не вклалася в таймаут, теж переїжджає у фон сама.
- **Вивід обрізається.** Моделі відразу дістається близько 30 тисяч символів. Решта зберігається у файл, і агент читає з нього потрібні шматки. Так лог збірки на мегабайт не з'їдає контекст.

Пара прикладів. Ось як виглядає правило про робочу теку. Агент перейшов у тимчасовий каталог за межами проєкту й виконав там команду:

```json title="виклик Bash"
{
  "command": "cd /tmp/build && ls"
}
```

```text languages="відповідь Bash"
bundle.js
Shell cwd was reset to D:\projects\demo
```

Останній рядок додав харнес: команда відпрацювала, але наступна знову почнеться з теки проєкту. Так агент не може «заблукати» і випадково виконати `rm` не там.

А ось запуск у фоні. Сервер розробки не завершується сам, тому чекати на його кінець безглуздо:

```json title="виклик Bash"
{
  "command": "npm run dev",
  "run_in_background": true
}
```

Харнес одразу повертає керування й ідентифікатор фонового завдання. Вивід сервера пишеться у файл, і агент читає його звичайним `Read`, коли треба подивитися, що там сталося. Список фонових завдань показує команда `/tasks`; там же їх можна зупинити.

На Windows `Bash` — це Git Bash з Git for Windows. Поруч працює інструмент `PowerShell`; без встановленого Git він лишається єдиною оболонкою. Звідси типова плутанина: синтаксис у них різний, і команда, написана для одного, в іншому не працює.

Ще є `Monitor`: він запускає команду у фоні й передає агентові її вивід рядок за рядком, у міру появи. Зручно, щоб стежити за логом або чекати на подію, не опитуючи в циклі.

Команду можна виконати й самому, не виходячи із сесії: рядок, що починається з `!`, запускається в оболонці, а її вивід потрапляє в розмову.

### Веб

`WebSearch` повертає заголовки й адреси з пошукового бекенду Anthropic. Самі сторінки він не завантажує.

`WebFetch` завантажує сторінку, але працює хитріше, ніж здається. Він перетворює HTML на Markdown і віддає його **іншому, окремому** запиту до невеликої моделі разом із питанням. Основний агент отримує вже відповідь на питання, а не сиру сторінку. Сенс тут подвійний: велика сторінка не забиває контекст, а шкідливі інструкції, сховані в тексті сторінки, не потрапляють основному агентові напряму. Зворотний бік: це переказ, і точні цифри з таблиці він іноді плутає. Коли потрібна дослівна точність, агентові краще завантажити сторінку командою `curl`.

Для сайтів, яким потрібен вхід або JavaScript, ці два інструменти не годяться. Там потрібен справжній браузер — про варіанти нижче.

### Одна задача цілком

Тепер зберемо інструменти разом. Задача на тому самому навчальному проєкті: «зроби, щоб сесія жила добу, і щоб прострочені видалялися з бази». Ось що робить агент, крок за кроком.

| Крок | Виклик | Навіщо | Що повернулося |
|---|---|---|---|
| 1 | `Grep` за словом `TTL` | знайти, де задано строк життя | один файл: модуль сесій |
| 2 | `Read` цього файлу | побачити код цілком, він короткий | двадцять рядків із номерами |
| 3 | `Grep` за `findSession` | зрозуміти, кого зачепить зміна | три файли: сам модуль, обробник профілю, тест |
| 4 | `Read` обробника й тесту, двома викликами одразу | перевірити, чого вони чекають від функції | обидва файли |
| 5 | `Edit`: рядок із `TTL` | доба замість години | «updated successfully» |
| 6 | `Edit`: умова з простроченою сесією | додати видалення | «updated successfully» |
| 7 | `Bash`: запуск тестів | перевірити результат | вивід тестів |
| 8 | відповідь текстом | розповісти, що зроблено | — |

На що тут варто подивитися.

**Агент почав із пошуку, а не з читання всього підряд.** У проєкті на тисячу файлів він так само прочитав би три.

**Крок 3 зроблено до правки.** Перш ніж змінювати поведінку функції, агент з'ясував, хто нею користується. Якби обробник профілю покладався на те, що прострочена сесія лишається в базі, це з'ясувалося б тут, а не після.

**На кроці 4 два виклики пішли однією відповіддю.** Читання одне від одного не залежать, і харнес виконав їх одночасно.

**На кроці 6 довелося взяти два рядки.** Один рядок `return null;` у файлі не унікальний — це той самий випадок із розділу про правку.

**Крок 7 замикає цикл.** Без нього агент зупинився б на «виглядає правильно». З ним — на «тести пройшли». Якби тест упав, вивід повернувся б моделі, і цикл пішов би далі: прочитати помилку, поправити, запустити знову.

Усього вісім запитів до моделі. І кожен наступний ніс у собі все попереднє: до восьмого в запиті лежали обидва пошуки, три прочитані файли, дві правки та вивід тестів. Це і є вміст контексту, про який наступний розділ.

## Контекст: вікно, стиснення і ціна

Контекстне вікно — це межа обсягу одного запиту до моделі. У нього має вміститися все: системний промпт, інструкції, уся розмова, кожен прочитаний файл і вивід кожної команди.

У теперішніх моделей вікно — мільйон токенів. Цього вистачає на години роботи, і впертися в межу важко. Але вікно все одно наповнюється, і тоді спрацьовує **стиснення** (compaction): Claude Code просить модель переказати розмову і замінює історію цим переказом. Робота триває, але з короткою версією минулого.

Тут важливо знати, що стиснення переживає, а що ні.

| Переживає | Не переживає як є |
|---|---|
| системний промпт і стиль виводу | дослівні формулювання ранніх повідомлень |
| кореневий `CLAUDE.md` і правила без прив'язки до шляхів — перечитуються з диска | правила з прив'язкою до шляхів і `CLAUDE.md` з підтек — повернуться, коли агент знову зачепить відповідний файл |
| автопам'ять — перечитується з диска | вміст раніше прочитаних файлів, окрім кількох останніх |
| список скілів | домовленості, дані лише в чаті |
| тіла нещодавно викликаних скілів, з обмеженням за обсягом | |
| фонові команди та субагенти — продовжують працювати | |

Практичний висновок простий. Усе, що має діяти всю сесію, має лежати у файлі, а не в чаті. Сказане в чаті може не пережити стиснення; записане в інструкції проєкту перечитається з диска.

Керують цим чотири команди: `/context` показує, чим зайняте вікно; `/compact` стискає зараз, і йому можна підказати, що зберегти; `/clear` починає розмову з чистого аркуша, стара лишається на диску; `/autocompact` задає поріг, за якого стиснення вмикається саме.

Тепер про ціну. Оскільки кожен запит несе всю розмову, довга сесія була б дуже дорогою. Рятує **кеш промпта**: незмінний початок запиту сервер запам'ятовує і за повтору рахує приблизно в десять разів дешевше. Поки ви працюєте без довгих пауз, кеш теплий і розмова коштує недорого. Після паузи кеш холоне, і наступний запит оплачується повністю. Звідси порада, яка здається дивною, поки не знаєш механізму: непов'язані задачі вигідніше робити в різних сесіях, а не в одній нескінченній.

## Сесії: де зберігається розмова і як відкотитися

Сесія — це одна розмова. Харнес записує її на диск у міру роботи, у звичайний текстовий файл формату JSONL: один рядок — один запис у JSON.

Лежить він у домашній теці, у каталозі за назвою проєкту:

```text
~/.claude/projects/D--PycharmProjects-My-Site-on-Astro/
├── 4e5a5be5-….jsonl          розмова: повідомлення, виклики інструментів, результати
├── 4e5a5be5-…/
│   ├── subagents/            розмови субагентів цієї сесії
│   └── tool-results/         великі виводи інструментів, що не вмістилися в запит
└── memory/                   автопам'ять проєкту
```

Назва теки — це шлях до проєкту, в якому все, крім літер і цифр, замінено дефісами. Так `D:\PycharmProjects\My_Site_on_Astro` перетворюється на `D--PycharmProjects-My-Site-on-Astro`.

Ось як виглядає один запис — ваше повідомлення. Я залишив головні поля й розбив рядок для читабельності; у файлі це один рядок:

```json
{
  "type": "user",
  "uuid": "0b6f2c1e-…",
  "parentUuid": "9d41a7f3-…",
  "sessionId": "4e5a5be5-…",
  "timestamp": "2026-11-19T08:55:12.431Z",
  "cwd": "D:\\projects\\demo",
  "gitBranch": "master",
  "version": "2.1.328",
  "message": {
    "role": "user",
    "content": "зроби, щоб сесія жила добу"
  }
}
```

Поле `parentUuid` зв'язує запис із попереднім. Завдяки цьому розмова — не просто список, а дерево: коли ви відкочуєтеся і йдете іншим шляхом, стара гілка лишається у файлі, а нова росте від тієї самої точки. Запис відповіді моделі влаштований так само, тільки в `message` лежать блоки: міркування, текст, виклики інструментів, а поруч — відомості про модель і витрату токенів.

Усередині файлу записи різних типів: повідомлення користувача й асистента, знімки файлів, зміна режиму, назва сесії. Формат внутрішній і між версіями змінюється, але це звичайний текст: його можна відкрити, по ньому можна шукати. І з цього випливає важливе: **розмови лежать на диску незашифрованими**. Якщо агент прочитав файл із паролем, пароль тепер є і у файлі сесії.

Сесії зберігаються 30 днів, потім видаляються самі; строк змінюється налаштуванням `cleanupPeriodDays`. Видалити все, що Claude Code знає про один проєкт, можна командою `claude purge`.

Що з сесіями можна робити:

- **Продовжити.** `claude --continue` відкриває останню сесію в цій теці, `claude --resume` показує список. Усередині сесії те саме робить `/resume`.
- **Відгалузити.** `/branch` копіює розмову в нову сесію з поточного місця, оригінал не змінюється. Зручно спробувати інший шлях.
- **Назвати.** `/rename` або прапорець `--name`: за назвою сесію потім легше знайти.

### Відкат: чекпоінти

Перед кожною правкою файлу харнес зберігає його попередню версію. Ці копії лежать у `~/.claude/file-history/`, по теці на сесію. Кожне ваше повідомлення створює контрольну точку.

Команда `/rewind` (або Esc двічі на порожньому рядку) відкриває список точок. Для вибраної можна повернути код, повернути розмову або і те, й інше. Там же є «стиснути починаючи звідси»: файли не чіпаються, а хвіст розмови замінюється переказом.

У відкату є межа, про яку треба пам'ятати. Він знає лише про правки, зроблені інструментами `Edit` і `Write`. Те, що зробила команда оболонки, він не відкотить: видалений через `rm` файл, міграцію бази, `git push`, встановлений пакет. Не відстежуються і правки субагентів, і ваші власні правки в редакторі. Чекпоінти — це страховка всередині сесії, а не заміна git.

## Тека проєкту: що лежить у `.claude`

Тепер про те, чим Claude Code налаштовується під конкретний проєкт. Майже все живе в теці `.claude` у корені репозиторію і комітиться разом із кодом, щоб у всієї команди агент поводився однаково.

```text
проєкт/
├── CLAUDE.md                   інструкції проєкту, читаються в кожній сесії
├── CLAUDE.local.md             особисті інструкції, у git не йдуть
├── .mcp.json                   MCP-сервери проєкту
├── .worktreeinclude            які файли поза git копіювати в робочі копії
└── .claude/
    ├── settings.json           налаштування команди: дозволи, хуки, змінні
    ├── settings.local.json     особисті налаштування, у git не йдуть
    ├── rules/                  правила, по файлу на тему
    ├── skills/<назва>/SKILL.md скіли
    ├── agents/                 описи субагентів
    ├── commands/               команди в старому форматі
    ├── output-styles/          стилі виводу
    ├── workflows/              збережені сценарії з кількома агентами
    ├── agent-memory/           пам'ять субагентів
    ├── hooks/                  зазвичай тут тримають скрипти хуків
    └── worktrees/              окремі робочі копії для паралельних сесій
```

Нижче — про кожну частину: що це, коли завантажується і чим відрізняється від сусідніх.

### Інструкції: `CLAUDE.md`

`CLAUDE.md` — це текстовий файл із тим, що агент має знати в кожній сесії: як зібрати проєкт, як запустити тести, які тут є неочевидні домовленості. Створити першу версію допомагає команда `/init`.

Файлів може бути кілька, і вони складаються. Порядок завантаження такий:

| Рівень | Де лежить | Для чого |
|---|---|---|
| Організація | системна тека: `C:\Program Files\ClaudeCode\`, `/etc/claude-code/`, `/Library/Application Support/ClaudeCode/` | правила компанії, задає адміністратор |
| Особистий | `~/.claude/CLAUDE.md` | ваші звички в усіх проєктах |
| Проєкт | `CLAUDE.md` у корені або `.claude/CLAUDE.md` | спільні правила проєкту, у git |
| Особистий у проєкті | `CLAUDE.local.md` | ваші нотатки щодо цього проєкту, не в git |

Крім того, читаються `CLAUDE.md` з усіх тек вище робочої. А файли з підтек підвантажуються на вимогу — коли агент читає або правит щось у цій підтеці. У монорепозиторії це дає змогу тримати в кожного сервісу свої інструкції й не вантажити їх усі одразу.

Усередині можна підключати інші файли рядком `@шлях/до/файлу`. Вкладеність — до чотирьох рівнів.

Про `AGENTS.md`. Це загальний формат інструкцій, який читають багато агентів. Claude Code читає його, лише якщо в проєкті немає власного `CLAUDE.md`. Поведінка змінюється в налаштуваннях: можна читати обидва.

Головна порада щодо цього файлу — тримати його коротким. Документація називає орієнтир у двісті рядків, і причина не в ліміті, а в тому, що довгі інструкції гірше дотримуються.

### Правила: `.claude/rules/`

Правила — це ті самі інструкції, тільки розкладені по файлах, по одному на тему. Правило без шапки завантажується на старті, як `CLAUDE.md`.

Цікавіше правило з шапкою, де вказано маски шляхів:

```markdown title=".claude/rules/api-endpoints.md"
---
paths:
  - "src/api/**/*.ts"
---

# Правила для API

- Кожен ендпоїнт валідує вхід.
- Помилки віддаються в загальному форматі.
```

Таке правило потрапить у контекст, лише коли агент прочитає або зачепить відповідний файл. Так правила для бази даних не займають місце, поки триває робота над версткою.

Особисті правила на всі проєкти кладуться в `~/.claude/rules/`.

### Автопам'ять

Інструкції й правила пишете ви. Автопам'ять агент пише сам. Це нотатки про те, що він дізнався під час роботи і що знадобиться в наступних сесіях: що ви віддаєте перевагу, яке рішення ухвалили, де лежить потрібна панель.

Зберігається вона не в проєкті, а в домашній теці: `~/.claude/projects/<проєкт>/memory/`. Усередині — індексний файл `MEMORY.md` і окремі файли за темами. На початку сесії в контекст потрапляє лише початок індексу, перші двісті рядків. Тематичні файли агент відкриває, коли вони потрібні.

Індекс — це просто список посилань, по рядку на нотатку:

```markdown title="memory/MEMORY.md"
- [Тести лише через контейнер](tests-in-docker.md) — локальний запуск тестів падає, потрібна база з docker compose
- [Панель моніторингу](grafana-dashboard.md) — де дивитися затримки API після викладання
```

А сама нотатка — файл із короткою шапкою та одним фактом:

```markdown title="memory/tests-in-docker.md"
---
name: tests-in-docker
description: Інтеграційні тести запускати лише в контейнері, локально вони падають
metadata:
  type: feedback
---

Інтеграційні тести запускати командою `docker compose run tests`.

**Чому:** тестам потрібна база певної версії, локально її немає.
**Як застосовувати:** перед запуском тестів не пробувати `npm test` напряму.
```

Типів нотаток чотири: про користувача, про його зауваження до роботи, про проєкт і посилання на зовнішні ресурси. За описом у шапці агент вирішує, чи відкривати файл.

Що з цього випливає:

- Пам'ять **локальна для машини і для вас**. Колега її не отримає, на іншому комп'ютері її немає. Усе, що мають знати всі, — у правила проєкту.
- Це звичайні Markdown-файли. Їх можна читати й правити руками; командою `/memory` — подивитися й вимкнути.
- Проєкт визначається за git-репозиторієм, тому в усіх робочих копій одного репозиторію пам'ять спільна.
- Чищення за строком зберігання її не чіпає.

Щоб не плутати, чим відрізняються три види «пам'яті»:

| | Хто пише | Де лежить | Бачить команда | Коли в контексті |
|---|---|---|---|---|
| `CLAUDE.md` і правила | ви | у репозиторії | так | завжди або за маскою шляхів |
| Автопам'ять | агент | у домашній теці | ні | індекс — завжди, теми — на вимогу |
| Історія сесії | харнес | у домашній теці | ні | лише в цій сесії |

### Скіли: знання на вимогу

Скіл — це тека з файлом `SKILL.md`: інструкція, як виконувати певну роботу. Наприклад, як випускати реліз або як читати дані з аналітики. Поруч можуть лежати допоміжні файли та скрипти.

Ключова ідея — поступове завантаження. У сплячому стані від скіла в контексті лише назва й опис. Коли задача підпадає під опис, агент викликає інструмент `Skill`, і тіло файлу потрапляє в контекст. Файли поруч читаються, лише якщо на них є посилання і вони знадобилися. Тому довідник на тисячу рядків у вигляді скіла майже нічого не коштує, а у вигляді правила коштував би в кожній сесії.

```markdown title=".claude/skills/release/SKILL.md"
---
name: release
description: Випуск нової версії. Використовувати, коли просять випустити реліз або підняти версію.
disable-model-invocation: true
allowed-tools: Bash(npm version *), Bash(git tag *)
---

1. Переконатися, що робоче дерево чисте.
2. Підняти версію: `npm version $ARGUMENTS`.
3. Зібрати проєкт і прогнати тести.
```

Що тут важливо:

- `description` — це те, за чим агент вирішує, чи підходить скіл. Опис важливіший за тіло: погано описаний скіл не буде викликаний.
- `disable-model-invocation: true` забороняє агентові запускати скіл самому. Лишається ручний виклик командою `/release 1.4.0`. Так позначають процедури з наслідками.
- `$ARGUMENTS` замінюється на те, що ви написали після назви команди.
- `allowed-tools` заздалегідь дозволяє перелічені інструменти на час роботи скіла.

Ще скіл можна запустити в окремому контексті (`context: fork`): тоді він виконується як субагент і повертає лише результат.

Скіли й слеш-команди — це одне й те саме. Будь-який скіл викликається як `/назва`. Старий формат, файли в `.claude/commands/`, як і раніше працює. Скіли бувають особисті (`~/.claude/skills/`), проєктні, з плагінів і вбудовані: `/code-review`, `/simplify`, `/doctor`, `/loop`, `/run` та інші.

Місця в контексті під список скілів відведено небагато — близько одного відсотка вікна. Коли скілів багато, у рідко вживаних лишається тільки назва. Подивитися, скільки коштує кожен, можна в `/skills`.

### Субагенти

Субагент — це окремий екземпляр агента зі своїм чистим контекстом. Головний агент дає йому завдання, субагент працює у власному циклі й повертає один підсумковий звіт.

Навіщо це потрібно. Уявіть завдання «з'ясуй, як влаштована авторизація». Щоб відповісти, треба прочитати двадцять файлів. Якщо їх читає головний агент, усі двадцять назавжди лишаються в його контексті. Якщо читає субагент, у головний контекст повертається одна сторінка висновків, а двадцять файлів зникають разом із субагентом.

У цього є ціна, і про неї часто забувають. Субагент не бачив вашої розмови. Він знає лише те, що головний агент написав йому в завданні. І головний агент бачить лише підсумковий звіт, а не те, як субагент до нього дійшов. На кожній передачі втрачаються деталі. Тому субагенти добрі для розвідки та незалежних шматків роботи і погані для задач, де важливий увесь накопичений контекст.

Вбудованих субагентів кілька:

| Назва | Що робить |
|---|---|
| `Explore` | лише читання: швидкий пошук по кодовій базі |
| `Plan` | лише читання: готує план реалізації |
| `general-purpose` | усі інструменти, для багатокрокових задач |
| `claude-code-guide` | відповідає на питання про сам Claude Code |

Власних описують файлами в `.claude/agents/` або `~/.claude/agents/`:

```markdown title=".claude/agents/test-runner.md"
---
name: test-runner
description: Запускає тести й розбирає падіння. Використовувати після змін у коді.
tools: Read, Grep, Glob, Bash
model: haiku
---

Запусти тести, знайди причину кожного падіння і поверни короткий список:
тест, причина, файл і рядок.
```

Тіло файлу — це системний промпт субагента. У шапці задається, які інструменти йому доступні, на якій моделі він працює, в якому режимі дозволів. Просту механічну роботу вигідно віддавати дешевій моделі.

Корисні можливості:

- **Фон.** Субагент може працювати у фоні, поки головний агент зайнятий іншим; результат прийде сповіщенням.
- **Ізоляція.** З `isolation: worktree` субагент отримує власну копію репозиторію і не заважає правкам в основній.
- **Форк.** Звичайний субагент починає з чистого аркуша. Форк успадковує всю розмову; його запускає `/subtask`.
- **Власна пам'ять.** З полем `memory` у субагента з'являється тека нотаток, що переживає сесії.
- **Вкладеність.** Субагент може запустити свого субагента, до трьох рівнів углиб.

І про витрати. П'ять субагентів паралельно — це приблизно п'ять сесій за ціною. Запускати їх заради задачі на три файли невигідно.

### Хуки

Усе перелічене вище — текст, який модель читає і зазвичай виконує. Хук — це інше: ваш код, який харнес запускає сам у певний момент, що б модель не вирішила.

Моментів, на які можна повісити хук, понад тридцять: старт сесії, надсилання повідомлення, перед викликом інструмента і після нього, запит дозволу, кінець ходу, стиснення контексту тощо. Хук отримує на вхід JSON з описом події і може не лише щось зробити, а й вплинути на хід: заборонити виклик інструмента, додати текст у контекст, повернути агента до роботи.

```json title=".claude/settings.json"
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "npm run lint" }]
      }
    ]
  }
}
```

Цей хук запускає лінтер після кожної правки файлу. Модель про це не просили — це робить харнес.

Правило вибору таке: те, що має відбуватися завжди, робиться хуком, а не рядком в інструкціях. Форматування після правки, заборона чіпати певну теку, звук наприкінці ходу, запис у журнал. Докладно, з усіма подіями та робочими прикладами, — у [статті про хуки](/uk/claude-code-hooks/).

### MCP: зовнішні інструменти

Вбудованих інструментів вистачає для роботи з файлами й терміналом. Але агентові буває потрібне й інше: зазирнути в трекер задач, у базу даних, у документацію бібліотеки. Для цього є MCP (Model Context Protocol) — стандарт, за яким зовнішня програма-сервер оголошує свої інструменти, а агент їх викликає. Як влаштований сам протокол, я писав в [окремій статті](/uk/mcp-webmcp/).

Для Claude Code MCP-сервер — це просто ще один набір інструментів. Підключається він командою або файлом:

```json title=".mcp.json"
{
  "mcpServers": {
    "docs": {
      "type": "http",
      "url": "https://mcp.example.com/mcp"
    },
    "local-db": {
      "command": "npx",
      "args": ["-y", "example-db-mcp"],
      "env": { "DB_URL": "${DB_URL}" }
    }
  }
}
```

Перший сервер віддалений, до нього агент ходить по HTTP. Другий локальний: Claude Code сам запускає його як процес і спілкується з ним через стандартний ввід і вивід.

Те саме робиться командами, без правки файлу руками:

```bash
claude mcp add --transport http docs https://mcp.example.com/mcp
claude mcp add local-db -e DB_URL=postgres://localhost/app -- npx -y example-db-mcp
claude mcp add --scope project --transport http docs https://mcp.example.com/mcp
```

Перша команда додає віддалений сервер. Друга — локальний: усе, що після двох дефісів, — це команда його запуску. Третя відрізняється прапорцем `--scope`: він вирішує, кому сервер буде видно.

Інструменти сервера отримують назви виду `mcp__<сервер>__<інструмент>`, наприклад `mcp__docs__search`. Під цими назвами вони фігурують у правилах дозволів і в хуках.

Сервер можна підключити на трьох рівнях, і від рівня залежить, де зберігається запис:

| Рівень | Кому видно | Де записано |
|---|---|---|
| local (типово) | вам, у цьому проєкті | `~/.claude.json`, у розділі проєкту |
| project | усій команді | `.mcp.json` у корені репозиторію |
| user | вам, в усіх проєктах | `~/.claude.json` |

Сервери з `.mcp.json` вимагають одноразового підтвердження: чужий репозиторій не повинен мовчки запускати програми на вашій машині.

Важлива деталь про контекст. Раніше кожен сервер одразу викладав у контекст повні описи всіх своїх інструментів, і п'ять серверів могли з'їсти десятки тисяч токенів. Тепер описи відкладено: у контексті лише назви. Коли інструмент знадобився, агент викликає `ToolSearch` і отримує його повну схему. Тому багато підключених серверів більше не проблема.

І ще одне: якщо ви ввійшли через акаунт claude.ai, конектори, підключені там (пошта, календар, диск), доступні і в Claude Code.

### Плагіни, маркетплейси та моди

Плагін — це пакунок. В одну теку збираються скіли, субагенти, хуки, MCP-сервери, стилі виводу, теми, виконувані файли, і все це ставиться однією командою. Так діляться налаштуваннями між проєктами й командами.

Джерело плагінів називається маркетплейсом. Це git-репозиторій або адреса з файлом-каталогом. Офіційний маркетплейс Anthropic підключається сам під час першого запуску. Керування — командою `/plugin`: подивитися доступні, поставити, увімкнути, вимкнути.

Два види плагінів варто виділити.

**Плагіни мовних серверів.** Вони дають агентові інструмент `LSP`, про який ішлося в розділі про пошук. Є готові для півтора десятка мов, від TypeScript і Python до Kotlin і Rust. Сам мовний сервер має бути встановлений у системі.

**Моди.** Звичайний плагін додає агентові знання та інструменти. Мод змінює сам Claude Code: його код працює всередині програми. Мод може намалювати панель поруч із чатом або смугу над полем вводу, додати команду, що виконується миттєво, без звернення до моделі, втрутитися у виклик інструмента. Моди з'явилися у версії 2.1.287. Написати свій можна, просто попросивши агента.

До модів варто ставитися як до будь-якої програми, яку ви запускаєте: код мода працює з вашими правами і поза пісочницею. Якщо після встановлення щось зламалося, `claude --safe-mode` запустить сесію без усіх налаштувань, плагінів і хуків.

### Стилі виводу, рядок стану, клавіші

Три невеликі налаштування інтерфейсу.

**Стиль виводу** змінює манеру відповідей. Вбудовані: звичайний, стислий, пояснювальний (додає пояснення, чому зроблено так) і навчальний (лишає вам шматки для самостійної роботи). Власні кладуться файлами в `output-styles/`.

**Рядок стану** — нижній рядок інтерфейсу. Його малює ваш скрипт: харнес передає йому JSON з даними сесії, а те, що скрипт надрукує, з'являється на екрані. Туди виводять гілку git, модель, заповненість контексту, витрату ліміту.

**Клавіші** перепризначаються у файлі `~/.claude/keybindings.json`.

## Налаштування: де лежать і що головніше

Налаштування зберігаються у файлах `settings.json`. Їх кілька, і те саме налаштування може бути задане в кількох. Перемагає рівень із вищим пріоритетом.

| Пріоритет | Рівень | Файл |
|---|---|---|
| 1, вищий | Організація | `managed-settings.json` у системній теці, політика ОС або налаштування з сервера |
| 2 | Запуск | прапорець `--settings` |
| 3 | Особисті в проєкті | `.claude/settings.local.json` |
| 4 | Проєкт | `.claude/settings.json` |
| 5 | Особисті | `~/.claude/settings.json` |

Списки не перекриваються, а складаються. Правила дозволів з особистого файлу і з файлу проєкту діють разом.

Є ще один файл, який постійно плутають з налаштуваннями: `~/.claude.json`. Він лежить не в теці `.claude`, а поруч із нею, в домашньому каталозі. Це не налаштування, а стан: в який акаунт ви ввійшли, яким текам довіряєте, особисті MCP-сервери, лічильники підказок, кеші. Claude Code пише в нього сам. Руками його чіпати зазвичай ні до чого.

Третій механізм — змінні середовища. Через них задають ключ API, провайдера, модель, таймаути. Їх можна виставити в оболонці або в блоці `env` файлу налаштувань.

Перевірити, що насправді завантажилося, допомагають дві команди: `/status` показує джерела налаштувань, `/doctor` знаходить биті файли й суперечності. Повний список ключів із прикладами — в [довіднику](/uk/claude-code-commands-and-settings/).

## Що лежить на диску поза проєктом

Проєкт — лише частина картини. Більша частина даних Claude Code живе в домашній теці користувача. На Windows це `C:\Users\<ім'я>\.claude`, на macOS і Linux — `~/.claude`.

Ось що там лежить. Частина тек з'являється, лише коли ви починаєте користуватися відповідною можливістю.

```text
~/.claude/
├── settings.json          особисті налаштування
├── CLAUDE.md              особисті інструкції на всі проєкти
├── keybindings.json       власні комбінації клавіш
├── rules/  skills/  agents/  commands/  output-styles/  workflows/  themes/
│                          особисті правила, скіли, субагенти та інше
├── .credentials.json      дані входу в акаунт
├── history.jsonl          історія введених вами повідомлень
├── projects/              розмови й автопам'ять, по теці на проєкт
├── file-history/          копії файлів для відкату
├── sessions/              по маленькому файлу на кожну запущену сесію
├── session-env/           середовище сесій
├── shell-snapshots/       відбитки налаштувань оболонки
├── paste-cache/           великі вставки з буфера
├── plans/                 плани з режиму планування
├── tasks/                 списки завдань
├── plugins/               встановлені плагіни та маркетплейси
├── daemon/  jobs/         стан фонових сесій
├── ide/                   зв'язок із запущеними IDE
├── chrome/                міст до розширення в браузері
├── debug/                 налагоджувальні логи
├── backups/               копії файлу ~/.claude.json
├── cache/                 каталог моделей, список змін
├── agent-memory/          пам'ять особистих субагентів
└── teams/                 поштові скриньки команд агентів
```

Розберемо те, що важливо розуміти.

**`projects/`** — найбільша й найцінніша тека. Тут усі ваші розмови і вся автопам'ять. У мене в ній кілька десятків підтек, по одній на кожен проєкт, де я бодай раз запускав Claude Code. Якщо переносите роботу на інший комп'ютер, копіювати треба її.

**`.credentials.json`** — дані входу. На Windows і Linux це файл, захищений правами доступу до профілю користувача. На macOS дані входу лежать у системній в'язці ключів, а файл використовується як запасний варіант. Цей файл не можна комітити, пересилати й показувати.

**`history.jsonl`** — те, що ви набирали в полі вводу. З нього працюють стрілка вгору і пошук за Ctrl+R. За строком зберігання не видаляється.

**`sessions/`** — службові файли працюючих сесій: номер процесу, робоча тека, назва, статус. За ними сесії знаходять одна одну і за ними ж Claude Code розуміє, що сесія впала.

**`file-history/`** — копії файлів перед правками. Версії називаються за хешем шляху з номером: перша правка, друга, третя.

**`shell-snapshots/`** — відбитки аліасів і функцій вашої оболонки. Через них команди агента поводяться як ваші.

**`ide/`** — файли-замки з портом, на якому слухає розширення у VS Code або JetBrains. Через них термінальна сесія знаходить відкритий редактор.

Чищення працює так: розмови, копії файлів, плани, логи й вставки видаляються, коли стають старшими за строк зберігання, типово 30 днів. Автопам'ять, історія вводу та налаштування не видаляються.

Тепер те, що лежить поза `~/.claude`:

| Що | Де на Windows | Де на macOS і Linux |
|---|---|---|
| Стан і особисті MCP-сервери | `C:\Users\<ім'я>\.claude.json` | `~/.claude.json` |
| Сама програма | `C:\Users\<ім'я>\.local\bin\claude.exe` | `~/.local/bin/claude` |
| Тимчасові файли сесії | `%TEMP%\claude\<проєкт>\<сесія>\` | тимчасова тека системи |
| Налаштування організації | `C:\Program Files\ClaudeCode\` | `/etc/claude-code/`, `/Library/Application Support/ClaudeCode/` |
| Міст до браузера | `%APPDATA%\Claude Code\ChromeNativeHost` | тека налаштувань браузера |
| Кеш | `%LOCALAPPDATA%\claude-cli-nodejs\` | тека кешу користувача |

У тимчасовій теці в кожної сесії є своя «чернеткова» директорія. Туди агент складає одноразові скрипти й проміжні файли, щоб не смітити в проєкті.

Усе, що зберігається в `~/.claude`, можна перенести в інше місце змінною `CLAUDE_CONFIG_DIR`. Це ж спосіб тримати на одній машині два акаунти: у кожного своя тека конфігурації.

## Дозволи: що агентові можна без питання

Досі йшлося про те, що агент уміє. Тепер — про те, що йому дозволено. Це окремий шар, і працює він у харнесі: модель може попросити що завгодно, але виконає харнес лише дозволене.

### Режими

Режим визначає типову поведінку. Перемикається поєднанням Shift+Tab просто під час роботи.

| Режим | Що робить без питань |
|---|---|
| Ручний (`default`) | лише читає; на правки й команди питає |
| `acceptEdits` | плюс правит файли й виконує прості файлові команди в робочій теці |
| `plan` | читає й досліджує, пише план; вихідники не чіпає |
| `auto` | усе, але кожну дію перевіряє фоновий класифікатор |
| `dontAsk` | те, що дозволено правилами; усе інше мовчки відхиляє |
| `bypassPermissions` | усе без питань; правила заборони лишаються в силі |

Останній режим вмикається прапорцем `--dangerously-skip-permissions`, і назва чесна: він призначений для ізольованих середовищ — контейнера або віртуальної машини без доступу до чогось цінного.

### Правила

Поверх режиму діють правила трьох видів: дозволити, спитати, заборонити.

```json title=".claude/settings.json"
{
  "permissions": {
    "allow": ["Bash(npm run *)", "Edit(src/**)"],
    "ask": ["Bash(git push *)"],
    "deny": ["Read(./.env)", "Read(./secrets/**)"]
  }
}
```

Правило — це назва інструмента і уточнення в дужках. Для команд це початок команди із зірочкою, для файлів — маска шляху, для вебу — домен.

Приклади правил і того, що вони означають:

| Правило | Що покриває |
|---|---|
| `Bash(npm run build)` | рівно цю команду |
| `Bash(npm run *)` | будь-яку команду, що починається з `npm run` |
| `Bash(git log *)` | `git log` з будь-якими аргументами, але не `git push` |
| `Edit(src/**)` | правку будь-яких файлів усередині `src` |
| `Read(./.env)` | читання файлу `.env` у корені проєкту |
| `Read(~/.ssh/**)` | читання чого завгодно в теці ключів |
| `WebFetch(domain:docs.example.com)` | завантаження сторінок із цього домену |
| `mcp__docs__*` | усі інструменти MCP-сервера `docs` |
| `Agent(Explore)` | запуск субагента `Explore` |
| `Bash` | інструмент цілком |

Як це працює на живому прикладі. Агент хоче виконати `npm run test && git push origin main`. Харнес ділить команду на дві частини. Перша підпадає під дозвіл `Bash(npm run *)`. Друга підпадає під правило «спитати» `Bash(git push *)`. Підсумок: питання вам, і в питанні видно всю команду цілком.

Коли ви в діалозі вибираєте «більше не питати», харнес сам дописує правило в особисті налаштування проєкту, `.claude/settings.local.json`. Подивитися й почистити накопичене можна командою `/permissions`.

Правила перевіряються в порядку: спочатку заборони, потім «спитати», потім дозволи. Перемагає перший збіг, тому заборона завжди сильніша за дозвіл. Заборона на читання файлу діє і для пошуку: такий файл випадає з результатів.

Кілька речей, що роблять правила надійнішими, ніж здається:

- Складена команда розбирається на частини. `npm test && rm -rf build` перевіряється як дві команди, і дозволені мають бути обидві.
- Обгортки на кшталт `timeout` чи `nohup` відкидаються перед перевіркою.
- Перенаправлення виводу у файл перевіряється як правка цього файлу.

І одна річ, через яку на правила для команд не можна покладатися як на стіну: те саме можна виконати багатьма способами. Заборона `Bash(curl *)` не впіймає `/usr/bin/curl` чи скрипт на Python, який робить той самий запит. Заборони на команди захищають від випадковостей, а не від цілеспрямованого обходу. Справжню межу ставить пісочниця.

### Довіра теці та захищені шляхи

Під час першого запуску в новій теці Claude Code питає, чи довіряєте ви їй. Це не формальність. Файли проєкту можуть містити хуки та MCP-сервери, тобто код, який виконається на вашій машині. До підтвердження дозвільні правила з проєкту не застосовуються. Чужий репозиторій варто спершу переглянути очима.

Крім того, є захищені шляхи, запис у які потребує підтвердження навіть у режимі автоматичних правок: теки `.git`, `.vscode`, `.idea`, `.claude`, файли налаштувань оболонки, `.mcp.json`. Змінивши їх, можна змусити виконатися довільний код, тому харнес бере їх під окрему охорону.

### Авторежим

Ручний режим безпечний, але виснажливий: на сотому підтвердженні людина перестає читати, що підтверджує. Авторежим вирішує це інакше. Питань немає, але кожну дію, не дозволену правилами явно, перевіряє окрема модель-класифікатор.

Що вона бачить: ваші повідомлення, виклики інструментів та інструкції проєкту. Результати інструментів їй не показують — щоб текст із прочитаного файлу чи вебсторінки не міг умовити і її теж.

Що вона блокує типово: завантажити й одразу виконати скрипт із мережі, надіслати секрети назовні, викотити в продакшен, видалити дані в хмарі, видати права доступу, зробити `git push --force` чи `git reset --hard`. Що пропускає: роботу з файлами в проєкті, встановлення оголошених залежностей, запити на читання, звичайний push у гілку.

Якщо класифікатор заблокував три дії поспіль, авторежим призупиняється і повертаються звичайні питання.

Власні правила для класифікатора пишуться звичайним текстом в особистих налаштуваннях: які репозиторії та сервіси вважати своїми, що заборонено завжди.

```json title="~/.claude/settings.json"
{
  "autoMode": {
    "environment": [
      "$defaults",
      "Репозиторії організації example-org на GitHub — свої",
      "Бакет example-staging — тестовий, писати в нього можна"
    ],
    "hard_deny": [
      "$defaults",
      "Будь-які зміни в продакшен-базі даних"
    ]
  }
}
```

Це не шаблони, а речення людською мовою: їх читає модель-класифікатор. Рядок `"$defaults"` зберігає вбудовані правила, без нього ваш список замінив би їх. З налаштувань проєкту цей блок не читається — інакше чужий репозиторій міг би дозволити собі що завгодно.

І головне, що треба розуміти: авторежим заощаджує підтвердження, але межею безпеки його не вважає сама Anthropic. Це уважний спостерігач, а не стіна.

## Пісочниця та ізоляція

Дозволи вирішують, що агент *попросить* зробити. Ізоляція вирішує, що він *зможе* зробити, навіть якщо щось пішло не так. Варіантів кілька, від легкого до суворого.

### Пісочниця для команд

Пісочниця — це обмеження на рівні операційної системи для команд, які запускає агент. Команда і всі процеси, які вона породить, отримують урізаний доступ:

- **Запис** — лише в робочу теку і тимчасову директорію.
- **Мережа** — прямого виходу немає. Увесь трафік іде через локальний проксі, який пропускає лише дозволені домени.
- **Читання** — типово майже весь диск. Теки з ключами треба закривати явно.

```json title=".claude/settings.json"
{
  "sandbox": {
    "enabled": true,
    "network": {
      "allowedDomains": ["registry.npmjs.org", "*.githubusercontent.com"]
    },
    "filesystem": {
      "denyRead": ["~/.ssh", "~/.aws"]
    }
  }
}
```

На macOS пісочниця побудована на системному механізмі Seatbelt, на Linux і в WSL2 — на bubblewrap. **На Windows без WSL пісочниці немає**: команди виконуються як зазвичай. Якщо вона вам потрібна на Windows, запускайте Claude Code всередині WSL2.

Типово пісочниця вимкнена; вмикається командою `/sandbox`. У неї приємний побічний ефект: оскільки команда не може нічого зіпсувати за межами проєкту, її можна виконувати без питання. Підтверджень стає помітно менше.

Чого пісочниця не покриває, і це треба знати. Вона обгортає лише команди оболонки. Інструменти читання й правки файлів працюють поза нею і підкоряються правилам дозволів. Локальні MCP-сервери, хуки та моди теж запускаються поза пісочницею, з вашими правами.

### Окремі робочі копії

Друге завдання ізоляції — щоб паралельні сесії не заважали одна одній. Якщо два агенти правлять одні й ті самі файли в одній теці, вийде каша.

Рішення — git worktree. Це штатна можливість git: друга робоча тека того самого репозиторію на своїй гілці. Історія спільна, файли окремі.

```bash
claude --worktree feature-auth
```

Команда створює робочу копію в `.claude/worktrees/feature-auth/` на новій гілці й запускає в ній сесію. Фонові сесії та субагенти з ізоляцією роблять те саме автоматично. Копія без змін видаляється під час виходу сама.

Одна практична деталь: файли, яких немає в git, у нову копію не потрапляють. Якщо проєкту потрібен `.env`, перелічіть його у файлі `.worktreeinclude`, і він буде скопійований.

Важливо не плутати: worktree захищає ваші файли від інших агентів, а не машину від агента. Це ізоляція роботи, а не безпека.

### Контейнер і віртуальна машина

Найнадійніша ізоляція — запустити агента там, де нема чого псувати.

**Dev-контейнер.** В Anthropic є готова конфігурація: контейнер із Claude Code і мережевим екраном, що пропускає лише потрібні адреси. Усередині можна ввімкнути режим без питань, бо агентові доступний лише змонтований проєкт.

**Віртуальна машина.** Те саме, але межа ще жорсткіша. Про цей варіант докладно нижче, в розділі про віддалену роботу.

**Хмарна сесія.** Anthropic запускає агента на своїй віртуальній машині. Ваш комп'ютер не бере участі зовсім.

Зведення, щоб обирати:

| Спосіб | Від чого захищає | Чого не закриває |
|---|---|---|
| Правила дозволів | від випадкових дій | обходяться іншим способом зробити те саме |
| Авторежим | від явно небезпечних дій без питань | не є межею безпеки |
| Пісочниця | команди не вийдуть за проєкт і дозволені домени | інструменти файлів, MCP, хуки; немає на Windows без WSL |
| Worktree | сесії не заважають одна одній | не захищає машину |
| Контейнер, ВМ | агент не бачить вашу систему | те, що ви самі туди змонтували, і які ключі дали |

## Моделі, зусилля та міркування

Харнес один, а моделей за ним кілька, і в кожної є ручки.

**Модель** вибирається командою `/model` або прапорцем `--model`. Зазвичай пишуть не повний ідентифікатор, а коротку назву родини: `fable`, `opus`, `sonnet`, `haiku`. За короткою назвою завжди стоїть найсвіжіша модель родини. Старші моделі розумніші й дорожчі, молодші швидші й дешевші. Є і складений варіант `opusplan`: старша модель планує, середня виконує.

**Зусилля** (effort) — це те, скільки модель думає і перевіряє, перш ніж відповісти. Рівнів п'ять: `low`, `medium`, `high`, `xhigh`, `max`. Низький годиться для дрібних зрозумілих правок, високий — коли важлива перевірка, максимальний — для справді важких задач, зі спадною віддачею. Задається командою `/effort`. Зусилля впливає і на швидкість, і на витрату: на `max` та сама задача може коштувати в рази більше, ніж на `medium`.

**Міркування** (thinking) — це розмірковування моделі перед відповіддю, які ви бачите згорнутими. У теперішніх моделей воно адаптивне: модель сама вирішує, де подумати довше. Слово `ultrathink` у повідомленні піднімає зусилля на цей один хід.

**Швидкий режим** (`/fast`) — та сама модель, але відповідь іде приблизно вдвічі з половиною швидше й коштує дорожче. Лише для старших моделей.

**Радник** (`/advisor`) — друга, сильніша модель, з якою основна звіряється в ключові моменти задачі. Експериментальна можливість.

**Запасна модель** — якщо основна перевантажена, сесія продовжить на запасній. Задається прапорцем `--fallback-model`.

Окремо варто згадати **ultracode**. Це не рівень зусиль, а режим роботи: на кожну суттєву задачу агент сам пише сценарій із кількома субагентами і запускає його. Про сценарії — в розділі про взаємодію сесій. Витрата токенів у цьому режимі помітно вища.

Така сама ручка є й у частин системи. Субагентові та скілу можна призначити свою модель і своє зусилля в шапці файлу. Так розвідку віддають швидкій дешевій моделі, а головну розмову лишають сильній.

## Де запускається Claude Code

Харнес — це один і той самий рушій, у якого кілька лицьових сторін.

| Де | Що це | Особливості |
|---|---|---|
| Термінал | програма `claude` | повний набір можливостей, звідси все почалося |
| VS Code | розширення | правки показуються у вікні редактора, агент бачить виділений код |
| JetBrains | плагін | перегляд правок в IDE, спільний із терміналом сеанс |
| Застосунок Desktop | програма для macOS і Windows | кілька сесій поруч, перегляд діфів, вбудований браузер, підключення по SSH |
| Веб | claude.ai/code | хмарні сесії, працюють без вашого комп'ютера |
| Телефон | застосунок Claude | хмарні сесії та керування сесіями на комп'ютері |
| Slack | `@Claude` у каналі | завдання з листування йде в хмарну сесію |
| CI | GitHub Actions, GitLab CI/CD | запуск за подією, без людини |

Локальні поверхні ділять між собою все: налаштування, інструкції проєкту, MCP-сервери, історію сесій. Розмову, розпочату в терміналі, можна відкрити в застосунку командою `/desktop`. Хмарні сесії живуть окремо: у них своє середовище, і до файлів на вашому диску вони не дотягуються.

Встановлення. Основний спосіб — власний інсталятор: одна команда для macOS і Linux, одна для PowerShell. Є пакети для Homebrew, WinGet і npm. Підтримуються macOS 13 і новіші, Windows 10 і новіші, поширені дистрибутиви Linux; потрібно від 4 ГБ пам'яті. Встановлена так програма оновлюється сама, у фоні. Канал оновлень вибирається: найсвіжіший або стабільний, із затримкою близько тижня.

На Windows два варіанти. Запуск напряму: усе працює, крім пісочниці; бажано поставити Git for Windows, щоб в агента був Bash. Запуск у WSL2: це повноцінний Linux з усіма можливостями, включно з пісочницею, але без інтеграції з браузером Chrome.

## Браузер: які є варіанти

Агентові часто потрібно подивитися на результат своєї роботи: відкрити сторінку, натиснути кнопку, прочитати помилку в консолі. Способів багато, і вибирати між ними простіше за трьома питаннями.

**Чий це браузер.** Ваш справжній, з усіма входами в пошту і робочі сервіси, чи окремий чистий, де агент ні до чого вашого не дістанеться.

**Як агент бачить сторінку.** Тут три способи, і від них залежать точність і витрата токенів:

- *Знімок екрана.* Картинка, як її бачить людина. Універсально, але дорого за токенами, і влучати по кнопці доводиться за координатами.
- *Дерево доступності.* Це структурний опис сторінки, яким користуються програми читання з екрана: «кнопка „Увійти“, поле „Пошта“, посилання „Забули пароль“». Агент отримує його текстом, де в кожного елемента є короткий номер, і натискає за номером, а не за координатами. Дешевше й точніше за картинку.
- *Нутрощі браузера.* Консоль, мережеві запити, стилі, виміри швидкості — те, що ви бачите в інструментах розробника.

**Чи потрібне вікно.** На ноутбуку вікно є. У контейнері, на сервері й у CI його немає, і браузер має працювати в режимі без інтерфейсу (headless).

Зведення всіх варіантів:

| Варіант | Чий браузер | Як бачить сторінку | Без вікна | Хто робить |
|---|---|---|---|---|
| `WebFetch`, `WebSearch` | жодний | текст у переказі | так | вбудовано |
| Claude in Chrome | ваш, із входами | сторінка, знімки, консоль, мережа | ні | Anthropic |
| Вбудований браузер Desktop | чистий, у застосунку | сторінка і знімки | ні | Anthropic |
| Playwright MCP | свій профіль або ваш браузер | дерево доступності, за бажанням знімки | так | Microsoft |
| Playwright CLI | чистий типово | дерево доступності, на запит | так, типово | Microsoft |
| Chrome DevTools MCP | свій або вже запущений Chrome | дерево, знімки, консоль, мережа, виміри швидкості | так | команда Chrome DevTools |
| Firefox DevTools MCP | окремий профіль Firefox | дерево і знімки | так | Mozilla |
| Власний скрипт на Playwright чи Puppeteer | будь-який | що напишете в скрипті | так | ви й агент |
| Хмарний браузер | на серверах сервісу | залежить від сервісу | так | сторонні платні сервіси |
| Керування комп'ютером | будь-який, як вікно на екрані | знімок екрана | ні | Anthropic |

Тепер по черзі.

### Вбудовані інструменти

`WebFetch` і `WebSearch` — це не браузер. Вони годяться, щоб прочитати публічну сторінку документації, і не годяться для всього, де потрібен вхід, JavaScript чи натискання кнопок. Вони описані вище, в розділі про інструменти.

### Claude in Chrome: ваш справжній браузер

Це розширення для Chrome і Edge плюс міст до Claude Code. Вмикається прапорцем `claude --chrome` або командою `/chrome`. Агент працює в справжньому вікні вашого браузера, у новій вкладці, і бачить сайти так, як їх бачите ви: з вашими входами в пошту, панелі керування, трекери.

Що він уміє: переходити сторінками, натискати й заповнювати форми, читати текст сторінки, консоль і мережеві запити, робити знімки екрана, записувати GIF із ходом дій.

Це і сила, і ризик. Сила в тому, що агент може зробити щось у сервісі, де у вас уже відкритий сеанс, не отримуючи паролів. Ризик у тому самому. Тому доступ видається в розширенні для кожного сайту окремо, а на вході в акаунт і на капчі агент зупиняється й чекає на вас.

Як влаштований зв'язок. Розширення не може саме спілкуватися з програмою на комп'ютері, тому Claude Code під час першого вмикання реєструє в системі невеликий посередник (native messaging host). Через нього розширення й термінальна сесія обмінюються командами. У мене він лежить у `%APPDATA%\Claude Code\ChromeNativeHost`.

Обмеження: потрібні підписка і вхід через акаунт, із ключем API не працює; у WSL не працює; режиму без вікна немає; відкрите на сторінці системне вікно з питанням блокує керування.

### Вбудований браузер застосунку Desktop

У застосунку Desktop є панель браузера поруч із чатом. Профіль у неї свій, чистий, ваших входів там немає. Вона показує запущений застосунок проєкту та зовнішні сайти, і агент може в ній діяти. Дії на зовнішніх сайтах потребують підтвердження.

Для розробки це спокійніше, ніж розширення: агент бачить ваш сайт на локальному сервері, а до вашої пошти доступу не має.

### Playwright MCP

Playwright — це бібліотека Microsoft для автоматизації браузерів; на ній пишуть наскрізні тести. У неї є MCP-сервер, який дає агентові інструменти керування браузером: відкрити адресу, натиснути, ввести текст, зробити знімок.

Підключається однією командою:

```bash
claude mcp add playwright npx @playwright/mcp@latest
```

Або плагіном з офіційного маркетплейсу, який робить те саме:

```bash
claude plugin install playwright@claude-plugins-official
```

Головна особливість — типово агент працює з деревом доступності, а не з картинкою. Він запитує знімок сторінки й отримує текст приблизно такого вигляду:

```yaml
- heading "Вхід" [level=1]
- textbox "Пошта" [ref=e12]
- textbox "Пароль" [ref=e13]
- button "Увійти" [ref=e15]
- link "Забули пароль?" [ref=e16]
```

Далі він каже «натисни `e15`», і сервер натискає саме цю кнопку. Моделі не треба вгадувати координати, і токенів іде помітно менше, ніж на картинку. Режим із координатами теж є: він вмикається прапорцем `--caps=vision` і потрібен там, де дерево не допомагає, наприклад на полотні з графікою.

Що налаштовується прапорцями:

| Прапорець | Що робить |
|---|---|
| `--browser` | який браузер: Chrome, Edge, Firefox чи WebKit |
| `--headless` | працювати без вікна; типово вікно показується |
| `--isolated` | профіль лише в пам'яті, після закриття нічого не лишається |
| `--user-data-dir` | свій шлях до профілю |
| `--storage-state` | завантажити збережені куки в ізольовану сесію |
| `--extension` | підключитися до вашого вже відкритого Chrome чи Edge через розширення Playwright |
| `--cdp-endpoint` | підключитися до браузера, запущеного з налагоджувальним портом |

Про профіль варто розуміти одне. Типово він постійний: сервер заводить власну теку профілю й зберігає в ній входи між запусками. Це не ваш особистий профіль, але якщо ви один раз увійшли в сервіс у цьому вікні, вхід збережеться. Для тестів, де потрібна чистота, ставлять `--isolated`.

Самі автори попереджають про дві речі. Сервер не є межею безпеки: списки дозволених адрес не покривають перенаправлень. І серед інструментів є виконання довільного коду в браузері, що рівносильно повному доступу до сторінки.

### Playwright CLI

У того самого Playwright є другий спосіб, зроблений спеціально для агентів у терміналі: звичайна програма командного рядка замість MCP-сервера.

```bash
npm install -g @playwright/cli@latest
playwright-cli install --skills
```

Друга команда ставить скіли для Claude Code: з них агент дізнається, які команди є і як ними користуватися. Далі він просто викликає програму через `Bash`:

```bash
playwright-cli open https://example.com
playwright-cli snapshot --depth=3
playwright-cli click e15
```

У чому різниця з MCP-сервером. MCP-сервер повертає дерево сторінки після кожної дії, і воно осідає в контексті. Програма командного рядка друкує лише те, що запитали: знімок потрібної глибини, результат пошуку елемента. Автори Playwright самі пишуть, що для агентів-програмістів такий шлях економніший, а MCP-сервер краще там, де треба довго досліджувати сторінку зі збереженням стану.

Типово браузер тут запускається без вікна і з чистим профілем у пам'яті; вікно вмикається прапорцем `--headed`, збереження профілю — прапорцем `--persistent`.

### Chrome DevTools MCP

Цей сервер робить команда інструментів розробника Chrome. Натискати й вводити текст він теж уміє, але його сенс в іншому: він відкриває агентові те, що ви бачите в панелі розробника.

- **Швидкість.** Записати трасування завантаження сторінки й розібрати, що її гальмує.
- **Мережа.** Список запитів, заголовки й тіла відповідей.
- **Консоль.** Повідомлення та помилки зі стеком, приведеним до вихідників.
- **Стилі.** Які правила CSS реально застосувалися до елемента.
- **Аудит.** Перевірка Lighthouse.
- **Пам'ять.** Знімки купи для пошуку витоків.

Ставиться плагіном:

```bash
claude plugin marketplace add ChromeDevTools/chrome-devtools-mcp
claude plugin install chrome-devtools-mcp@chrome-devtools-plugins
```

Він може запустити власний Chrome, а може підключитися до вже працюючого. Для цього Chrome запускають із налагоджувальним портом і окремою текою профілю, а серверу передають адресу:

```bash
chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug
npx -y chrome-devtools-mcp@latest --browser-url http://127.0.0.1:9222
```

Вибір між ним і Playwright простий. «Пройди по формі й перевір, що замовлення створюється» — це Playwright. «Сторінка вантажиться чотири секунди, з'ясуй чому» — це Chrome DevTools. Працює він лише з Chrome. І типово надсилає Google статистику використання; вона вимикається прапорцем `--no-usage-statistics`.

### Firefox DevTools MCP

У Mozilla є свій офіційний сервер, поки в ранній версії:

```bash
claude mcp add firefox-devtools npx @mozilla/firefox-devtools-mcp@latest
```

Влаштований він схоже: знімок сторінки з номерами елементів, натискання і ввід за номером, знімки екрана, режим без вікна. Потрібен, коли помилка відтворюється саме у Firefox. Автори радять заводити для нього окремий профіль і не підключати основний.

Для Safari окремого сервера я не знайшов. Рушій WebKit, на якому він побудований, доступний через Playwright: прапорець `--browser webkit`.

### Власний скрипт

Найпростіший спосіб часто забувають: жодних серверів, агент пише звичайний скрипт на Playwright чи Puppeteer і запускає його через `Bash`.

```javascript title="check-login.mjs"
import { chromium } from 'playwright';

const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('http://localhost:3000/login');
await page.getByLabel('Пошта').fill('user@example.com');
await page.getByRole('button', { name: 'Увійти' }).click();
console.log(await page.getByRole('alert').textContent());
await page.screenshot({ path: 'login.png' });
await browser.close();
```

Агент запускає скрипт, читає надрукований текст, а знімок відкриває інструментом `Read` і дивиться на нього як на картинку.

У цього способу три переваги. У контекст потрапляє лише те, що скрипт надрукував. Скрипт лишається в репозиторії й перетворюється на тест. І він однаково працює на ноутбуці, в контейнері та в CI. Недолік один: це не діалог зі сторінкою. Кожне «а що там тепер» — новий запуск.

Якщо в проєкті вже є наскрізні тести, це і є найкращий спосіб перевірки: агент дописує тест і запускає його. На цьому ж побудовані вбудовані скіли `/run` і `/verify`: вони самі визначають тип проєкту, запускають застосунок і дивляться на результат, а `/run-skill-generator` записує знайдений рецепт запуску в скіл проєкту.

### Хмарні браузери та сервіси збору даних

Окремий клас — сервіси, де браузер працює на чужих серверах, а агент керує ним через MCP. Усі вони сторонні й платні або з обмеженим безкоштовним тарифом.

| Сервіс | Для чого |
|---|---|
| Browserbase | браузери в хмарі; керування описом дії словами |
| browser-use | керує вашим локальним Chrome або хмарним браузером сервісу |
| Firecrawl | не керування, а збір: сторінка чи цілий сайт перетворюються на Markdown |
| Bright Data | збір даних і браузер з обходом захисту від роботів |

Вони потрібні там, де локального браузера мало: сотні сторінок паралельно, сайти із захистом від автоматизації, інша країна в адресі. Для перевірки власного застосунку вони не потрібні. І пам'ятайте, що сторінки й введені дані при цьому проходять через сервери третьої сторони.

### Як вибрати

- **Перевірити свій сайт на локальному сервері** — вбудований браузер Desktop або Playwright; у проєкті з тестами — власний скрипт.
- **Зробити щось у сервісі, де ви вже ввійшли** — Claude in Chrome. Або Playwright із прапорцем `--extension`.
- **Знайти, чому сторінка повільна або що падає в консолі** — Chrome DevTools MCP.
- **Робота на сервері, в контейнері, в CI** — Playwright CLI, Playwright MCP з `--headless` або власний скрипт. Розширення для Chrome там не працює.
- **Помилка лише в одному браузері** — Playwright з потрібним `--browser` або сервер Mozilla.
- **Масовий збір даних** — хмарні сервіси.

Два застереження для всіх варіантів одразу. Вміст сторінки — це чужий текст, і в ньому можуть бути інструкції, адресовані агентові; чим більше у браузера ваших входів, тим дорожча помилка. І кожен MCP-сервер браузера запускається поза пісочницею, з вашими правами.

## Настільні та мобільні застосунки

З браузером зрозуміло. А що, коли потрібна програма — не сайт? Настільний застосунок, редактор макетів, середовище розробки, симулятор телефона. Способів дістатися й до них теж кілька, і загальний принцип той самий, що з браузером: чим вужчий і точніший інструмент, тим краще. Дивитися на екран і рухати мишу — останній засіб.

Сам Claude Code перебирає варіанти в такому порядку: готовий конектор або MCP-сервер програми → команда в терміналі → браузер → панель симулятора → керування екраном. Розберемо їх у тому самому порядку.

### Не чіпати вікно: файли й командний рядок

Найнадійніший спосіб працювати з програмою — не відкривати її взагалі.

**Файли.** Документ Word, таблиця Excel, презентація — це файли відомих форматів. Агент читає й створює їх бібліотеками, невеликим скриптом, і для цього є готові скіли. Застосунок Office при цьому не запускається.

**Командний рядок.** У багатьох настільних програм є режим без вікна. Blender рендерить сцену з командного рядка, Android Studio збирає проєкт через Gradle, Xcode — через `xcodebuild`, Docker Desktop керується командою `docker`. Агентові досить інструмента `Bash`.

### Скриптові інтерфейси операційної системи

Наступний рівень — програма запущена, але керують нею не мишею, а через програмний інтерфейс, який передбачила система. До них агент дістається звичайними командами оболонки.

| Система | Інтерфейс | Що вміє |
|---|---|---|
| Windows | PowerShell і COM | керувати застосунками Office як об'єктами: відкрити книгу, заповнити клітинки, зберегти |
| Windows | UI Automation | читати дерево елементів будь-якого вікна і натискати їх; це інтерфейс для програм читання з екрана |
| macOS | AppleScript, JXA | надсилати команди застосункам, які підтримують сценарії: Finder, Пошта, Safari, Нотатки |
| Linux | xdotool, ydotool | імітувати клавіатуру й мишу, рухати вікна |

Приклад для Windows. Так агент записує значення у відкриту таблицю Excel, не бачачи її вікна:

```powershell
$excel = New-Object -ComObject Excel.Application
$excel.Visible = $true
$book = $excel.Workbooks.Open("C:\reports\sales.xlsx")
$book.Sheets.Item(1).Range("B2").Value2 = 1250
$book.Save()
$excel.Quit()
```

А так на macOS він просить Finder показати теку:

```bash
osascript -e 'tell application "Finder" to open folder "Documents" of home'
```

Відмінність від керування мишею принципова. Команда «запиши 1250 у клітинку B2» або виконалася, або повернула помилку. Їй не заважає ні роздільна здатність екрана, ні вікно, що виринуло згори, ні змінена тема оформлення.

На macOS такі сценарії потребують дозволів у системних налаштуваннях: «Автоматизація» для команд застосункам і «Універсальний доступ» для керування інтерфейсом. На Linux `xdotool` працює лише під X11, для Wayland потрібен `ydotool`.

### MCP-сервери програм

Багато програм тепер самі дають агентам офіційний вхід — MCP-сервер. Це найзручніший шлях: програма оголошує зрозумілі інструменти, а не змушує вгадувати, куди натиснути.

| Програма | Сервер | Що дає |
|---|---|---|
| Figma | офіційний, від Figma | контекст макета, змінні, знімки, запис на полотно |
| IDE від JetBrains | вбудований в IDE з версії 2025.2 | збірка, помилки у файлі, запуск конфігурацій, пошук і рефакторинг |
| Xcode | офіційний плагін від Apple | збірка й тести, попередній перегляд SwiftUI, симулятори, логи збірки |
| Unity | офіційний плагін і сервери спільноти | сцени, об'єкти, скрипти, тести |
| Blender | від спільноти | виконання Python усередині Blender, рендер сцени |
| Симулятор iOS, Android | від спільноти | дерево елементів екрана, натискання, знімки |

Підключається такий сервер як будь-який інший. Наприклад, Figma:

```bash
claude mcp add --transport http figma https://mcp.figma.com/mcp
```

З IDE окрема історія: окрім MCP-сервера, у JetBrains і VS Code є власна інтеграція з Claude Code. Через неї агент бачить відкритий файл, виділений фрагмент і помилки, які показує редактор, а правки з'являються у вікні порівняння.

Є й сервери загального призначення, які відкривають агентові весь робочий стіл: для Windows — сервер від спільноти, який читає дерево елементів вікон через UI Automation, натискає, друкує і запускає PowerShell; для macOS — сервер, який виконує сценарії AppleScript. Це потужно і тому небезпечно: по суті, повний доступ до системи. Самі автори про це попереджають. До серверів від спільноти варто ставитися як до будь-якої чужої програми з такими правами: подивитися код, подивитися, що він надсилає назовні.

### Застосунки на Electron

Багато настільних програм — Slack, VS Code, Discord, Notion — написані на Electron. Усередині це браузер Chromium, і до нього застосовне все з розділу про браузери.

Якщо це ваш власний застосунок, у Playwright є підтримка Electron, поки експериментальна: скрипт запускає застосунок, отримує його вікна й працює з ними як зі сторінками.

```javascript title="check-app.mjs"
import { _electron as electron } from 'playwright';

const app = await electron.launch({ args: ['main.js'] });
const window = await app.firstWindow();
await window.getByRole('button', { name: 'Новий документ' }).click();
await window.screenshot({ path: 'app.png' });
await app.close();
```

Другий шлях — запустити застосунок із налагоджувальним портом, прапорцем `--remote-debugging-port`, і підключити до цього порту Chrome DevTools MCP так само, як до звичайного Chrome.

### Мобільні застосунки

**iOS.** У застосунку Desktop на macOS є панель симулятора iOS. Агент збирає застосунок, ставить його в симулятор, натискає, вводить текст і робить знімки. Керування екраном для цього не використовується: панель працює через штатні засоби Apple, тому системні дозволи на запис екрана не потрібні. Працює лише із симулятором, не зі справжнім телефоном.

З термінала те саме робиться командою `xcrun simctl` і MCP-серверами для симулятора.

**Android.** Тут усе тримається на `adb`, штатній утиліті Android. Через неї агент ставить збірку на емулятор або підключений телефон, запускає екран, читає логи, робить знімок, натискає за координатами:

```bash
adb install -r app/build/outputs/apk/debug/app-debug.apk
adb shell am start -n com.example.app/.MainActivity
adb logcat -d -t 200
adb exec-out screencap -p > screen.png
```

Є й MCP-сервери для мобільних пристроїв, які замість координат дають дерево елементів екрана — так само, як Playwright для сторінок.

### Керування комп'ютером: коли решта не підійшла

Керування комп'ютером (computer use) — це коли агент працює з машиною як людина: дивиться на знімок екрана, рухає мишу, натискає клавіші. Так можна дістатися до того, у чого немає ні командного рядка, ні програмного інтерфейсу: стара корпоративна програма, панель керування обладнанням, пропрієтарний інструмент.

Де це доступно. У застосунку Desktop — на macOS і на Windows. У терміналі — лише на macOS, вмикається через `/mcp`. Можливість позначена як попередня і потребує особистої підписки.

Як це влаштовано з погляду безпеки:

- Доступ видається за застосунками. Агент просить дозвіл на конкретну програму, і ви даєте його на сесію.
- У застосунків різні рівні. Браузери — лише дивитися. Термінали й редактори коду — дивитися й клікати, але не друкувати: інакше це був би повний доступ до оболонки в обхід усіх правил. Решта — повне керування.
- Працювати може лише одна сесія одночасно. Інші програми на час ходу ховаються, а термінал із самим Claude Code на знімки не потрапляє.
- Esc перериває роботу з будь-якого місця.

Чому це останній засіб. Воно найповільніше: кожна дія — знімок екрана і запит до моделі. Найкрихкіше: зсунулася кнопка — агент схибив. І пісочниці тут немає: агент діє на справжньому робочому столі, з вашими правами, а вміст екрана — ще один канал, через який у нього може потрапити чужий текст з інструкціями.

Поруч стоїть Dispatch — можливість дати завдання з телефона застосунку Desktop на вашому комп'ютері. Він сам запускає сесію, а вам приходить сповіщення, коли роботу закінчено або потрібне підтвердження.

### Як вибрати

| Що потрібно | Чим робити |
|---|---|
| Створити або змінити документ, таблицю, презентацію | робота з файлом, без запуску програми |
| Зібрати, запустити, відрендерити | командний рядок програми |
| Керувати застосунком Office на Windows | PowerShell і COM |
| Команди застосункам на macOS | AppleScript |
| Макети, IDE, ігровий рушій, 3D-редактор | MCP-сервер цієї програми |
| Власний застосунок на Electron | Playwright |
| Застосунок для iOS | панель симулятора в Desktop або `xcrun simctl` |
| Застосунок для Android | `adb` |
| Програма без жодного програмного входу | керування комп'ютером |

## Робота без людини

Усе, що описано вище, — про інтерактивний режим, де ви сидите поруч. Але той самий рушій запускається і без інтерфейсу.

```bash
claude -p "Знайди в логах причину падіння й опиши її одним абзацом" --output-format json
```

Прапорець `-p` означає: виконати завдання, надрукувати результат і вийти. Вивід буває трьох видів: звичайний текст, один JSON із результатом, вартістю та ідентифікатором сесії, або потік JSON-подій у міру роботи. Можна задати схему, і тоді відповідь прийде у строго заданій структурі.

Що важливо в цьому режимі:

- **Питати нема кого.** Усе, що потребувало б підтвердження, відхиляється. Потрібні дії дозволяють заздалегідь: прапорцем `--allowedTools` або режимом дозволів.
- **Вікно довіри теці не показується.** Тому запускати так варто лише в теках, яким ви довіряєте.
- **Є обмежувач бюджету**: `--max-budget-usd` зупинить роботу, коли витрачено задану суму.
- **Є «голий» режим** `--bare`: без хуків, плагінів, пам'яті й автоматичного читання інструкцій. Він дає передбачуваний результат у скриптах, де середовище машини не повинне впливати на відповідь.

На цьому режимі побудовані готові інтеграції: дія для GitHub Actions і шаблон для GitLab CI, які запускають агента на подію в репозиторії — новий запит на злиття, впала збірка, згадка в коментарі.

А якщо потрібно вбудувати агента у власну програму, є **Agent SDK** для Python і TypeScript. Це той самий цикл, ті самі інструменти і та сама робота з контекстом, тільки у вигляді бібліотеки: ви викликаєте функцію і отримуєте потік подій.

## Фонові сесії

Інтерактивна сесія займає термінал. Якщо завдання на годину, а дивитися на нього ні до чого, сесію можна відвести у фон.

```bash
claude --bg "Онови залежності й полагодь те, що зламається"
claude agents
```

Перша команда запускає сесію у фоні й одразу повертає керування. Друга відкриває екран зі списком усіх фонових сесій, розкладених за станом: чекає на вашу відповідь, працює, закінчила. Зі списку в будь-яку можна ввійти, подивитися й вийти назад, не зупиняючи її. Уже поточну сесію відправляє у фон команда `/background`.

Як це працює всередині. За фоновими сесіями стежить службовий процес-супервізор. Він стартує сам, тримає список сесій, перезапускає впалі й зупиняє ті, що годину простоюють без нагляду. Його стан лежить у теках `daemon` і `jobs` домашньої директорії. Сон комп'ютера сесії переживають, перезавантаження — ні: після нього вони позначаються зупиненими і продовжуються, коли ви в них увійдете.

Щоб фонові сесії не заважали вам і одна одній, кожна перед першою правкою переїжджає у власну робочу копію репозиторію. В основну гілку вони не пушать і нічого не зливають самі.

## Як сесії й агенти взаємодіють

Способів змусити кілька агентів працювати разом тепер чотири. Вони розв'язують різні задачі, і вибирати між ними простіше, якщо бачити їх поруч.

| | Субагенти | Сценарії (workflows) | Команди агентів | Повідомлення між сесіями |
|---|---|---|---|---|
| Хто керує | головний агент | скрипт | агент-лідер | ви або самі агенти |
| Спілкуються між собою | ні, лише звіт головному | ні, результати збирає скрипт | так, напряму | так |
| Контекст | у кожного свій, чистий | у кожного свій | у кожного свій | у кожної сесії свій |
| Кількість | одиниці | до сотень | кілька | скільки сесій відкрито |
| Коли брати | розвідка, незалежний шматок роботи | велика однотипна робота | задача, де учасникам треба сперечатися й домовлятися | уже поточні сесії мають обмінятися відомостями |

**Субагенти** описані вище: головний агент роздає завдання й отримує звіти. Між собою вони не спілкуються.

**Сценарії** (dynamic workflows). Коли субагентів потрібно багато, керувати ними з розмови стає незручно: кожен звіт потрапляє в контекст головного агента. Сценарій розв'язує це інакше. Агент пише невеликий скрипт на JavaScript, а харнес його виконує: запускає агентів паралельно чи ланцюжком, передає результати з кроку в крок. Проміжні результати лишаються у змінних скрипта і контекст не займають. Типовий приклад — перевірити двадцять файлів за п'ятьма критеріями і кожну знахідку перевірити ще раз окремим агентом. Запускається словом `ultracode` у повідомленні або проханням «використай workflow». Перед запуском харнес питає підтвердження, бо десятки агентів — це десятки сесій за витратою.

**Команди агентів** (agent teams) — експериментальна можливість, типово вимкнена. Тут учасники рівноправніші: є лідер і кілька напарників, спільний список завдань і поштові скриньки. Напарники пишуть одне одному напряму, беруть завдання зі спільного списку й позначають зроблене. Це підходить там, де робота потребує обговорення: один досліджує гіпотезу, інший її спростовує.

**Повідомлення між сесіями.** Звичайні незалежні сесії — в сусідніх терміналах, у фоні — теж можуть листуватися. Агент бачить список доступних співрозмовників і надсилає повідомлення за назвою сесії. На одній машині повідомлення йдуть напряму, через локальний канал, минаючи сервери. Між машинами — через сервери Anthropic, і для цього потрібен вхід в акаунт.

Тут вбудовано захист, який варто розуміти. Повідомлення від іншої сесії приходить як звичайний текст із позначкою, від кого воно. Воно не може підтвердити запит дозволу, змінити налаштування чи виконати команду. Чужа сесія може попросити, але не наказати. А в налаштуваннях можна вибрати, що робити з вхідними: доставляти, притримувати чи відхиляти.

## Розклад

Запускати агента за часом можна на трьох рівнях.

**Усередині сесії.** Команда `/loop 5m перевір, чи закінчилася збірка` повторює завдання, поки сесія відкрита. Без інтервалу агент сам вибирає паузу між перевірками. Працює це лише поки сесія жива й простоює.

**На вашій машині.** Застосунок Desktop уміє запускати завдання за розкладом локально, з доступом до ваших файлів. Комп'ютер при цьому має бути ввімкнений.

**У хмарі.** Команда `/schedule` створює завдання, яке виконується на серверах Anthropic. Ваш комп'ютер може бути вимкнений. Запускається воно за розкладом (не частіше разу на годину), запитом до API або за подією в GitHub, наприклад під час відкриття запиту на злиття.

## Віддалена робота

Остання велика тема: як працювати з агентом, який перебуває не там, де ви. Варіантів чотири, і вони відрізняються тим, де виконується код.

### Віддалене керування

Агент працює на вашому комп'ютері, а керуєте ви ним з телефона або з браузера на іншій машині.

```bash
claude remote-control
```

Після цієї команди сесія з'являється на claude.ai/code і в застосунку на телефоні. Звідти можна писати повідомлення, дивитися, що робить агент, підтверджувати дозволи.

Як влаштоване з'єднання. Ваш комп'ютер сам підключається до серверів Anthropic вихідним HTTPS-запитом і чекає на повідомлення. Вхідних портів він не відкриває, прокидати нічого не треба. Код, файли, інструменти й MCP-сервери лишаються на вашій машині; через сервери проходить лише листування: повідомлення, відповіді та відомості про виклики інструментів.

Вимоги: вхід через акаунт із підпискою, з ключем API це не працює. І процес має продовжувати працювати: закрили термінал — керування зникло.

### Хмарні сесії

Тут агент працює на віртуальній машині Anthropic. Ваш комп'ютер не потрібен узагалі.

```bash
claude --cloud "Додай перевірку формату телефона у форму реєстрації"
```

Те саме робиться з сайту claude.ai/code і з телефона. Машина отримує ваш репозиторій з GitHub, агент працює в окремій гілці й наприкінці пропонує запит на злиття.

Що варто знати про це середовище:

- **Середовище налаштовується.** Можна задати скрипт підготовки, який поставить потрібні пакети, змінні середовища та рівень доступу в мережу: жодного, обмежений (реєстри пакетів і GitHub) або повний.
- **Ключі GitHub у машину не потрапляють.** Вони лишаються на серверах Anthropic, а запити до GitHub йдуть через проксі, який підставляє їх сам.
- **Машина засинає.** Після кількох хвилин простою її ставлять на паузу; фонові процеси при цьому не зберігаються.
- **Сесію можна забрати до себе.** Команда `/teleport` переносить хмарну розмову і гілку у ваш термінал. У зворотний бік, з термінала в хмару, готову сесію перенести не можна.

### Підключення по SSH із застосунку

У застосунку Desktop у списку середовищ є пункт SSH. Ви вказуєте адресу машини, застосунок сам ставить на неї Claude Code і запускає там сесію. Інтерфейс лишається у вас, а код виконується на віддаленій машині. Постійні підключення описуються в налаштуваннях:

```json title="~/.claude/settings.json"
{
  "sshConfigs": [
    {
      "id": "dev-vm",
      "name": "Dev VM",
      "sshHost": "deploy@dev.example.com",
      "sshPort": 22
    }
  ]
}
```

### Віртуальна машина в мережі: як зібрати самому

Тепер частий практичний випадок. У вас є власна віртуальна машина — в хмарі або в локальній мережі — і ви хочете, щоб агент працював на ній. Причин зазвичай дві. Перша — ізоляція: на машині немає ваших особистих файлів і ключів, і агентові можна дозволити більше. Друга — безперервність: машина не засинає разом з ноутбуком.

Claude Code — звичайна програма для Linux, тому способів кілька.

**Спосіб перший: SSH і tmux.** Заходите на машину по SSH, запускаєте `tmux`, у ньому — `claude`. tmux потрібен, щоб сесія пережила обрив зв'язку: відключилися, підключилися знову, повернулися в той самий термінал. Це найпростіший варіант, і працює він усюди.

**Спосіб другий: віддалене керування з машини.** На машині в tmux запускаєте `claude remote-control` і далі працюєте з нею з телефона чи з браузера. SSH потрібен лише для першого запуску. Вхідні порти відкривати не треба, бо машина підключається назовні сама. Для команди `claude remote-control` є серверний режим: одна така команда приймає кілька сесій, кожну можна запускати у своїй робочій копії репозиторію.

**Спосіб третій: фонові сесії.** На машині запускаєте завдання через `claude --bg` і дивитеся на них через `claude agents`. Супервізор тримає їх без відкритого термінала.

**Спосіб четвертий: застосунок Desktop по SSH**, описаний вище. Зручний, якщо хочеться графічний інтерфейс і діфи, а не термінал.

**Спосіб п'ятий: без інтерфейсу.** Скрипт або планувальник на машині викликає `claude -p` із завданням. Підходить для нічних прогонів і обробки черги.

Спільне для всіх способів питання — як увійти в акаунт на машині без браузера. Варіанти такі:

| Спосіб входу | Що дає | Чого не дає |
|---|---|---|
| Звичайний вхід (`/login`) | усе, що є в підписці | вимагає один раз відкрити посилання в браузері на іншому пристрої |
| Довгоживучий токен (`claude setup-token`) | запити до моделі за підпискою, зручно для скриптів | віддалене керування і браузер |
| Ключ API | запити до моделі з оплатою за токенами | усе, що прив'язане до підписки: віддалене керування, хмарні сесії |

І пара порад із практики. Якщо машину виділено під агента, увімкніть на ній пісочницю: це Linux, там вона працює повністю. Давайте машині окремий ключ доступу до репозиторію з мінімальними правами, а не свій особистий. І пам'ятайте, що ізоляція машини захищає вашу систему, але не те, до чого сама машина може дістатися мережею.

Для організацій є ще один варіант — власні середовища для хмарних сесій. Ви запускаєте на своїй інфраструктурі процес-виконавець, він підключається до серверів Anthropic вихідним з'єднанням, і хмарні сесії з веб-інтерфейсу виконуються на ваших машинах, усередині вашої мережі. Це бета для корпоративних тарифів.

## Провайдери та локальні моделі

Звідки береться модель. Основних шляхів два: підписка Claude або ключ API з оплатою за токенами. Для компаній є третій: моделі Claude через хмару — Amazon Bedrock, Google Cloud або Microsoft Foundry. Вибирається змінною середовища.

Важливо розуміти, що частина можливостей прив'язана саме до підписки та серверів Anthropic. Через хмарного провайдера або за ключем API не працюють віддалене керування, хмарні сесії, розширення для браузера, керування комп'ютером, застосунок Desktop. Сам цикл агента, інструменти, пам'ять, скіли, хуки та MCP працюють скрізь однаково.

Чи можна запустити Claude Code на чужій або локальній моделі? Офіційно — ні: Anthropic такий режим не підтримує. Технічно адресу API підміняють змінною `ANTHROPIC_BASE_URL`, і деякі вендори документують підключення своїх моделей таким способом. Але системний промпт та інструменти Claude Code розраховані на моделі Claude, і якість з іншими помітно нижча. Якщо потрібна робота на власних моделях, краще взяти харнес, який для цього зроблений.

## Ліміти й вартість

На підписці витрата обмежена вікнами: п'ятигодинним і тижневим, плюс окремі тижневі ліміти на старші моделі. Вони спільні для всього акаунта: термінал, застосунок, хмарні сесії та звичайний чат витрачають одну квоту. Скільки лишилося, показує `/usage`; там же видно, що саме витрачає ліміт — які скіли, субагенти й MCP-сервери.

За ключем API лімітів за вікнами немає, оплата йде за токени. Для орієнтиру: документація називає середню цифру близько 13 доларів на розробника за активний день.

З будови, описаної вище, прямо випливає, що саме коштує дорого:

- **Довга сесія після паузи.** Кеш охолов, і вся розмова оплачується заново.
- **Паралельні агенти.** Кожен субагент, напарник чи фонова сесія — окрема розмова зі своїм контекстом.
- **Високе зусилля і старша модель** там, де задача цього не потребує.
- **Завдання за розкладом.** Кожне спрацювання надсилає повний контекст.
- **Роздуті інструкції.** Вони оплачуються в кожному запиті кожної сесії.

## Що йде з вашої машини

Коротка, але важлива частина.

**Що надсилається.** На сервери Anthropic іде те, що потрапило в запит: ваші повідомлення, вміст прочитаних файлів, вивід команд, відповіді моделі. Файли, які агент не читав, нікуди не надсилаються.

**Навчання.** На особистих тарифах використання ваших даних для навчання моделей — це перемикач у налаштуваннях приватності. На корпоративних тарифах і за API дані для навчання типово не використовуються.

**Зберігання на серверах.** Типово 30 днів; якщо на особистому тарифі дозволено навчання — до п'яти років.

**Зберігання у вас.** Розмови лежать у домашній теці відкритим текстом 30 днів. Про це варто пам'ятати, коли агент читає файли із секретами.

**Телеметрія.** Метрики використання та звіти про помилки вимикаються змінними середовища; одна змінна вимикає весь необов'язковий трафік одразу.

**Захист від шкідливих інструкцій.** Текст, який агент прочитав на вебсторінці, у файлі чи у відповіді інструмента, може містити команди, адресовані йому. Проти цього працює кілька шарів одразу: запити дозволів, переказ вебсторінок окремою моделлю, вікно довіри для нової теки, підтвердження для MCP-серверів проєкту. Жоден шар не дає гарантії. Тому з недовіреним вмістом — чужий репозиторій, незнайомі сайти — розумно працювати в ізольованому середовищі.

## Чим Claude Code відрізняється від схожих інструментів

Усі сучасні харнеси для програмування влаштовані за однією схемою: цикл, інструменти, інструкції проєкту, дозволи. Відрізняються вони рішеннями в деталях. Коротко про головні; докладне порівняння понад сорока інструментів — в [окремій статті](/uk/ai-agent-harnesses/).

| | Claude Code | Codex | Cursor | GitHub Copilot | OpenCode |
|---|---|---|---|---|---|
| Хто робить | Anthropic | OpenAI | Anysphere | GitHub | спільнота, команда SST |
| Вихідний код | закритий | CLI відкритий | закритий | CLI закритий, розширення відкрите | відкритий |
| Головна форма | термінал | термінал і хмара | власний редактор | редактор і GitHub | термінал |
| Моделі | лише Claude | моделі OpenAI | багатьох вендорів | багатьох вендорів | будь-які, включно з локальними |
| Інструкції | `CLAUDE.md`, правила за шляхами | `AGENTS.md` | `.cursor/rules` | `copilot-instructions.md` | `AGENTS.md` |
| Пошук по коду | агентний, без індексу | агентний | індекс з ембедингами плюс агентний | індекс плюс агентний | агентний |
| Пісочниця | за бажанням; немає на Windows без WSL | увімкнена типово на трьох ОС | увімкнена на macOS і Linux | за бажанням | немає |
| Хмарний режим | є | є | є | є | немає |

Що з цього випливає на практиці.

**Сильні сторони Claude Code** — глибина налаштування і робота без нагляду. Чотири рівні інструкцій, правила з прив'язкою до шляхів, скіли, субагенти зі своєю моделлю, три десятки подій для хуків, моди, сценарії з десятками агентів, фонові та хмарні сесії. Ні в кого більше немає такого набору цілком.

**Слабкі сторони** — закритий код і прив'язка до одного вендора. Працювати можна лише з моделями Claude, а підписка діє лише в продуктах Anthropic. Пісочниця не ввімкнена типово і не працює на Windows без WSL — у Codex вона ввімкнена одразу і на всіх трьох системах.

**Що переноситься.** Файли з теки `.claude` стали чимось на кшталт спільного формату: скіли, правила й хуки частково читають Cursor, Copilot, OpenCode та інші. А `AGENTS.md`, який розуміють майже всі, Claude Code читає, якщо немає власного файлу інструкцій. Команда `/import` переносить налаштування у зворотний бік — з Codex, Gemini CLI і Cursor.

## Коротко

- Claude Code — це харнес: програма на вашому комп'ютері, яка дає моделі інструменти й керує тим, що модель бачить. Модель думає, харнес робить.
- Робота йде циклом: модель просить викликати інструмент, харнес виконує й повертає результат, і так до відповіді без викликів. Кожен запит несе всю розмову.
- Правка файлу — це точна заміна унікального фрагмента. Пошук — звичайний пошук по файлах, без індексу.
- Контекст стискається сам. Стиснення переживає те, що записано у файли: інструкції, правила, пам'ять. Сказане лише в чаті може загубитися.
- Знання передається трьома способами: інструкції та правила (завжди в контексті), скіли (на вимогу), автопам'ять (пише сам агент, лежить у домашній теці).
- Субагент — окремий контекст для окремої задачі. Заощаджує головний контекст, але втрачає деталі під час передачі й коштує як ще одна сесія.
- Хук — код, який харнес виконує сам. Усе, що має відбуватися завжди, робиться хуком, а не рядком в інструкціях.
- Розмови, пам'ять і копії файлів лежать у `~/.claude` відкритим текстом. Налаштування проєкту — в `.claude` у репозиторії.
- Дозволи й авторежим захищають від випадковостей. Справжню межу дають пісочниця, контейнер і віртуальна машина.
- Один рушій працює в терміналі, редакторі, застосунку, хмарі та без інтерфейсу. На власній віртуальній машині він запускається як звичайна програма для Linux, а керувати ним можна з телефона, не відкриваючи портів.

## Джерела

- [How Claude Code works](https://code.claude.com/docs/en/how-claude-code-works) — цикл агента, контекст, сесії.
- [Tools reference](https://code.claude.com/docs/en/tools-reference) — усі вбудовані інструменти та їхня поведінка.
- [Explore the context window](https://code.claude.com/docs/en/context-window) — що завантажується в контекст і що переживає стиснення.
- [Explore the .claude directory](https://code.claude.com/docs/en/claude-directory) — файли проєкту та домашньої теки.
- [Memory](https://code.claude.com/docs/en/memory), [Skills](https://code.claude.com/docs/en/skills), [Subagents](https://code.claude.com/docs/en/sub-agents), [Hooks](https://code.claude.com/docs/en/hooks), [MCP](https://code.claude.com/docs/en/mcp).
- [Permission modes](https://code.claude.com/docs/en/permission-modes), [Permissions](https://code.claude.com/docs/en/permissions), [Sandboxing](https://code.claude.com/docs/en/sandboxing), [Security](https://code.claude.com/docs/en/security), [Data usage](https://code.claude.com/docs/en/data-usage).
- [Checkpointing](https://code.claude.com/docs/en/checkpointing), [Worktrees](https://code.claude.com/docs/en/worktrees), [Development containers](https://code.claude.com/docs/en/devcontainer).
- [Claude in Chrome](https://code.claude.com/docs/en/chrome), [Computer use](https://code.claude.com/docs/en/computer-use), [Desktop](https://code.claude.com/docs/en/desktop).
- [Remote Control](https://code.claude.com/docs/en/remote-control), [Claude Code on the web](https://code.claude.com/docs/en/claude-code-on-the-web), [Self-hosted environments](https://code.claude.com/docs/en/self-hosted-environments).
- [Headless mode](https://code.claude.com/docs/en/headless), [Agent view](https://code.claude.com/docs/en/agent-view), [Agent teams](https://code.claude.com/docs/en/agent-teams), [Workflows](https://code.claude.com/docs/en/workflows), [Cross-session messaging](https://code.claude.com/docs/en/cross-session-messaging).
- [Model configuration](https://code.claude.com/docs/en/model-config), [Costs](https://code.claude.com/docs/en/costs), [Feature availability](https://code.claude.com/docs/en/feature-availability).
