VorobeoffAIВиталий Воробьев

Pi: минимальная агентная обвязка для терминала

Что такое Pi: минимальная агентная обвязка для терминала, расширения, навыки, четыре режима работы, MCP и границы применимости.

Pi — кодинг-агент для терминала от Earendil Works. Он связывает языковую модель с инструментами для работы с файлами и выполнения команд. Дополнительные функции можно подключать через расширения, навыки и пакеты. Разберём, как устроен Pi и кому подойдёт такой подход.

Что это

Pi запускают в папке проекта. Агент может читать и изменять файлы, выполнять команды и решать задачи в несколько шагов. Его устанавливают с помощью установщика с pi.dev, через npm или Nix. Пакет называется @earendil-works/pi-coding-agent; для работы требуется Node.js 22.19 или новее. Исходный код написан на TypeScript и доступен по лицензии MIT.

Программную обвязку, которая позволяет модели выполнять действия с файлами и командами, называют agent harness. В Pi есть терминальная программа (CLI) и набор библиотек. CLI поддерживает четыре режима: интерактивный, print (вывод результата для скриптов), JSON (поток событий) и RPC (управление агентом из другой программы). Отдельно доступен SDK — библиотека для встраивания Pi в приложения на TypeScript. Среди пакетов проекта есть API для обращения к моделям разных провайдеров (pi-ai), движок агента (pi-agent-core), терминальный интерфейс (pi-tui) и среда для длительных задач (pi-durable).

В Pi намеренно не включены некоторые функции, привычные по другим агентным средам: изоляция команд в песочнице, обязательное подтверждение каждого действия, субагенты, отдельный режим планирования, встроенный список задач и фоновое выполнение bash-команд. Вместо этого разработчики предлагают собирать нужное поведение из расширений, пакетов и внешних инструментов, например tmux. Версия 1.0 вышла 1 октября 2026 года. Она закрепила поддержку Codemode и MCP, загрузку инструментов по запросу и возможность добавлять системные сообщения в ходе диалога. Также появились изменения в оформлении терминала и полноэкранный режим по умолчанию.

Основная идея Pi: если стандартных возможностей не хватает, нужное поведение можно добавить расширением или пакетом, не дожидаясь его появления в основном продукте.

Зачем нужно

  • Собственные инструменты и команды: расширения на TypeScript позволяют добавлять действия, горячие клавиши и элементы терминального интерфейса.
  • Экономия контекста модели: системный промпт небольшой, полные инструкции навыков загружаются по необходимости, а длинная история диалога автоматически сжимается.
  • Смена модели во время работы: через /model или Ctrl+L можно выбрать модель, а Ctrl+P переключает избранные варианты.
  • Ветвящаяся история: можно вернуться к предыдущему сообщению, продолжить разговор с выбранного места и поделиться сессией с коллегой.
  • Несколько способов интеграции: Pi доступен в терминале, из скриптов, через поток JSON-событий, RPC и SDK.

Как устроено

Когда пользователь отправляет сообщение, Pi берёт системные инструкции, историю выбранной ветки диалога, сведения о доступных инструментах и настройки модели. На их основе он формирует запрос к провайдеру. Модель может ответить текстом или запросить действие, например чтение файла. Pi выполняет такой вызов, сохраняет результат и при необходимости снова обращается к модели. Во время выполнения задачи Enter передаёт уточнение после текущего шага, а Alt+Enter откладывает сообщение до завершения работы агента.

Документация Pi: агентный цикл, контекст и история сессии
Документация Pi: агентный цикл, контекст и история сессии
ЭлементЧто даётГде живёт
Инструменты по умолчанию
read, bash, edit, write
defaultTools в settings.json
Расширения
свои инструменты, команды, шорткаты, провайдеры, MCP-серверы, весь TUI
~/.pi/agent/extensions/,.pi/extensions/
Навыки
инструкции и файлы, подгружаются по требованию
~/.pi/agent/skills/,.pi/skills/
Шаблоны промптов
Markdown-файл как команда /имя, аргументы $1 и $@
~/.pi/agent/prompts/,.pi/prompts/
Темы
цвета терминала
~/.pi/agent/themes/,.pi/themes/
Пакеты
всё перечисленное одним блоком из npm или git
settings.json, ключ packages
MCP
серверы по stdio и streamable HTTP, вход по OAuth
~/.pi/agent/mcp.json,.pi/mcp.json
Codemode
скрипт на JavaScript комбинирует вызовы инструментов
встроенное расширение
Сжатие истории (компакция)
сокращение старых сообщений при приближении к лимиту контекста
блок compaction в settings.json
Каталог моделей
модели, лимиты контекста, цены; работает офлайн
pi update —models

