Pi Agent Toolkit

Overview

Pi is a TypeScript-first AI agent toolkit built by earendil-works, designed as a complete platform for building and running AI coding agents. Unlike SDK-only frameworks, Pi ships with everything needed to deploy a production-grade agent: a unified multi-provider LLM API, a full agent runtime loop with tool calling and state management, a terminal UI library, and a ready-to-use interactive coding agent CLI.

The project has surged past 79,500 GitHub stars and nearly 10,000 forks, making it one of the fastest-growing AI agent toolkits of 2026. It is distributed as an npm monorepo under the @earendil-works scope, with four tightly integrated packages.

Pi is MIT-licensed and self-hosted by design — it "does not include a built-in permission system" and runs with the user's own permissions, making it transparent and debuggable. For teams needing isolation, the project documents three containerization patterns: a Gondolin extension approach, plain Docker, and OpenShell sandboxing.

Features

• Unified Multi-Provider LLM API: A single interface (pi-ai) supports OpenAI, Anthropic, Google, xAI, and more, letting agents switch providers transparently.
• Agent Runtime with Tool Calling: pi-agent-core provides a full agent loop — state management, tool execution, retry logic, and context tracking — out of the box.
• Terminal UI Library: pi-tui offers differential rendering (React-like re-renders only of changed parts), ideal for building responsive TUI applications.
• Interactive Coding Agent CLI: pi-coding-agent is a drop-in coding assistant CLI with conversation history, file editing, and shell execution.
• Monorepo Architecture: All packages share a TypeScript build system (Biome for linting, Vitest for testing), making extension straightforward.
• Self-Extensible: The coding agent can modify its own prompts and extend its capabilities at runtime.

Installation

# Install the coding agent globally
npm install -g @earendil-works/pi-coding-agent

# Or install the core packages for custom development
npm install @earendil-works/pi-ai @earendil-works/pi-agent-core @earendil-works/pi-tui

For development from source:

git clone https://github.com/earendil-works/pi
cd pi
npm install --ignore-scripts
npm run build

Standalone binaries are available from the GitHub Releases page — build them from source archives using the provided build script.

Quick Start

import { createAgent } from "@earendil-works/pi-agent-core";
import { createLLM } from "@earendil-works/pi-ai";

const llm = createLLM({ provider: "anthropic", model: "claude-sonnet-4-6" });
const agent = createAgent({ llm, tools: [] });

agent.run({
  prompt: "List the files in the current directory and summarize them.",
});

Core Concepts

• Provider Abstraction: pi-ai normalizes the OpenAI-compatible API shape across all backends. Providers are configured once and reused across all agent instances.
• Agent Loop: pi-agent-core manages the think → act → observe cycle. State is persisted between turns, supporting long-running sessions.
• Tool Calling: Tools are first-class citizens with schema-based definitions. The runtime handles tool selection, argument validation, and error recovery.
• Differential Rendering: pi-tui tracks a virtual DOM of terminal output and renders only the changed regions, enabling smooth UI updates in terminal environments.

Advanced Features

Containerization Patterns

Pi documents three sandboxing approaches for production:

1. Gondolin Extension: Lightweight process isolation for trusted workloads.
2. Plain Docker: Full container isolation for multi-tenant deployments.
3. OpenShell Sandboxing: Minimal shell environment with explicit allowlists.

Multi-Provider Fallback

Configure multiple LLM providers in priority order; Pi automatically falls back to the next provider on failure or rate limit, with configurable retry strategies.

Examples

Interactive Coding Session

pi-coding-agent
# Start a conversation with the agent
> Help me refactor this Python file to use async/await

Custom TUI Agent

import { createTUI } from "@earendil-works/pi-tui";
import { createAgent } from "@earendil-works/pi-agent-core";

const tui = createTUI();
const agent = createAgent({ llm: createLLM({ provider: "openai" }) });

tui.render({
  agent,
  layout: "split", // chat panel + context panel
});

Pros

• ✅ Full-stack toolkit — API, runtime, TUI, and CLI in one package family
• ✅ TypeScript-native with excellent type safety
• ✅ No vendor lock-in — unified multi-provider API
• ✅ MIT license, self-hosted, transparent
• ✅ Differential TUI rendering for responsive terminal apps
• ✅ Active community with 79.5K+ stars and 9.8K forks

Cons

• ✅ TypeScript-only (no native Python SDK)
• ✅ No built-in permission system — relies on host permissions
• ✅ Relatively young ecosystem compared to LangChain/CrewAI
• ✅ Sandbox setup requires manual configuration

When to Use

• Building a new coding agent CLI — the pi-coding-agent package is production-ready out of the box.
• Multi-provider LLM applications — Pi's unified API abstracts away provider differences cleanly.
• Terminal-based agent interfaces — pi-tui's differential rendering gives a native-app feel in the terminal.
• Teams wanting a TypeScript-native agent stack — ideal for Node.js ecosystems.

Resources

• Official Repository
• npm Packages
• Releases