Pi (pi.dev): минимальный расширяемый coding agent harness — техническое эссе

Pi — это терминальный coding agent harness, который строится вокруг противоположной всем остальным идеи: не «дать как можно больше готовых функций», а «дать как можно меньше примитивов и позволить достроить остальное самому». Автор формулирует это слоганом на главной странице: «There are many agent harnesses, but this one is yours» — «адаптируй Pi под свои рабочие процессы, а не наоборот».¹ За проектом стоит Mario Zechner (известный как badlogic, автор игрового фреймворка libGDX), а сам harness распространяется под лицензией MIT и работает целиком в терминале, без какого-либо SaaS-бэкенда.²

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

Откуда взялся Pi и почему «примитивы, а не функции»

Pi родился из раздражения создателя инструментом, которым он пользовался каждый день. Zechner прямо пишет, что ушёл от Claude Code, потому что тот «превратился в космический корабль, 80% функциональности которого мне не нужны».³ Второй мотив — потеря контроля над контекстом: «системный промпт и инструменты меняются с каждым релизом, это ломает мои рабочие процессы и меняет поведение модели. Я это ненавижу».³

Из этой боли выросла центральная инженерная гипотеза Pi: context engineering решает всё. Zechner формулирует так: «точный контроль над тем, что попадает в контекст модели, даёт лучший результат, особенно когда она пишет код», а существующие harness’ы делают этот контроль «крайне трудным или невозможным, подсовывая в контекст то, что даже не видно в интерфейсе».³ Отсюда третье требование — полная наблюдаемость: «я хочу инспектировать каждый аспект моего взаимодействия с моделью».³

Философия «primitives, not features» — это не маркетинговая поза, а проектное ограничение. Pi намеренно не имеет MCP, sub-agents, plan mode и встроенных to-do списков. Логика автора: всё это можно собрать из более простых примитивов — файлов, bash, tmux, расширений — не вшивая в ядро.⁴ Расширение пишет не команда Pi, а сам пользователь — или даже сама модель, которая «очень хорошо умеет писать и запускать код».⁵ Отсюда самый необычный сюжет вокруг Pi: harness достаточно мал и наблюдаем, чтобы агент дописывал себе инструменты на лету. Zechner показывает, как «Pi строит сам себя», а Pragmatic Engineer разбирает этот класс самомодифицирующегося софта отдельным материалом.⁶⁷

Архитектура ядра

Четыре инструмента

Дизайн-ядро Pi — четыре инструмента: read, write, edit, bash. Вывод автора категоричен: «этих четырёх инструментов достаточно для эффективного coding-агента».³ К текущей версии к ним добавились три тонких built-in — grep, find, ls,⁸ — но принцип прежний: всё остальное (запуск тестов, работа с git, прочие утилиты) модель делает через bash, читая при необходимости README нужной CLI. Минимализм даёт короткий системный промпт: вместе с определениями инструментов он укладывается менее чем в 1000 токенов против 7–10 тысяч у зрелых конкурентов.³

Четыре режима работы

Одно и то же агентное ядро доступно через четыре интерфейса:⁹

• Interactive TUI — обычный терминальный интерфейс для человека.
• Print / JSON — однократный запуск с машиночитаемым выводом, для скриптов и пайплайнов.
• RPC — двусторонний протокол поверх stdin/stdout для встраивания в другой процесс.
• SDK — программное встраивание Pi прямо в TypeScript-приложение.

TUI — лишь один из фасадов; RPC и SDK позволяют использовать Pi без терминала вообще. Это ключевой момент для автоматизации: тот же агент, что отвечает вам в консоли, может работать headless внутри CI или другого сервиса.

Агентный цикл и дерево сессий

Цикл прост: пользователь отправляет промпт через session.prompt() → модель генерирует ответ и вызовы инструментов → инструменты выполняются и возвращают результат → цикл повторяется до завершения хода.⁹ Поверх этого Pi хранит историю не линейно, а деревом: сессии можно ветвить, переключаться между ветками, форкать и клонировать.¹⁰ Сессии автоматически сохраняются в ~/.pi/agent/sessions/, их можно экспортировать в HTML и шарить через GitHub gist.⁸ Дерево — не косметика, а инструмент для исследовательской отладки: можно увести разговор в сторону, упереться в тупик и вернуться к точке ветвления без потери основного контекста.

Context engineering как первоклассная механика

Управление контекстом в Pi разложено на три независимых механизма, работающих вместе:

• Авто-компакция. Когда contextTokens > contextWindow − reserveTokens, Pi запускает LLM-суммаризацию старых сообщений, сохраняя последние keepRecentTokens (по умолчанию 20 000). Резка идёт только по валидным границам — никогда посреди результата инструмента.¹¹
• Суммаризация веток. При переключении между ветвями дерева контекст брошенной ветки сворачивается в резюме.¹¹
• Progressive disclosure для skills. В системный промпт попадают только имена и описания навыков; полная инструкция подгружается по требованию, когда модель решает навык применить.¹²

Проектные инструкции Pi читает из файлов AGENTS.md (а также совместимо с CLAUDE.md) — из текущей директории, родительских и глобального конфига.⁸

Модели и провайдеры

Pi через свой пакет pi-ai (унифицированный LLM API) поддерживает более 30 провайдеров: Anthropic, OpenAI, Google Gemini, Azure OpenAI, AWS Bedrock, Google Vertex AI, Mistral, Groq, Cerebras, DeepSeek, NVIDIA NIM, xAI, OpenRouter, Hugging Face, Fireworks, Together AI и ряд региональных.¹³ Локальные эндпоинты (Ollama, LM Studio, vLLM) подключаются через models.json.¹³ Модель можно переключать прямо посреди сессии. Это снимает vendor lock-in на уровне архитектуры, а не отдельной интеграции.

Вместе с моделью настраивается и уровень размышления (thinking level) — off, minimal, low, medium, high, xhigh. Его задают флагом --thinking, в /settings или прямо в имени модели (sonnet:high), а в headless-режиме меняют на лету RPC-командой set_thinking_level.⁸¹⁰ Для harness, построенного вокруг точного управления контекстом, это ещё один рычаг: дозировать reasoning под задачу, а не платить за него всегда.

Расширяемость: где Pi раскрывается

Здесь Pi показывает свою настоящую природу. Ядро остаётся маленьким, а вся мощь живёт в системе расширений на TypeScript. Модули грузятся через jiti (JIT-транспайлер), так что компиляция не нужна — правишь файл, расширение перезагружается.¹⁴

Extensions API

Расширение — это TypeScript-модуль, который умеет: регистрировать инструменты для модели через pi.registerTool(), подписываться на события жизненного цикла (session_start, tool_call, message_end и другие), перехватывать и блокировать операции, добавлять команды и горячие клавиши через registerCommand() и registerShortcut().¹⁵ Минимальный пример из официальных примеров выглядит так:

export default function (pi) {
  pi.on("session_start", async (_event, ctx) => {
    ctx.ui.notify("Extension loaded!", "info");
  });

  pi.registerTool({
    name: "greet",
    description: "Greet someone",
    parameters: Type.Object({ name: Type.String() }),
    async execute(toolCallId, params, signal, onUpdate, ctx) {
      return {
        content: [{ type: "text", text: `Hello, ${params.name}!` }],
        details: {},
      };
    },
  });
}

Схемы параметров типобезопасны через TypeBox. В репозитории лежит более 50 рабочих примеров расширений — от permission-gate и protected-paths (safety-слой) до делегирования всех инструментов на удалённую машину по SSH и git-воркфлоу.¹⁴

SDK

Точка входа для встраивания — фабрика createAgentSession(), которая инициализирует агента с настраиваемыми моделью, инструментами, расширениями, навыками и файлами контекста; AgentSession управляет жизненным циклом разговора — историей, стримингом, подпиской на события.⁹ В простейшем виде это одна строка:

const { session } = await createAgentSession();

Официальные SDK-примеры идут лесенкой от 01-minimal.ts (минимум) через выбор модели, кастомный промпт, фильтрацию навыков, allowlist инструментов, расширения, файлы контекста до полного контроля (12-full-control.ts) и управления рантаймом сессии (13-session-runtime.ts).¹⁶ Именно через SDK Pi встраивают в более крупные продукты: по ряду источников, агентное ядро Pi лежит в основе ассистент-платформы OpenClaw, которая подключает createAgentSession() из @earendil-works/pi-agent-core напрямую.⁵

RPC

RPC-режим даёт headless-управление через строгий JSONL поверх stdin/stdout (один JSON-объект на строку, разделитель — только LF; клиентам нельзя использовать readline-библиотеки, которые режут по Unicode-сепараторам).¹⁰ Команды покрывают промптинг (prompt, steer, follow_up), управление состоянием (get_state, get_messages), управление моделью (set_model, cycle_model) и операции над сессиями (fork, clone, switch_session); события стримятся асинхронно.¹⁰

Skills, packages, themes, custom providers

