Pi
Lean by design. Multi-model by default.
Pi keeps its system prompt under 1,000 tokens — an order of magnitude lighter than most commercial agents. Swap model providers without rewriting agent logic. Run fully local with Ollama. Embed in any TypeScript service via createAgentSession().
Pi CLIMITbadlogic/pi-monoThree modes
InteractiveProgrammaticLocal / Air-gappedGetting started
Install Pi
npm install -g @earendil/pi-agent# macOS alternativebrew install earendil-works/tap/piConfigure your models
Create ~/.pi/models.json to point Pi at one or more providers. Pi will use the first entry as default.
{ "default": "anthropic-messages/claude-sonnet-4-5", "providers": { "anthropic-messages": { "apiKey": "sk-ant-..." }, "openai-completions": { "apiKey": "sk-..." }, "ollama": { "baseUrl": "http://localhost:11434" } }}Run Pi — or embed it
Interactive terminal session:
pi# Switch model mid-session/model openai-completions/gpt-4o# Fork the current context into a branch/fork# View session tree/treeProgrammatic via SDK:
import { createAgentSession } from '@earendil/pi-sdk';
const session = await createAgentSession({ model: 'anthropic-messages/claude-sonnet-4-5', systemPrompt: 'You are a financial analysis agent.', tools: ['read', 'write', 'bash'],});
for await (const event of session.run('Analyse Q1 revenue data')) { if (event.type === 'text') process.stdout.write(event.text);}Built-in tools
| Tool | Availability | Notes |
|---|---|---|
| read | Built-in | Read files and directory trees |
| write | Built-in | Create and overwrite files |
| edit | Built-in | Surgical in-place edits |
| bash | Built-in | Execute shell commands; no sandbox by default |
| Skills (Lazy) | Add-on | Custom skill definitions loaded on demand — not in the base system prompt |
| Community plugins | Add-on | npm packages that extend Pi’s toolset (web search, Slack, databases) |
Model providers
| Provider key | Models | Data egress |
|---|---|---|
| anthropic-messages | Claude Sonnet, Haiku, Opus | Anthropic API |
| openai-completions | GPT-4o, o3-mini, o1 | OpenAI API |
| google-generative-ai | Gemini 2.5 Pro / Flash | Google API |
| mistral | Mistral Large, Codestral | Mistral API |
| azure · bedrock | Azure OpenAI, AWS Bedrock hosted models | Your cloud region |
| ollama · lm-studio · vllm | Llama 3, Mistral, Phi-3, Qwen, any GGUF | None — fully local |
When to use Pi
Context efficiency is critical — every token counts
Pi’s system prompt stays under 1,000 tokens. Claude Code and Codex typically consume 8,000–10,000 tokens of context on every turn just for instructions. In a high-volume pipeline running thousands of agent calls per day, that overhead compounds fast. Pi leaves virtually all of the context window for actual task data.
Multi-model routing — different tasks, different models, same agent logic
Pi’s provider layer decouples the agent from the underlying model. Route expensive reasoning tasks to Claude Opus, fast retrieval to Gemini Flash, cost-sensitive batch work to Mistral, and sensitive data processing to a local Ollama instance — all within the same session or pipeline, without rewriting agent logic per provider.
Data sovereignty — no tokens leave your infrastructure
Pair Pi with Ollama or LM Studio on a local or on-premise machine. Zero data egress. No API keys. No third-party logging. This is the right setup for maritime ISM Code records, crew PII, confidential contracts, or any data with jurisdictional residency requirements.
Embedding agents in your own products via SDK
Use createAgentSession() from @earendil/pi-sdk to embed a full agent session into any TypeScript service — a Next.js API route, an Express microservice, or a background worker. Stream events, intercept tool calls, fork sessions for parallel explorations, and dispose sessions cleanly when done. MIT license means zero friction in commercial products.