Pi — инструмент для минимизации кода: расширения, навыки, сессии и безопасность
Почему небольшой терминальный инструментарий с четырьмя инструментами и кратким системным сообщением может превзойти агентов с большим количеством функций: установка, модели, деревья сессий, расширения, навыки и среда изоляции.
Источники: Forget OpenCode. PI Agent Harness 10x Better
Инструменты для кодирования в терминале, такие как Claude Code, Cursor и OpenCode, стали обычной частью рабочего дня многих разработчиков, особенно после того, как в апреле OpenAI сделала Codex CLI открытым исходным кодом. Pi — это намеренно простой инструмент для кодирования, созданный в ответ на проблемы, связанные со всеми вышеупомянутыми инструментами: они постоянно меняются под рукой пользователя.
Претензии не коснутся багов. Речь идет о том, что сами инструменты меняются, и вместе с ними меняется и поведение модели. Инженеры хотят иметь инструменты, на которые можно полагаться. Сами большие языки моделей ненадежны, но по крайней мере окружающие их компоненты можно сделать детерминированными, включая инструменты, системные подсказки и всё, что в них вводится.
Claude Code и Codex вносят большое количество информации в контекст без её отображения в интерфейсе, и эти скрытые добавления косвенно нарушают рабочий процесс. Обновления выходят раз в день или даже несколько раз в день. Рабочий процесс, который идеально функционирует в девять утра, может рухнуть к десяти, а к трём вести себя совершенно иначе, причём сама модель остаётся прежней, меняется лишь среда её работы. Новые функции появляются почти каждый месяц: среди них MCP, сабагенты, режим планирования и фоновая обработка, и становится всё сложнее понимать, что происходит за кулисами.
Ответ Pi заключается в правиле проектирования: если что-то не нужно, его не создают. Существующие инструменты вносят контекст незаметно, и пользователи не могут видеть, что происходит. Именно это стало движущей силой.
Что вдохновило на минимализм
Прежде чем создать Pi, его создатель Марио Цехнер изучил табло лидеров Terminal Bench, где выделялся инструмент под названием Terminus. Он предоставляет модели ровно один инструмент — интерфейс к сессии tmux. Язык больших моделей отправляет отдельные нажатия клавиш и считывает результаты работы tmux в формате ANSI, чтобы выполнить задачу. Благодаря этому он почти всегда попадает в топ-три, а часто занимает первое место.
Это указывает на важную интуицию: модели сейчас активно тренируются с использованием методов обучения с подкреплением, поэтому они уже знают, что такое инструменты для программирования, и им не нужно много дополнительных компонентов. Pi воплощает эту идею в виде минимального, но при этом расширяемого инструмента.
Что делает Pi особенным
Особенность Pi заключается в том, что он исключает то, что другие инструменты для кодирования считают стандартом. Возьмём MCP: при подключении к серверу каждое определение инструмента заполняет контекст в начале каждой сессии. Инструменты командной строки сопровождаются файлами 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 diff.
- Переключение рабочих деревьев 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 + локальная большая языковая модель — пошаговое руководство по созданию агента для программирования в частном облаке с использованием OpenCode и локальной большой языковой модели: контракты, проверки и готовые блоки кода для команд, внедряющих эту схему.