Инструкции для проекта Pi ищет в файлах AGENTS.md текущей и родительских папок. Файл SYSTEM.md заменяет системный промпт, а APPEND_SYSTEM.md добавляет к нему инструкции. Сначала в запрос включаются только название и описание навыка. Полный текст навыка загружается при необходимости; вручную его можно открыть командой /skill:имя. Когда история приближается к лимиту контекста модели, Pi сокращает её старую часть. По умолчанию сжатие начинается за 16 384 токена до лимита, при этом последние 20 000 токенов сохраняются без изменений. Исходные сообщения остаются в истории сессии.

Каждая сессия хранится в файле JSONL: отдельные записи содержат ссылки на родительские записи, поэтому историю можно просматривать как дерево. Команда /tree позволяет перейти к другому сообщению, /fork создаёт новую сессию от выбранного места, а /clone копирует текущую ветку. Через /export можно выгрузить историю в HTML или JSONL, через /share — получить ссылку для просмотра. Файлы сессий хранятся в ~/.pi/agent/sessions/ и группируются по папкам проектов.

РежимИнтерфейсКогда подходит
Интерактивный
полный экран в терминале
человек работает руками
Print: pi -p ”…“
финальный текст в stdout, один прогон
скрипты и конвейеры
JSON: —mode json
поток событий JSONL, один прогон
нужен прогресс по шагам
RPC: —mode rpc
JSONL-команды в stdin, ответы и события в stdout
интеграции на других языках, IDE
SDK
createAgentSession() внутри Node.js или Bun
приложение на TypeScript

Pi умеет подключаться к MCP-серверам — внешним источникам инструментов, которыми может пользоваться агент. Настройка доступна через pi mcp add, pi mcp list и команду /mcp внутри сессии. Поддерживаются локальные серверы через stdio, удалённые через streamable HTTP и авторизация OAuth. В режиме Codemode модель пишет JavaScript-код, который вызывает инструменты (например, tools.имя(…)). Сам скрипт выполняется в ограниченной среде QuickJS, но вызываемые им инструменты могут работать с файлами и сетью. MCP-инструменты можно передавать модели напрямую, открывать через Codemode или загружать по запросу. Подробнее о протоколе — в материале «MCP-сервер».

У Pi нет общей песочницы для команд и расширений: они работают с правами процесса, под которым запущен агент. Ограничения QuickJS относятся к JavaScript-сценарию Codemode, а не ко всем вызываемым инструментам. Сторонние расширения могут получать доступ к содержимому сессии и данным окружения, поэтому перед установкой стоит изучить их код и происхождение. Механизм project trust отвечает за загрузку ресурсов из папки.pi конкретного проекта; решение пользователя сохраняется в ~/.pi/agent/trust.json. Для изоляции самого агента потребуются внешние средства: Docker, Docker Sandboxes, OpenShell с политиками доступа к файлам и сети либо Gondolin, который запускает инструменты в отдельной микровиртуальной машине.

Основной интерфейс Pi — терминал. Для доступа через браузер существуют сторонние проекты. Например, Pi Pocket предоставляет веб-интерфейс и поддержку длительных задач на основе pi-durable; его разработчики не относятся к команде Earendil.

Когда использовать

