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 откладывает сообщение до завершения работы агента.
| Элемент | Что даёт | Где живёт |
|---|---|---|
Инструменты по умолчанию | 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 и запустите его в папке проекта.
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 имеет смысл выбирать, когда нужно управлять поведением агента: добавлять свои команды, инструменты или интеграции. Если стандартных возможностей достаточно и настраивать ничего не планируется, готовая агентная среда может оказаться проще.
Ссылки
- Сайт: pi.dev — Pi Coding Agent
- Документация: Pi Documentation
- Репозиторий: earendil-works/pi


