Pi — інструмент для мінімалістичного програмування: розширення, навички, сесії та безпека
Чому невеликий термінальний інструментарій для кодування з чотирма інструментами та коротким системним запитом може перевершити агентів із великою кількістю функцій: встановлення, моделі, дерева сеансів, розширення, навички та сендбоксинг.
Термінальні інструменти для кодування, такі як Claude Code, Cursor та OpenCode, стали звичайною частиною робочого дня багатьох розробників, особливо після того, як у квітні OpenAI оприлюднила код Codex CLI. Pi — це навмисно простий інструмент для кодування, створений у відповідь на проблеми, пов’язані з усіма цими інструментами: вони постійно змінюються під час роботи.
Претензії не стосуються багів. Справа в тому, що сам інструмент змінюється, і разом з ним змінюється й поведінка моделі. Інженери хочуть інструменти, на які можна покластися. Самі ШІ-моделі є ненадійними, але принаймні супутні елементи можна зробити детермінованими, включаючи інструменти, системні запити та все, що до них додається.
Claude Code та Codex вносять багато елементів у контекст роботи без їх відображення в інтерфейсі, і ці приховані доповнення по-підступному порушують процес роботи. Оновлення виходять раз на день або навіть кілька разів на день. Процес роботи, який іде ідеально о дев’ятій ранку, може зламатися о десятій та поводитися зовсім інакше о третій, при цьому сама модель залишається незмінною, а змінюється лише інструментарій. Нові функції з’являються майже щомісяця — серед них MCP, субагенти, режим планування та виконання у фоновому режимі — і стає все складніше стежити за тим, що відбувається на тлі.
Відповідь Pi — це правило проектування: якщо щось не потрібне, його не створюють. Існуючі інструменти додають контекст непомітно, і користувачі не можуть бачити, що відбувається. Саме це було мотивацією.
Що надихнуло на мінімалізм
Перш ніж створити Pi, його творець Маріо Цехнер переглянув табель лідерів Terminal Bench, де виділявся інструмент під назвою Terminus. Він надає моделі лише один інструмент — інтерфейс до сесії tmux. Штучний інтелект надсилає окремі натискання клавіш та отримує відповідь у форматі ANSI від tmux, щоб виконати завдання. За допомогою лише цього він майже завжди потрапляє до трійки лідерів, а часто й займає перше місце.
Це вказує на корисну інтуїцію: моделі сьогодні тренуються переважно за допомогою методу посилення навчання, тому вони вже знають, що таке інструменти для програмування, і їм не потрібно багато додаткових елементів. Pi втілює цю ідею у вигляді мінімального, але розширюваного інструментарію.
Що робить Pi унікальним
Особливістю Pi є те, що він не враховує певні функції, які інші інструменти для кодування вважають стандартними. Візьмемо MCP: підключення до сервера та кожна з визначень інструментів заповнюють контекст на початку кожної сесії. Інструменти CLI постачаються з файлами README, які читаються та виконуються лише за потреби, тому немає причин постійно займати контекст ними.
Що у нього є, а чого немає у інших
Pi був створений шляхом видалення непотрібного, проте він має можливості, яких бракує Claude Code. Розширення та пакети встановлюються за допомогою кількох команд:
pi install npm:@foo/pi-tools
pi install git:github.com/user/repo
pi config # Enable or disable
Механізм розширень
Розширення пишуться на основі API, імпортованого з пакета Pi:
import { ExtensionAPI } from "@mariozechner/pi-coding-agent";
Розширення може підключатися до подій, таких як виклики інструментів. Один із прикладів захищає від небезпечних команд оболонки:
export default function (pi: ExtensionAPI) {
pi.on("tool_call", async (event, ctx) => {
if (event.toolName === "bash"
&& event.input.command.includes("rm -rf")) {
const ok = await ctx.ui.confirm(
"Dangerous!", "Allow rm -rf?"
);
if (!ok) return { block: true, reason: "Blocked" };
}
});
}
1. Встановлення
Для встановлення потрібна одна команда:
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
Скрипт встановлення є альтернативою:
curl -fsSL https://pi.dev/install.sh | sh
Існує два способи автентифікації. Один з них використовує ключ API:
# Use an API key
export ANTHROPIC_API_KEY=sk-ant-...
pi
Інший використовує підписку, яка вже у вас є:
# Use an existing subscription
pi
/login # Select a provider
За допомогою /login існуючі підписки, такі як Anthropic Claude Pro або Max, OpenAI ChatGPT Plus або Pro (Codex) та GitHub Copilot, можна використовувати без змін. Поріг входження у роботу дуже низький: встановіть його, почніть спілкуватися з ним — і все буде працювати.
2. Налаштування моделі
Pi підтримує понад 15 постачальників LLM. Основні з них включають:
- Anthropic
- OpenAI
- Google Gemini / Vertex
- DeepSeek
- xAI
- OpenRouter
- Amazon Bedrock
- Azure OpenAI
- Groq / Cerebras / Mistral など
Зміна моделей посеред сеансу є цілком звичайною практикою:
/model # Model selection screen
Ctrl+L # Same as above
Shift+Tab # Switch thinking level (off–max)
Доставників на замовлення можна додати у файлі ~/.pi/agent/models.json. Будь-який API, сумісний з OpenAI, Anthropic чи Google, працює лише завдяки налаштуванням, а сервери-маршрутизатори, такі як llama.cpp, можуть обслуговувати локальні моделі. Однією з головних переваг, які підкреслює Pi, є можливість „не бути прив’язаним до конкретного доставника“.
3. Керування сеансами
Сеанси зберігаються у вигляді файлу JSONL із деревоподібною структурою у каталозі ~/.pi/agent/sessions/; кожне повідомлення містить поля id та parentId. Завдяки такій структурі один файл дозволяє виконувати всі ці операції:
pi -c # Continue the most recent session
pi -r # Select from previous sessions
Команда /tree є особливо цікавою. Ви можете повернутися до будь-якої точки розмови та продовжити її звідти. Вся історія зберігається в одному файлі, тож легко сказати „Я хотів би повернутися до того, що робив півгодини тому“ та справді це зробити.
/compact узагальнює старі повідомлення для стиснення контексту. Автоматичне стиснення увімкнене за замовчуванням, і якщо контекст переповнюється, він самостійно відновлюється та намагається знову.
4. Розширення детальніше
Тут Pi демонструє, для чого він насправді призначений. Налаштування мають чотири рівні:
Extensions (TypeScript) → Tools, commands, UI, and event handling
Skills → Procedures/instructions written in Markdown
Prompt Templates → Reusable prompts
Themes → Display themes
Пакети з npm або git керуються таким чином:
pi install npm:@foo/pi-tools
pi install git:github.com/user/repo
pi list
pi update --all
Розширення можуть виконувати все наступне:
- Додавати власні інструменти, включаючи замінники вбудованих.
- Створювати власних підагентів та режими планування.
- Запроваджувати механізми контролю дозволів та захисту шляхів.
- Додавати елементи інтерфейсу, такі як рядок статусу, заголовок та футер.
- Створювати точки контролю git або автоматичні комітти.
- Інтегрувати сервери MCP.
- Якщо бажаєте, можна запускати Doom під час очікування.
Ключова ідея полягає у тому, що кожна функція, яку інші агенти додають у продукт — чи то підагенти, режими планування чи вікна з питаннями дозволів — може бути створена у вигляді розширення. Тож філософія полягає у збереженні мінімалізму основного продукту.
5. Навички
Навички — це пакети здібностей, написані у форматі Markdown. Згідно зі стандартом Agent Skills, папка, що містить файл SKILL.md, утворює одну навичку.
<!-- ~/.pi/agent/skills/my-skill/SKILL.md -->
# My Skill
Use this skill when a user asks about X.
```
```text ## Steps 1. Perform this action. 2. Then perform that action. ```
Навичку можна викликати явно за допомогою /skill:name, а агент також завантажує її самостійно, коли це доцільно. Ключовим елементом дизайну є те, що навички потрапляють у контекст лише тоді, коли це необхідно. Замість того, щоб вкладати все у системний запит, вони активуються під час використання, і саме тому обсяг системного запиту залишається близько тисячі токенів.
6. Pi Web, інтерфейс браузера
Існує також інтерфейс браузера під назвою Pi Web:
npx @agegr/pi-web@latest
Його основні функції:
- Робочий простір сесії для переліку, відновлення, перейменування та видалення попередніх розмов за проектом.
- Два способи створення гілок: початок нової сесії з повідомлення або створення гілки всередині поточної сесії.
- Перегляд файлів проекту та відображення різниць у форматі Git.
- Зміна робочого дерева Git.
- Увійшення до облікового запису постачальника, налаштування моделей, пакетів та навичок у браузері.
Оскільки він ділиться налаштуваннями та файлами сесії з папкою ~/.pi/agent з версією для терміналу, перемикання між браузером та терміналом відбувається без проблем.
7. Пам’ять
Питання пам’яті виявляється простим. Підхід полягає у тому, що Pi не потребує окремої бази даних довгострокової пам’яті. Натомість існують три механізми:
1. The session itself is memory
The entire history is saved as JSONL and can be resumed at any time.
2. AGENTS.md / CLAUDE.md
Write project conventions, instructions, and commands in these files.
They are loaded at startup from global settings and the directory hierarchy.
3. Compaction
Long sessions are compressed by summarizing older parts.
However, the complete history remains in JSONL, so you can go back with /tree.
Іншими словами, те, що було зроблено, зберігається у сеансі, а те, що потрібно запам’ятати, — у файлі AGENTS.md. Додавання пам’яті за допомогою розширень також є поширеним способом її використання.
8. Забезпечення безпеки
У Pi немає вбудованої пісочниці. Операції читання, запису, редагування та виконання команд відбуваються з привілеями того, хто її запустив, і те саме стосується розширень. Це робиться навмисно. Напіввбудована пісочниця всередині процесу забезпечує лише видимо безпечні межі, тому офіційна позиція полягає у тому, щоб справжню ізоляцію залишити операційній системі та шарам контейнерів чи віртуальних машин. Ненадійні репозиторії та автономні запуски мають знаходитися в ізольованому середовищі.
Одним із варіантів є розміщення всього середовища Pi у Docker — це найпростіший підхід:
# 1. Put the entire pi environment in Docker (simplest)
Інший варіант — запустити Pi на хості та спрямовувати виконання інструментів лише до локальної мікро-ВМ:
# 2. Run pi on the host and route only tool execution
# to a local micro-VM (Gondolin)
pi -e ~/.pi/agent/extensions/gondolin
Функція під назвою project trust додає механізм захисту вхідних даних. Вона запобігає тому, щоб репозиторії таємно перезаписували налаштування чи розширення Pi, і за замовчуванням вимагає підтвердження для неперевірених проектів. Однак вона не повністю запобігає вставці команд, тож майте це на увазі під час роботи з незнайомим кодом чи документами.
9. Створення власного розширення
Найменше розширення — це один файл TypeScript. Він реєструє інструмент:
export default function (pi: ExtensionAPI) {
pi.registerTool({
name: "deploy",
// Tool definition (input schema, execution logic)
});
і він може додавати команди або переривати виклики інструментів:
pi.registerCommand("stats", {
// Custom command definition }); pi.on("tool_call", async (event, ctx) => {
// Intercept tool calls and process them
}); }
Помістіть файл у ~/.pi/agent/extensions/ для всіх проєктів або у .pi/extensions/ для одного проєкту — він автоматично завантажуватиметься під час запуску Pi. Для одноразового тестування достатньо використати команду pi -e ./my-ext.ts. У офіційному репозиторії є багато прикладів: автоматичне комітування, контрольні точки Git, інтеграція MCP та користувацьке стиснення даних. На Pi відсутність певної функції є цілком звичайною ситуацією. Зазвичай рекомендується додати її самостійно або встановити відповідний пакет.
Що вчить Pi
Для тих, хто створює власного агента, рішення Pi є корисним джерелом інформації. Не варто обирати пакет із усім необхідним одразу. Почніть із чотирьох інструментів та системного промпту об’ємом близько тисячі токенів, додаючи лише те, що дійсно потрібно. Процес проектування має починатися з визначення того, що потрібно видалити, а не з того, що додати.
Пов’язана література
- П’ять шарів агентського харнесу, з кодом, який не працює без них — практичний огляд п’яти місць, де агентський харнес застосовує правила в коді, від меж виконання до конвеєрів контексту, а також того, що дослідження можуть та не можуть довести.
- Практичні нотатки: створення агента для кодування в приватній хмарі: OpenCode + локальний LLM — поетапний огляд Практичних нотаток: створення агента для кодування в приватній хмарі: OpenCode + локальний LLM: контракти, перевірки та блоки коду для використання командами, які впроваджують цю модель.