blog.dopana

Back

In the landscape of AI coding assistants, most tools are built as monolithic β€œblack boxes.” They lock developers into rigid workflows, predetermined UI layouts, and fixed plan modes. If you want to add a custom tool, tweak prompt handling, or integrate a specialized sandbox, you often have to wait for vendor updates or write fragile wrapper scripts.

Pi (@earendil-works/pi) reimagines this dynamic with a clear philosophy: Adapt the AI agent to your workflow, not the other way around.

[!NOTE] Pi is an open-source AI agent harness project developed by earendil-works (led by Mario Zechner / badlogic). Rather than bloated features, Pi provides clean, modular primitives for terminal-first AI development.

1. Explain Like I’m 10 (ELI5)#

Imagine buying a sports car where the hood is welded shut: you can’t swap the engine, change the dashboard, or attach custom sensors.

Pi Agent Harness is like a modular racing chassis:

  • Engine Swap: Switch between Anthropic Claude, OpenAI, Google Gemini, DeepSeek, or local models via llama.cpp seamlessly.
  • Custom Dashboard: Build custom TypeScript extensions that render interactive terminal UIs or Q&A prompts.
  • New Skills: Teach the agent project-specific workflows using Skills and Prompt Templates.
  • Time-Travel Dashboard: Every interaction is stored in a tree-structured session file. If an approach fails, you can branch back to any previous step and try another path without losing history.

2. The 4-Layer Modular Architecture#

Pi is structured as four distinct npm packages, allowing developers to embed components into custom tools or use the full CLI directly:

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚        @earendil-works/pi-coding-agent (CLI)             β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚        @earendil-works/pi-tui (Terminal UI)             β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚        @earendil-works/pi-agent-core (Agent Engine)     β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚        @earendil-works/pi-ai (Unified Provider API)    β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
text
PackagePurpose
@earendil-works/pi-aiA unified API layer wrapping over 30+ LLM providers (Anthropic, OpenAI, Google Gemini, DeepSeek, Bedrock, llama.cpp, etc.).
@earendil-works/pi-agent-coreThe core runtime managing tool calls (read, write, edit, bash), message history, agent loop, and context compaction.
@earendil-works/pi-tuiA terminal UI library designed for high-performance differential rendering.
@earendil-works/pi-coding-agentThe ready-to-use interactive CLI agent harness for your terminal.

3. Core Features & Key Strengths#

Self-Extensibility via TypeScript#

Out of the box, Pi provides four fundamental tools to the model: read, write, edit, and bash. However, you can extend Pi without forking its internal codebase:

  • Skills (/skill:name): Modular task workflows defined in Markdown or TypeScript.
  • Extensions: Custom TypeScript modules adding interactive tools, status lines, or custom footers.
  • Prompt Templates: Quick-expansion prompt macros accessible via /template-name.
  • Pi Packages: Standard npm or git packages to distribute custom themes, skills, and extensions across teams.

Tree-Structured Sessions (/tree)#

Unlike linear chat logs, Pi records sessions in JSONL format as an acyclic tree structure (where each step tracks an id and parentId).

By using /tree in interactive mode, developers can visually navigate history, jump back to earlier prompt states, create branches, and filter messages.

[!TIP] Press Ctrl+O within the /tree viewer to toggle view modes: full history, no-tool calls, user messages only, or bookmarked items.

Comprehensive Provider Support & Local LLMs#

Pi supports both API keys and subscription logins:

  • Cloud Providers: Anthropic Claude, OpenAI, Google Gemini, DeepSeek, NVIDIA NIM, Groq, Mistral, OpenRouter, and more.
  • Local Models: Native llama.cpp router support (/llama) for downloading, loading, and running GGUF models offline.

Flexible Containerization & Sandboxing#

Pi defaults to running with host user permissions. When executing untrusted code or automated tasks, Pi supports containerized execution via:

  1. Gondolin Micro-VM: Keeps pi on the host while routing bash commands into a lightweight Linux VM.
  2. Plain Docker: Runs the entire pi process in isolated containers.
  3. OpenShell: Enforces fine-grained permission security policies.

4. Quick Start Guide#

Installation#

Install globally using npm:

Terminal
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
bash

Or via the official install script:

Terminal
curl -fsSL https://pi.dev/install.sh | sh
bash

Launching & Provider Setup#

Set your API key and start the interactive CLI:

Terminal
export ANTHROPIC_API_KEY=sk-ant-...
pi
bash

Useful interactive commands:

  • /model: Select active LLM model (or press Ctrl+L).
  • /login: Authenticate with subscription credentials.
  • /tree: Open the interactive session tree viewer.
  • /compact: Trigger manual context compaction.
  • /reload: Hot-reload keybindings, extensions, skills, and prompt templates.

5. Comparing Pi with OpenCode, Claude Code & Codex#

FeaturePi Agent (@earendil-works/pi)Claude CodeOpenAI CodexOpenCode
PhilosophyUnopinionated Harness (Self-extensible)Opinionated Assistant (Tailored for Claude)Dedicated Assistant (Tailored for OpenAI)Modular Open-Source Framework
LLM Providers30+ Providers (Anthropic, OpenAI, Gemini, DeepSeek, llama.cpp)Locked to Anthropic EcosystemLocked to OpenAI EcosystemMulti-provider (API keys/OpenRouter)
Session ManagementTree Sessions (/tree): Branching tree history with in-place rewindingLinear chat historyLinear chat historyStandard session files
ExtensibilityTypeScript Extensions, Skills, Prompt Templates, Pi PackagesLimited hooks & sub-agentsBasic Custom Instructions / ToolsPlugin architecture & Scheduler
Terminal UIHigh-performance differential TUI (pi-tui)Custom Terminal UIBasic CLITerminal CLI
Integration Modes4 Modes: Interactive CLI, Print/JSON, RPC, Embeddable SDKStandalone CLICLI / APICLI / Framework
SandboxingGondolin Micro-VM, Docker, OpenShellHost / Docker ContainerHostDocker / Local

6. Supporting Open-Source AI Research#

Pi encourages developers working on open-source projects to publish their coding session logs using badlogic/pi-share-hf. Real-world developer interactions help the community train better open models, refine prompt evaluations, and improve agent tooling.

References#