• Skills реализуют стандарт Agent Skills: директория с SKILL.md (frontmatter name до 64 символов + description до 1024 + инструкции) и опциональными scripts/, references/, assets/. Обнаруживаются из ~/.pi/agent/skills/, .pi/skills/, npm-пакетов и аргументов CLI.¹²
• Packages упаковывают extensions, skills, prompt-шаблоны и themes для распространения. Манифест описывается в package.json в секции pi, установка — pi install npm:@foo/bar, pi install git:github.com/user/repo или из локального пути; при конфликте имён приоритет у project-уровня над global.¹⁷
• Custom providers регистрируются через pi.registerProvider() — можно переопределить существующий провайдер (подменить baseUrl/заголовки, например для прокси) или добавить новый с полным описанием моделей, аутентификацией (API-ключ, OAuth, кастомные заголовки) и нестандартным стримингом через streamSimple().¹⁸
• Themes — hot-reloadable JSON-файлы с 51 обязательным цветовым токеном.¹⁹

Вот точка, которую стоит осознать: «отсутствующие» функции (MCP, sub-agents, plan mode) — это не дыры, а домашнее задание. Sub-agent собирается делегированием инструментов через расширение; plan mode — внешним файлом плана, который переживает сессии; фоновые процессы — через tmux с полной наблюдаемостью.³⁴ Pi не запрещает эти паттерны — он отказывается принимать за вас решение, как именно они должны работать.

Преимущества перед альтернативами

Если сравнивать Pi с зрелыми конкурентами (Claude Code, opencode, Aider, Codex CLI), его сильные стороны очерчены чётко.

Три преимущества заслуживают отдельного акцента.

Контроль над контекстом. Это исходный смысл проекта. Вы видите и можете изменить системный промпт, инжектировать контекст по-турно, перехватить ввод до того, как агент его обработает, манипулировать окном контекста.²¹ Для задач, где качество вывода критично, точное управление контекстом — рычаг, которого у закрытых harness’ов просто нет.

Свобода провайдеров без lock-in. 30+ провайдеров и локальные модели за унифицированным API означают, что выбор модели — ваше решение в рантайме, а не архитектурное обязательство.¹³ Это же делает Pi дешёвым для лёгкого использования: нет фиксированной подписки, платите по токенам (на дешёвых моделях это единицы долларов в месяц).²⁰

Программируемость. SDK и RPC превращают Pi из «инструмента» в «библиотеку для сборки агентов». Это редкое свойство в классе терминальных агентов и главная причина, почему Pi выбирают как фундамент для других продуктов.⁵¹⁶

Trade-offs и ограничения

Честная оценка требует развернуть и обратную сторону.

Минимализм — это работа, переложенная на вас. Чтобы получить паритет по функциям с opencode или Claude Code, придётся писать расширения на TypeScript.²¹ Сравнения прямо фиксируют: opencode идёт «из коробки» с LSP, MCP, sub-agents и мультисессиями, тогда как Pi требует ручной достройки.²¹ Для команды, которой нужны «отполированные дефолты с минимальной конфигурацией», это налог, а не свобода.

Только терминал. Нет IDE-расширений и GUI; это сознательный выбор, но он сужает аудиторию по сравнению с конкурентами, у которых есть интеграция в VS Code.

Экосистема и зрелость. Pi молод (на момент написания — версия v0.79.3 от 13 июня 2026, без релиза 1.0), API и поведение ещё меняются.² Это значит периодические breaking changes и меньший корпус документации и готовых рецептов, чем у проектов с многолетней историей. В 2026 году проект перешёл под управление Earendil Inc. — Public Benefit Corporation, основанной Armin Ronacher и Colin Daymond Hanna: компания приобрела Pi, Mario Zechner перешёл в неё, а сам harness продолжает развиваться как open source под её управлением.²²²³ Второй продукт Earendil — Lefos, переосмысляющий электронную почту как «командную строку для вдумчивой работы и коммуникации»; Pi при этом служит минимальным агентом внутри ассистент-платформы OpenClaw.²²

Управление доступами провайдеров — на вас. Гибкость 30+ провайдеров оборачивается тем, что аутентификация, лимиты, биллinг по каждому ключу остаются вашей заботой, а не абстрагированы за подпиской.²¹

Человеческий фактор. Это не специфика Pi, но его минимализм усиливает проблему: по наблюдениям Pragmatic Engineer, команды, активно использующие агентов, рискуют деградацией качества кода — агенты бесконечно расширяют плохую структуру без стимула её упрощать, накапливая технический долг.⁶ Минимальный harness не подстелет соломки; дисциплину код-ревью придётся держать самому.

