Pi Agent Harness
Unified LLM API, agent runtime, and interactive coding agent CLI supporting multiple model providers for terminal-based coding assistance.
- Source repo
- earendil-works/pi
- Stars
- ★ 116k
- Last updated
- today
- License
- MIT
- Primary language
- TypeScript
- FA score
- 42/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API · Claude API
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- Developers who want a unified interface to interact with multiple LLMs from the terminal using pi-coding-agent.
- Not a fit if
- Teams needing built-in permission isolation; Pi has none
- Users wanting one npm package instead of many
- New contributors relying on issues/PRs; they are auto-closed
- Source review
- 42/100 · Major gaps 6 safety controls not found
What does this agent do, and when should you use it?
Pi is an AI agent toolkit composed of several npm packages: @earendil-works/pi-coding-agent provides an interactive coding agent CLI, @earendil-works/pi-agent-core offers an agent runtime with tool calling and state management, and @earendil-works/pi-ai provides a unified multi-provider LLM API for OpenAI, Anthropic, Google, and more. Additional packages include @earendil-works/pi-tui (terminal UI library) and @earendil-works/pi-telemetry (telemetry contracts). Pi does not include a built-in permission system; it runs with the privileges of the launching process, but containerization options (Gondolin, Docker, OpenShell) are documented. The project is MIT-licensed and emphasizes supply-chain security with pinned dependencies, shrinkwrap, and audits.
Pi operates as an end-to-end coding agent workflow: the pi-ai package abstracts access to multiple LLM providers (OpenAI, Anthropic, Google), pi-agent-core provides an agent loop with tool calling and state management, and pi-coding-agent delivers an interactive CLI (e.g., pi) in the terminal, supporting ! commands. The Pi TUI library provides differential rendering for terminal interfaces. Developers can test via ./test.sh, build from source with npm run build, and create standalone binaries with ./scripts/build-binaries.sh. Permissions can be enhanced through containerization patterns like Gondolin, Docker, and OpenShell.
- Developers who want a unified interface to interact with multiple LLMs from the terminal using pi-coding-agent.
- Teams building custom agents that require tool calling and state management; pi-agent-core provides the runtime.
- Developers needing to switch between OpenAI, Anthropic, and Google APIs without rewriting code; pi-ai offers a consistent TypeScript API.
- Terminal app developers wanting a TUI library with differential rendering; pi-tui can be used standalone.
- Security-conscious teams that need to run coding agents in sandboxed environments; the containerization docs provide patterns using micro-VMs, Docker, or OpenShell.
- Open-source contributors who want to share their coding agent sessions to improve agent performance; use pi-share-hf to publish to Hugging Face.
How do you install or deploy this agent?
Install the coding agent CLI via npm:
npm install -g @earendil-works/pi-coding-agentAlternatively, use Bun:
bun install --global @earendil-works/pi-coding-agentRequires Node.js and Bun runtime. Configure API keys for your LLM providers (e.g., OpenAI, Anthropic, Google).
How do you use this agent?
Run the interactive coding agent CLI:
piOr run from source:
./pi-test.shFor development:
npm install --ignore-scripts
npm run build
npm run check
./test.shTo build a standalone binary (example for linux-x64):
VERSION="<release-version>"
tar -xzf "pi-${VERSION}-source.tar.gz"
cd "pi-${VERSION}"
./scripts/build-binaries.sh --offline-model-data --platform linux-x64 --out "$PWD/out"What are this agent's strengths and limitations?
- Multi-provider LLM support with a unified API, reducing vendor lock-in.
- Rich agent runtime (pi-agent-core) with tool calling and state management for complex workflows.
- Interactive coding agent CLI (pi-coding-agent) is ready to use for daily coding tasks.
- Strong supply-chain security including exact dependency pinning, shrinkwrap, and npm audit.
- Documented containerization modes (Gondolin, Docker, OpenShell) enhance security.
- No built-in permission system; containerizing or sandboxing is required for isolation, adding complexity.
- Dependence on LLM APIs incurs costs and requires network access.
- The toolkit is split across multiple npm packages, potentially confusing new users.
- Building standalone binaries requires running build scripts, which may be time-consuming and need network.
- New contributors' issues and PRs are auto-closed by default, which might discourage community submissions.
How does this agent compare with similar options?
The README does not explicitly mention other agents, but as a multi-provider LLM API and agent toolkit, it can be compared to LangChain, Claude Code, or OpenAI Codex. However, Pi emphasizes self-extensibility and a TUI, and is MIT-licensed.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Pi Agent Harness This agent | 42 · Major gaps | CLIFree + model costs | ★ 116k | today | TypeScript | OpenAI API · Claude API |
| zerostack | 57 · Major gaps | CLIFree + model costs | ★ 1.7k | 5d ago | Rust | OpenAI API · Claude API |
| MiniCode | 50 · Major gaps | CLIFree + model costs | ★ 1.1k | 10d ago | TypeScript | Claude API |
| Kun Workspace | 49 · Major gaps | Desktop appFree + model costs | ★ 6.3k | 1d ago | TypeScript | ChatGPT · Codex · OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: README explicitly states Pi has no built-in permission system, runs with the permissions of the launching user, and recommends containerization or sandboxing. This is an honest disclosure of permission boundaries, but no least-privilege mechanism or user confirmation flow is provided. Data flow transparency: README mentions telemetry packages but does not detail data flows. Sensitive data handling is not mentioned. Dependency security: README describes supply-chain hardening measures in detail, such as exact version pinning, npm audit, shrinkwrap, etc., with strong evidence. External effects: no mention of external side effects or network behavior. Rollback: no rollback mechanism mentioned. Source attribution: README and LICENSE provide author information, but publisher is unverified. Therefore, except for dependency security, most criteria score low.
Evidence shows: Test files (agent-loop.test.ts, agent.test.ts, e2e.test.ts) demonstrate rich unit and integration tests covering agent loop, tool calls, error handling, etc., indicating good internal consistency. Dependency availability: README mentions npm and Bun, but no detailed offline installation instructions, only build:offline. Failure messages: tests verify error message generation, e.g., 'provider exploded', indicating clear error handling. But no detailed documentation of runtime failures.
Evidence shows: README describes multiple use cases, such as coding agent CLI, unified LLM API, TUI, etc., and provides containerization patterns (Gondolin, Docker, OpenShell), indicating consideration for various environments. Capability boundaries: README explicitly states no built-in permission system and recommends sandboxing, defining boundaries. Trigger precision: no detailed description of tool call trigger conditions, but tests show precise handling of tool calls. Environment fit: supports multiple platforms (darwin, linux, windows) and multiple LLM providers, indicating good adaptability.
Evidence shows: README provides clear information architecture, listing all packages and descriptions. Install notes are detailed, including npm install, build, test, etc. Naming stability: package names use @earendil-works/ prefix, but no naming convention documentation. Examples and FAQ: README provides usage examples and links to docs, but no FAQ. Known limitations: README and SECURITY.md clearly state security boundaries and limitations. License is MIT, clear. Versioning: package.json has version number, but no CHANGELOG. Maintenance responsibility: README provides contribution guidelines and contact info, indicating maintainers.
Evidence shows: Output usability: agent produces structured messages and events, tests verify output format. Marginal value: provides unified LLM API and agent framework, potentially reducing integration costs. Cost-benefit: no performance or cost data, but open-source MIT license reduces cost.
Evidence shows: Claims in README (e.g., supply-chain hardening) are supported by specific implementations (e.g., check scripts), but no independent verification. Cross-source corroboration: test files provide internal validation, but no cross-validation with external sources. Fact-inference separation: README distinguishes facts (e.g., feature descriptions) from inferences (e.g., recommendations), but not explicitly labeled.
- Not found in source: least-privilege scopingGrant only what the task needs: a dedicated account or read-only token, scoped to specific directories and repos.
- Not found in source: confirmation before actingTurn on (or add) a confirmation step before it acts, and try it in a sandbox or test environment before real data.
- Not found in source: data-flow disclosureWatch which external services it contacts (proxy or firewall logs) and keep sensitive data out until you know where it goes.
- Not found in source: sensitive-data handlingUse dedicated, low-privilege, revocable API keys — never production credentials — and keep secrets out of logs.
- Not found in source: disclosed external effectsEstablish which external systems it writes to, sends to or changes, and verify with test accounts or repos before production.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- Pi has no built-in permission system and runs with user permissions by default, posing security risks; sandboxing is required.
- Publisher identity is unverified; supply chain risks should be carefully assessed.
- No rollback mechanism is provided; operations may be irreversible.
- Data flow transparency is insufficient; the specific flow of telemetry data is not described.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
New Features - Choose where /share uploads: sessionShareDestination selects auto, gist, or radius. See [Sessions and context](https://github.com/earendil-works/pi/blob/v1.3.0/packages/coding-agent/docs/settings.md#sessions-and-context) and [Export or share a session](https://github.com/earendil-works/pi/blob/v1.3.0/packages/coding-agent/docs/sessions.md#export-or-share-a-session). - Cache-preserving thinking level changes on OpenAI GPT-6: changing the thinking level mid-session with an API key keeps the prompt cache. …View on GitHub ↗ -
Release notes excerpt
New Features - Per-key OpenRouter model lists: with an OpenRouter key, Pi lists only the models that key may use, with the key's context size, max output, and prices, including regional endpoints set in models.json. See [OpenRouter](https://github.com/earendil-works/pi/blob/v1.2.0/packages/coding-agent/docs/providers.md#openrouter). …View on GitHub ↗ -
Release notes excerpt
New Features - Program status reporting: terminals and agent dashboards that support OSC 7501 see whether Pi is working, blocked on a dialog or login, done, or failed. See [Program status](https://github.com/earendil-works/pi/blob/v1.1.0/packages/coding-agent/docs/terminal-setup.md#program-status). - Claude Haiku 5.5: anthropic/claude-haiku-5-5, with adaptive thinking up to xhigh/max effort. …View on GitHub ↗
FAQ
What is Pi's permission model?
Which LLM providers does Pi support?
How does Pi ensure supply-chain security?
How can I share Pi session data?
Can Pi be built without network access?
npm run build:offline to rebuild using existing model data without network. When building binaries, use the --offline-model-data flag.