Pi — модульный инструментарий для собственного кодинг-агента

Pi — это агентский harness (каркас) от earendil-works, включающий самодостраиваемого кодинг-агента. По сути это не один инструмент, а набор npm-пакетов, из которых можно собрать собственного агента: здесь есть и единый API для работы с разными LLM, и агентное ядро, и TUI, и готовый интерактивный кодинг-агент для терминала.

Проект построен как монорепозиторий на TypeScript/Bun и распространяется через npm. На момент написания у него порядка 80 тысяч звёзд, что говорит о большой популярности среди разработчиков, которые хотят понять, как устроены современные агенты «изнутри».

Из чего состоит Pi

Весь инструментарий разбит на несколько пакетов, и это главная его особенность — модульность. Вместо одного монолитного агента вы получаете слои, которые можно использовать по отдельности или вместе.

@earendil-works/pi-ai — унифицированный мультипровайдерный LLM API. Один интерфейс поверх OpenAI, Anthropic, Google и других провайдеров. Это позволяет менять модель, не переписывая логику приложения.

@earendil-works/pi-agent-core — агентное рантайм-ядро. Отвечает за цикл агента: приём задачи, вызов инструментов, обработка состояния. По сути это «мозг», поверх которого вы строите свою логику.

@earendil-works/pi-coding-agent — основной кодинг-агент в виде CLI. Интерактивный инструмент, ориентированный на работу с кодом и файлами. Именно он публикуется как @earendil-works/pi-coding-agent в npm.

@earendil-works/pi-tui — TUI-библиотека с дифференциальным рендерингом. Терминальный интерфейс, на котором строится интерактивная часть агента.

Для сценариев Slack/чат-автоматизации и воркфлоу отдельно существует связанный проект earendil-works/pi-chat.

Единый LLM API

Ключевая деталь — pi-ai. Современные агенты почти всегда вынуждены работать с разными провайдерами, и унификация API сильно упрощает переключение между ними и поддержку. Если ваш код завязан на конкретного провайдера, вы меняете не весь агент, а только слой pi-ai. Это делает проект удобным как для экспериментов (быстро сравнить модели), так и для продакшена.

Агентное ядро

pi-agent-core — это низкоуровневое ядро с вызовом инструментов и управлением состоянием. Оно отделено от конкретного интерфейса, поэтому вы можете использовать его и в CLI, и в другой оболочке. Самодостаточность этого модуля — одна из причин, почему Pi хвалят как хорошую точку входа для изучения архитектуры агентов.

Кодинг-агент в терминале

pi-coding-agent — это то, что большая часть пользователей видит как продукт. Интерактивный агент, который помогает работать с репозиторием: читает код, вносит изменения, запускает команды. Он построен на всех нижних слоях, но скрывает их за простой CLI-командой.

Стоит подчеркнуть: самокатегоризируемый или «саморождаемый» агент — то есть проект можно использовать, чтобы собрать собственного кодинг-агента под специфические задачи, а не только применять готовый.

Разрешения и контейнеризация

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

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

• Gondolin extension — держать pi и аутентификацию провайдера на хост-машине, при этом маршрутизируя встроенные инструменты и команды ! в локальную Linux-микро-ВМ.
• Plain Docker — запустить весь процесс pi в локальном контейнере для простой изоляции.
• OpenShell — запустить весь процесс pi в песочнице, управляемой политиками.

Это стоит учитывать, особенно при автоматизации или работе с чувствительными данными.

Укрепление цепочки поставок

Проект серьёзно относится к безопасности зависимостей — там прямо пишут, что изменения npm-зависимостей считают полноценными изменениями кода:

• Прямые внешние зависимости закрепляются на точных версиях; внутренние пакеты остаются версионированными диапазонами.
• В .npmrc включены save-exact=true и min-release-age=2, чтобы избегать свежих зависимостей «одного дня» при резолве.
• package-lock.json считается единственным источником правды; перед коммитом блокируются случайные изменения lockfile, если не задан PI_ALLOW_LOCKFILE_CHANGE=1.
• Опубликованный CLI-пакет включает npm-shrinkwrap.json, сгенерированный из корневого lockfile, для фиксации транзитивных зависимостей у npm-пользователей.
• CI устанавливает зависимости с npm ci --ignore-scripts, а запланированный workflow запускает npm audit --omit=dev и npm audit signatures --omit=dev.
• У генерации shrinkwrap есть явный список разрешённых скриптов жизненного цикла зависимостей; новые такие зависимости требуют проверки.

Это делает цепочку поставок воспроизводимой и защищённой от внезапных изменений в зависимостях — важный аспект, если вы собираете и публикуете собственную сборку агента.

Передача сессий в open source

Отдельной темой является публикация сессий кодинг-агентов для open-source работы. Публичные OSS-сессии помогают улучшать агентов на реальных задачах, использовании инструментов, сбоях и фиксах — вместо игрушечных бенчмарков.

Для публикации используются badlogic/pi-share-hf и Hugging Face. Автор регулярно публикует свои сессии pi-mono в датасете badlogicgames/pi-mono на Hugging Face.

Разработка

Сам проект собирается просто. Из репозитория:

npm install --ignore-scripts  # установить все зависимости без lifecycle-скриптов
npm run build         # обновить данные моделей и собрать все пакеты
npm run build:offline # собрать на существующих данных моделей без сети
npm run check         # lint, форматирование, проверка типов
./test.sh            # запуск тестов (пропускает LLM-зависимые без API-ключей)
./pi-test.sh         # запустить pi из исходников из любой директории

Итог

Pi — это не конкурирующий «ещё один агент», а скорее конструктор агента. Если вы хотите понять, как устроены современные кодинг-агенты, или вам нужен гибкий фундамент для собственного решения — это хороший вариант для изучения и старта. Модульная структура, единый LLM-слой и продуманный подход к зависимостям делают его интересной альтернативой монолитным инструментам.

Лицензия — MIT.