Безопасность: YOLO как явная позиция

Это самый важный пункт для тех, кто думает о production. Pi по умолчанию работает в режиме полного доверия. Цитата автора недвусмысленна: «pi работает в полном YOLO-режиме и предполагает, что вы знаете, что делаете. У него неограниченный доступ к файловой системе, и он может выполнить любую команду без проверок и страховочных рельсов».³

Обоснование прагматично: как только агент может писать и запускать код с доступом к сети, «вы играете в whack-a-mole с векторами атак», и security theater даёт лишь ложное чувство комфорта.³ Позиция спорная, но интеллектуально честная. Проблема в том, что она перекладывает изоляцию на пользователя, а многие изоляцию не настроят.

Угрозы реальны и описаны независимо: агент с неограниченным bash может похитить учётные данные, подменить git-хуки и build-скрипты (изменения сработают позже в обычном цикле без немедленного обнаружения), эксфильтровать данные по сети.²⁴ Сообщество ответило обёртками вроде pi-less-yolo, которые запускают Pi в изолированном Docker-контейнере-песочнице; это «осмысленное снижение риска, но не гарантия безопасности».²⁵

Практический вывод: для production-использования Pi нужна явная контейнеризация или permission-слой через расширение, а не опора на дефолты. Permission-gate — один из штатных примеров расширений, так что слой подтверждений собирается, но собирать его придётся вам.¹⁴

Рекомендации: что предложить и на что обратить внимание

Кому Pi подходит:

• Терминал-нативным разработчикам, которым важен контроль над контекстом и наблюдаемость.
• Командам, строящим собственного агента поверх Pi SDK/RPC (это, по сути, его сильнейший сценарий).
• DevOps/CI-автоматизации с явно заданными границами в AGENTS.md и отслеживанием изменений через git.
• Тем, кто хочет уйти от vendor lock-in и гонять разные модели, включая локальные.

Кому стоит выбрать другое:

• Командам, которым нужны отполированные дефолты и фичи «из коробки» без TypeScript-обвязки — посмотрите на opencode или Claude Code.
• Тем, кто работает в shared/недоверенных окружениях без контейнеризации.
• Организациям с требованиями compliance/audit и потребностью в SLA — Pi молод и гарантий не даёт.

На что обратить внимание при внедрении:

1. Сначала изоляция. Не запускайте YOLO-Pi на машине с боевыми секретами. Контейнер или выделенная среда — до первого запуска, а не после инцидента.
2. Границы в AGENTS.md. Минимальный промпт означает мало встроенных ограничений; формулируйте правила и инварианты явно в проектных инструкциях.
3. Версионируйте всё под git. Это и история изменений, и точка отката после неудачного хода агента.
4. Закрепите версию Pi. При активном развитии API возможны breaking changes; пинуйте конкретную версию и держите стратегию обновления.
5. Относитесь к выводу как к коду джуна. Обязательное senior-ревью, а не «production-ready по умолчанию».⁶
6. Инвестируйте в расширения как в актив. Если вы пишете permission-gate, делегирование на удалённый хост или интеграцию с внутренними CLI — оформляйте это пакетом и переиспользуйте между проектами.¹⁷

Что я бы предложил конкретно: начать не с замены повседневного агента, а с встраивания через SDK/RPC в одну узкую автоматизацию (например, генерация и проверка миграций или разбор логов в CI), где ценность точного контроля контекста максимальна, а риск ограничен изолированной средой. Это даёт пощупать сильнейшую сторону Pi без ставки на незрелую экосистему в критичном пути.

Insufficient Evidence

• Бенчмарки. Звучали утверждения о высоком месте Pi на Terminal-Bench, но чистого верифицируемого score для harness’а Pi найти не удалось — есть только самопубликуемый адаптер badlogic/pi-terminal-bench для прогона эвалов, а конкретные проценты в обзорах противоречивы и относятся к моделям, а не к harness’у.²⁶ Числовые результаты в эссе сознательно не приводятся.
• Метрики adoption. Число звёзд GitHub (~62.7k) подтверждено напрямую,² но npm-загрузки и точные масштабы потребителей SDK (в частности, звёздные счётчики OpenClaw, расходившиеся между источниками от ~145k до ~378k) не верифицированы и в эссе не используются как факты.
• Лицензионная стратегия после Earendil. Переход репозитория badlogic/pi-mono → earendil-works/pi под управление Earendil подтверждён первоисточниками.²²²³ Открытым остаётся другое — будущая лицензионная политика для не-ядровых компонентов: это риск, который стоит мониторить, а не установленный факт.

Quality Metrics