Pi Agent Harness

Pi Agent Harness (CLI command pi) is a highly extensible interactive AI coding agent toolkit maintained by the earendil-works organization, with Armin Ronacher (mitsuhiko) as the primary maintainer. Built in TypeScript (96.6%), organized as an npm workspaces monorepo, currently at v0.74.0 with 214 releases and 3,977 commits.

Core Capabilities#

• Interactive Coding Assistant: Drive file read/write, code editing, and shell command execution via natural language in the terminal
• Unified LLM API (@earendil-works/pi-ai): Compatible with OpenAI, Anthropic, Google, and other major providers
• Agent Runtime (@earendil-works/pi-agent-core): Tool call scheduling and state machine management
• Built-in Tools: read, write, edit, bash enabled by default; optional read-only tools grep, find, ls
• Context Compaction: Automatic context window management for long sessions to prevent overflow
• Sub-agent Delegation: Parallel task execution via extension packages
• Multimodal Input: File and image references via @file or @screenshot.png

Authentication#

• Subscription Login: Built-in support for Claude Pro/Max, ChatGPT Plus/Pro (Codex), GitHub Copilot (via /login)
• API Key: Via environment variables (e.g., ANTHROPIC_API_KEY) or ~/.pi/agent/auth.json

Session Management#

Sessions are persisted in JSONL format with support for auto-save, continue (-c), branch (/fork), clone (/clone), and tree browsing (/tree).

Extensibility#

• TypeScript extension modules for registering custom tools, commands, event handlers, and UI components
• Skills, Prompt Templates, Themes, and Pi Packages for deep customization
• MCP compatibility via community package pi-mcp-adapter
• 50+ official extension examples (plan mode, permission control, path protection, SSH execution, sandbox, etc.)
• 2,200+ community packages covering web search, browser automation, sandbox execution, Notion/WhatsApp integration, Mermaid rendering, etc.

Architecture Modules#

• @earendil-works/pi-coding-agent: Top-level interactive coding agent CLI entry point
• @earendil-works/pi-agent-core: Agent runtime
• @earendil-works/pi-ai: Unified LLM provider communication layer
• @earendil-works/pi-tui: Terminal UI library (diff rendering)
• @earendil-works/pi-web-ui: AI chat interface web component library

Programmatic Interfaces#

Beyond CLI, exposes Node.js SDK, stdin/stdout JSONL RPC mode, and JSON Event Stream mode for upstream application integration.

Installation & Usage#

curl -fsSL https://pi.dev/install.sh | sh
npm install -g @earendil-works/pi-coding-agent

pi                          # Interactive mode
pi -p "Summarize this codebase"  # One-shot prompt
cat README.md | pi -p "Summarize this text"  # Pipe input
pi @file1 @file2 "prompt"     # File references
pi -c                        # Resume latest session
pi -r                        # Browse session history
pi install npm:pi-subagents  # Install extension

Project-level config: Place AGENTS.md or CLAUDE.md in the project root; pi auto-loads it as agent behavior guidelines.

In-session shortcuts: Ctrl+L switch model, Shift+Tab switch thinking level, @ fuzzy file search, !command run shell and feed output to model.

Use Cases#

• Daily code writing, refactoring, and local build/test automation
• Code review, repository summarization, and multimodal understanding
• Standardized AI collaboration workflows for OSS via AGENTS.md
• Integrating AI agent capabilities into third-party workflows or IDEs via SDK/RPC
• Publishing coding sessions to Hugging Face via pi-share-hf for agent improvement