Exploring Pi Agent Harness: Extensible Terminal AI Agent

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)    │
└─────────────────────────────────────────────────────────┘

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:

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

Or via the official install script:

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

Launching & Provider Setup#

Set your API key and start the interactive CLI:

export ANTHROPIC_API_KEY=sk-ant-...
pi

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#

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#

• Pi Repository on GitHub ↗
• Official Website ↗
• Pi Documentation ↗
• Earendil Works RFCs ↗