Pi — AI Agent Harness Toolkit

Overview

Pi (earendil-works/pi) is a self-extensible AI agent harness toolkit that provides everything needed to build and run coding agents. It ships as four tightly integrated TypeScript packages: a unified multi-provider LLM API, a full agent runtime with tool calling, a terminal UI library with differential rendering, and an interactive coding-agent CLI. With over 74,000 GitHub stars and rapid weekly growth, Pi has become one of the most watched open-source agent harnesses in the ecosystem.

Pi is designed for developers who want a coding agent that runs locally, can call tools, manages its own state, and integrates with any LLM provider — OpenAI, Anthropic, Google, or local models. Unlike monolithic agent platforms, Pi is modular: you use only the packages you need, whether that's the CLI for interactive coding or the agent core for embedding agent behavior into your own applications.

The project is notable for its strong supply-chain hardening practices, including pinned direct dependencies, a min-release-age=2 policy, pre-commit lockfile checks, and regular npm audit runs in CI. It also has no built-in permission system — Pi runs with the permissions of the launching user — so it encourages sandboxing via Docker, Linux micro-VMs, or OpenShell for production deployments.

Features

• Unified Multi-Provider LLM API (@earendil-works/pi-ai): One API surface for OpenAI, Anthropic, Google, and more — switch providers without rewriting agent logic
• Agent Runtime (@earendil-works/pi-agent-core): Full agent loop with tool calling, state management, and session persistence
• Terminal UI Library (@earendil-works/pi-tui): Differential rendering for rich, responsive terminal interfaces
• Interactive Coding CLI (@earendil-works/pi-coding-agent): Ready-to-use coding agent that runs in your terminal
• Multi-Provider Support: Works with OpenAI, Anthropic Claude, Google Gemini, and any OpenAI-compatible endpoint
• Modular Architecture: Use individual packages independently or together
• Supply-Chain Security: Pinned dependencies, lockfile validation, regular CI audits
• Contribution-Friendly: CONTRIBUTING.md and AGENTS.md guide new contributors; badlogic/pi-share-hf enables sharing real-world coding sessions for research

Installation

# Clone the repository
git clone https://github.com/earendil-works/pi.git
cd pi

# Install dependencies (skip lifecycle scripts for safety)
npm install --ignore-scripts

# Build all packages
npm run build

# Run lint, format, and type checks
npm run check

# Run Pi coding agent from source (works from any directory)
./pi-test.sh

Using individual packages

# LLM API layer only
npm install @earendil-works/pi-ai

# Agent runtime only
npm install @earendil-works/pi-agent-core

# Terminal UI library
npm install @earendil-works/pi-tui

Quick Start

# Run the interactive coding agent CLI
./pi-test.sh "Implement a binary search tree in TypeScript"

# Or run with a specific model provider
PI_PROVIDER=anthropic ./pi-test.sh "Refactor the auth module for better error handling"

The coding agent launches an interactive session where you can ask it to modify files, run tests, and explain code — all within your terminal.

Core Concepts

Pi-ai (LLM API Layer)

The unified API layer abstracts away provider-specific differences. You write agent logic once and it runs against any connected LLM. Supports streaming, tool calling, and multi-modal inputs where the underlying provider supports them.

Pi-agent-core (Agent Runtime)

The agent runtime manages the agent loop: receive user input, decide which tool to call, execute the tool, observe results, and loop. It maintains session state so agents can carry context across multiple interactions.

Pi-tui (Terminal UI)

A differential rendering library for terminal interfaces — only redraws the parts of the screen that changed. Used by the coding agent CLI to display progress, errors, and agent reasoning in real time.

Pi-coding-agent (CLI)

The most user-facing component. A full coding agent that can read files, edit code, run commands, and manage multi-step tasks — all from the command line.

Sandboxing and Security

Pi has no built-in permission system, so the authors provide three sandboxing patterns:

• Gondolin extension: Linux micro-VM isolation for maximum security
• Plain Docker: Lightweight container isolation for most use cases
• OpenShell: Sandboxed shell execution for agent tool calls

For development, running Pi without sandboxing is acceptable. For production or untrusted input, use one of the above patterns.

Examples

Run Pi with a local model

# Point Pi at a local OpenAI-compatible endpoint
PI_BASE_URL=http://localhost:8080/v1 PI_MODEL=local-model ./pi-test.sh "Help me debug this Python script"

Share a coding session for research

Pi integrates with badlogic/pi-share-hf to share real-world coding sessions to Hugging Face, contributing to agent training data based on real tasks rather than synthetic benchmarks.

Pros

• ✅ Modular architecture — use only what you need
• ✅ Multi-provider LLM support with unified API
• ✅ Strong supply-chain security practices
• ✅ Active development with frequent releases
• ✅ Encourages real-world agent research via session sharing
• ✅ Terminal-native UI is lightweight and fast

Cons

• ✅ TypeScript-only — not ideal for Python-first teams
• ❌ No built-in permission system — requires external sandboxing for security
• ❌ New contributors' issues/PRs are auto-closed until reviewed
• ❌ Documentation focuses on CLI use — embedding in apps requires reading source

When to Use

Use Pi if you want a modular, TypeScript-native agent harness that runs locally and supports multiple LLM providers. It is especially well-suited for:

• Coding agents that you want to run in your terminal or embed in a DevTools workflow
• Multi-provider experiments where you compare agent behavior across LLMs
• Agent research — Pi's session-sharing tool contributes to real-world agent datasets
• Teams that prefer TypeScript and want agent tooling in their existing stack

Resources

• GitHub Repository
• Pi LLM API Package
• Badlogic Pi-Share HF