СитуацияПодходит или нетПочему
Нужен кодинг-агент в терминале со своими правилами и инструментами
Подходит
расширения и навыки меняют поведение без форка
Команда хочет раздать свою настройку коллегам
Подходит
пакет ставится одной командой из npm или git
Нужен агент внутри своего сервиса
Подходит
RPC и TypeScript SDK работают на том же движке
Нужны субагенты и готовый режим планирования
Не подходит без доработки
эти возможности добавляют через пакеты или расширения
Нужно подтверждать каждое действие
Не подходит без доработки
механизм подтверждений придётся настроить через расширение
Нужно работать с недоверенным репозиторием без дополнительной изоляции
Не подходит
встроенной изоляции команд нет; нужен контейнер или виртуальная машина
Основной интерфейс — браузер или телефон
Не подходит для самого Pi
это терминальный инструмент; браузерный доступ делают клиенты вроде Pi Pocket, на Android работает Termux
Работа на Windows без Git Bash и WSL
Потребуется настройка
вместо стандартного bash можно использовать инструмент PowerShell
Нужны локальные модели без облака
Подходит
llama.cpp подключается напрямую, Ollama и другие через совместимый эндпоинт
Нужен только обычный чат с моделью
Скорее избыточен
Pi рассчитан прежде всего на задачи с файлами, инструментами и командами

Pi работает на macOS и Linux, а на Windows — через Git Bash или WSL; при необходимости можно настроить инструмент PowerShell. На Android его запускают через Termux. Для продолжительных задач в терминале можно использовать tmux. Для сравнения можно посмотреть Warp с агентом Oz: у него собственный терминал на Rust и другой подход к расширениям.

Пример

Выберите один из способов установки. Затем проверьте версию Pi и запустите его в папке проекта.

Документация Pi: установка через официальный установщик и npm
Документация Pi: установка через официальный установщик и npm
curl -fsSL https://pi.dev/install.sh | sh
# Windows: powershell -c "irm https://pi.dev/install.ps1 | iex"
# npm: npm install -g --ignore-scripts @earendil-works/pi-coding-agent
# Nix: nix profile add github:earendil-works/pi/stable

pi --version
cd /path/to/project
pi

Внутри сессии команда /login помогает подключить провайдера модели, а /model — выбрать модель. Запрос пишут обычным текстом. Чтобы сослаться на файл проекта, перед его именем ставят @:

Summarize @meeting-notes.md and save the action items to action-items.md.

Pi можно запускать и из скриптов. Например, передать ему изменения из Git или сохранить события работы в файл:

git diff | pi --print "Review this change"
pi --mode json "Inspect this repository" > events.jsonl

Собственное расширение можно сохранить как файл TypeScript в ~/.pi/agent/extensions/. Пример ниже показывает, как запросить подтверждение перед выполнением команды с rm -rf и добавить команду /hello. Это демонстрация механизма перехвата, а не полноценная защита от опасных команд:

import { type ExtensionAPI, isToolCallEventType } from "@earendil-works/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  pi.on("tool_call", async (event, ctx) => {
    if (isToolCallEventType("bash", event) && event.input.command.includes("rm -rf")) {
      const ok = await ctx.ui.confirm("Dangerous!", "Allow rm -rf?");
      if (!ok) return { block: true, reason: "Blocked by user" };
    }
  });

  pi.registerCommand("hello", {
    description: "Say hello",
    handler: async (args, ctx) => ctx.ui.notify(`Hello ${args || "world"}!`, "info"),
  });
}

После сохранения файла команда /reload загрузит расширение в текущую сессию.

Pi имеет смысл выбирать, когда нужно управлять поведением агента: добавлять свои команды, инструменты или интеграции. Если стандартных возможностей достаточно и настраивать ничего не планируется, готовая агентная среда может оказаться проще.

Ссылки

По теме

Продолжить тему

Материалы, которые связаны с этим разбором

Подборка учитывает тему, редкие теги и смысл заголовка с описанием материала.

Открыть материалы по теме ↗

Обсудить задачу

Есть задача, которую хотите усилить с помощью ИИ?

Опишите процесс, что уже пробовали и какой результат хотите получить. Я помогу понять, где ИИ и автоматизация действительно дадут эффект, и предложу понятный следующий шаг.

Для первого сообщения достаточно пары абзацев — готовое техническое задание не требуется.