Pi Agent Harness: Unified LLM API and Coding Agent Toolkit
earendil-works/pi
Pi Agent Harness gives you a unified LLM API, an agent runtime with tool calling, and a self-extensible coding agent in one TypeScript monorepo. Reach for it if you want a full agent stack without stitching together multiple libraries; skip it if you need a hosted service or a permission system built in β the README is explicit that Pi runs with your user permissions by default and offers containerization docs instead. For stronger isolation, plan to use Docker, a micro-VM, or an OpenShell sandbox on top of Pi.
What is Pi Agent Harness?
Pi Agent Harness is a TypeScript monorepo with four packages for building AI agents. @earendil-works/pi-ai wraps OpenAI, Anthropic, and Google into a single API. @earendil-works/pi-agent-core runs the agent loop, manages state, and handles tool calls. @earendil-works/pi-coding-agent exposes this as an interactive CLI coding assistant. @earendil-works/pi-tui powers the terminal UI with differential rendering. A separate project, pi-chat, adds Slack and chat workflow support.
Key Components and Capabilities
- βUnified LLM API supporting OpenAI, Anthropic, and Google through a single interface
- βAgent runtime with tool calling and state management for orchestrating multi-step tasks
- βSelf-extensible coding agent CLI β add your own tools and `!` commands
- βTerminal UI with differential rendering for responsive local interaction
- βThree containerization patterns documented: Gondolin extension, plain Docker, and OpenShell sandbox
- βSupply chain hardening with pinned dependencies, exact versions, and npm-shrinkwrap for transitive deps
- βMonorepo structure keeps provider abstraction, agent loop, and CLI in sync across updates
- βOpen session publishing to Hugging Face for sharing real-world agent work
Getting Started with Pi
Clone the repo and run `npm install --ignore-scripts` to pull all dependencies without executing lifecycle scripts. Build everything with `npm run build`, or use `npm run build:offline` to skip network access. Type checking and linting run via `npm run check`. Test suites execute with `./test.sh` (LLM tests auto-skip without API keys). For standalone binaries, GitHub releases include a versioned source archive; extract it and run the build script with `--offline-model-data` for the bundled model snapshot.
Using the Pi Coding Agent
After installation, run the `pi` command to launch the interactive CLI. The coding agent cycles through planning, tool calls, and response generation. You can extend it by adding custom tools or `!` commands. To publish sessions, install `badlogic/pi-share-hf` and configure your Hugging Face CLI β the README links to a video walkthrough of the process.
Practical Applications
- β’Running an interactive coding agent in the terminal for autonomous code generation and editing
- β’Prototyping agentic workflows that switch between OpenAI, Anthropic, and Google models
- β’Building a local AI assistant with custom tools without relying on a hosted service
- β’Integrating agent capabilities into Slack workflows via the separate pi-chat package
- β’Sharing OSS coding agent sessions to contribute real-world data to the community
- β’Sandboxed development tasks using Docker or the Gondolin micro-VM extension
Strengths
- β**Unified LLM API**: Offers a single, multi-provider API (`pi-ai`) that abstracts away different large language model services, supporting providers like OpenAI, Anthropic, and Google, which simplifies LLM integration for agent development.
- β**Interactive Coding Agent CLI**: Includes a dedicated command-line interface (`pi-coding-agent`) for interactive coding tasks, enabling direct engagement with an AI agent for code generation and modification workflows.
- β**Stable Agent Runtime**: Provides a core agent runtime (`pi-agent-core`) with built-in capabilities for tool calling and state management, forming the foundation for building complex and intelligent AI agents.
- β**Thorough Security Practices**: Demonstrates a commitment to security through detailed supply-chain hardening, including pinning exact dependency versions, enforcing `package-lock.json` integrity, and auditing npm dependencies. It also provides explicit guidance and patterns for containerizing or sandboxing the agent to manage permissions and access.
Permissions and Containerization
- β³Pi does not include a built-in permission system to restrict access to the filesystem, processes, network, or credentials.
- β³By default, the agent runs with the full permissions of the user and process that launched it, which can pose a security risk.
- β³Achieving stronger security boundaries requires external containerization or sandboxing solutions, adding setup and operational complexity.
Exploring Similar Agent Tools
Common Questions
Pi Agent Harness is MIT licensed, allowing free use, modification, and distribution with minimal restrictions.
Pi Agent Harness is written in TypeScript throughout its monorepo of packages.
The pi-ai package unifies OpenAI, Anthropic, and Google models behind a single API.
No built-in permission system exists. By default it runs with your user permissions. The README documents containerization patterns for stronger isolation.
Check CONTRIBUTING.md for guidelines and AGENTS.md for project-specific rules. New contributor issues and PRs are auto-closed by default and reviewed daily.
Install badlogic/pi-share-hf, configure the Hugging Face CLI, and run the share tool. The README links to a video showing the full workflow for publishing sessions.
The problem it solves
Building an AI coding agent typically requires cobbling together separate libraries for provider access, agent orchestration, tool calling, and terminal UI. Pi Agent Harness consolidates these pieces into a single monorepo so you can prototype agentic workflows without dependency juggling.
Who should try it β and who should skip
Pi Agent Harness suits developers comfortable with TypeScript who want a self-extensible coding agent running locally with control over their LLM provider. It's also a fit if you need to prototype agentic workflows using multiple models without vendor lock-in. Skip it if you want a hosted agent service, need built-in security boundaries without containerization, or prefer a single-purpose package over a monorepo that includes TUI, agent runtime, and provider API in one repo.