Pi: A TypeScript toolkit that bundles LLM access, agent loops, and a coding CLI

What Pi actually bundles

Pi is not a single tool. It is a monorepo that publishes several npm packages. The README lists four of them: @earendil-works/pi-coding-agent, the interactive coding agent CLI; @earendil-works/pi-agent-core, the agent runtime with tool calling and state management; @earendil-works/pi-ai, a unified multi-provider LLM API for OpenAI, Anthropic, Google and others; and @earendil-works/pi-tui, a terminal UI library with differential rendering. There is also @earendil-works/pi-telemetry, which provides vendor-neutral telemetry contracts, a reference adapter, conformance tests, and typed schemas. The project's own description calls it a 'provider-neutral LLM API, agent loop, terminal interface, and coding CLI.' That is a wide surface. The value proposition is that you get the whole stack in one place, in TypeScript, instead of assembling separate libraries for API access, agent state, and terminal rendering.

Who this is for

The target user is a developer who wants an interactive coding agent that can be extended and that does not tie them to a single LLM vendor. The README points to the coding agent as the main entry point, and the website pi.dev hosts demos and documentation. The project also encourages sharing OSS coding agent sessions, which suggests the intended audience is open source maintainers and contributors who want to improve real-world agent behavior. If you are building your own agent harness, the lower-level packages like pi-agent-core and pi-ai give you building blocks. If you just want a CLI that helps you code, pi-coding-agent is the package to install. The monorepo structure means you can use one package without the others, but the tight integration across packages is the main reason to choose Pi over a collection of separate tools.

How the pieces fit together

The architecture is visible from the package list. pi-ai sits at the bottom, providing a unified API over multiple LLM providers. pi-agent-core builds on that with a runtime that handles tool calling and state management. pi-coding-agent uses the agent runtime to implement an interactive coding agent CLI. pi-tui provides the terminal interface with differential rendering, which is a technique to minimize redraws by computing the difference between the previous and next screen state. The README does not describe the data flow in detail, but the layering is clear: provider calls go through pi-ai, agent logic through pi-agent-core, and user interaction through pi-tui or the CLI. The telemetry package sits alongside, offering contracts and conformance tests so that different tools can emit telemetry in a consistent format. This modular design means you could replace the TUI with your own interface, or swap the agent loop for a different one, as long as you keep the same state and tool-calling contracts.

Getting it running

The README gives development commands rather than end-user installation instructions. To build from source, you run npm install --ignore-scripts, then npm run build. There is also npm run build:offline, which rebuilds using existing model data without network access. For checks, npm run check runs lint, format, and type checks. Tests run via ./test.sh, which skips LLM-dependent tests if you do not have API keys. To run Pi from sources, use ./pi-test.sh from any directory. For standalone binaries, the release source archive includes a SHA256SUMS file, and you extract it and run ./scripts/build-binaries.sh --offline-model-data --platform linux-x64 --out "$PWD/out". The --offline-model-data flag uses the provider model data snapshot included in the release instead of refreshing it from live catalogs. This is a concrete path to a binary, but it assumes you are comfortable building from source. The README also mentions pi update --self for self-updates, which implies the published CLI supports updating itself.

The missing permission system is a real limitation

The README is explicit: Pi does not include a built-in permission system for restricting filesystem, process, network, or credential access. By default, it runs with the permissions of the user and process that launched it. That is a significant gap for a coding agent that can execute commands and edit files. An agent with your shell permissions can delete files, send network requests, or read credentials without any prompt. The project acknowledges this and points to containerization as the solution. It documents three patterns: a 'Gondolin extension' that keeps pi and provider auth on the host while routing built-in tools and '!' commands into a local Linux micro-VM; plain Docker to run the whole pi process in a container; and OpenShell, a policy-controlled sandbox. Each has trade-offs. Gondolin gives you host auth and sandboxed tools, but it is more complex. Plain Docker is simple but may restrict access to your host filesystem in ways that break workflows. OpenShell adds policy control but is another dependency. This is not a tool you can run directly on your workstation without thinking about isolation.

Supply-chain hardening is a priority

The README describes a serious approach to dependency management. Direct external dependencies are pinned to exact versions, while internal workspace packages remain version-ranged. The .npmrc sets save-exact=true and min-release-age=2 to avoid same-day dependency releases during npm resolution. package-lock.json is the ground truth, and pre-commit blocks accidental lockfile commits unless PI_ALLOW_LOCKFILE_CHANGE=1 is set. The coding-agent package includes an npm-shrinkwrap.json to pin transitive dependencies for npm users. Release smoke tests use npm run release:local to build, pack, and create isolated npm and Bun installs outside the repo before tagging. CI installs with npm ci --ignore-scripts, and a scheduled workflow runs npm audit --omit=dev plus npm audit signatures --omit=dev. Shrinkwrap generation has an allowlist for dependency lifecycle scripts, and new lifecycle-script dependencies fail checks until reviewed. This is more rigorous than many open source projects. The trade-off is that contributors cannot casually add dependencies, and the maintainers treat dependency changes as code changes that need review.

Maintenance and upgrade cost

The project is under active development, with three releases in August 2026 alone: v0.84.2, v0.84.3, and v0.84.4. The version number is below 1.0, which signals that APIs may change. The README mentions longer-term plans in RFCs, so the project has a roadmap, but it is not stable yet. Upgrading from one version to the next may require adapting to changes in the agent runtime or the CLI. The build process regenerates model data from provider catalogs, which means you need network access for a full build, but --offline-model-data lets you use a snapshot for reproducible builds. The project also auto-closes new issues and PRs from new contributors by default, with maintainers reviewing them daily. That policy reduces noise but may slow down community contributions. For adoption, you should budget time to track releases and test your workflows after each upgrade. The license is MIT, which is permissive, but the README does not describe any contributor license agreement or patent grant, so you should review the license file yourself.

A real alternative: build your own with separate libraries

The main alternative to Pi is assembling your own stack from separate libraries. For example, you could use the Vercel AI SDK for provider-neutral LLM access, LangChain for agent loops, and Ink for terminal UIs. The difference is that Pi provides a coherent, integrated set of packages that share contracts and types, while a DIY approach requires you to glue together libraries that may not align in their state management or tool-calling conventions. The trade-off is that Pi is a smaller, less mature project, so you inherit its design decisions and its release cadence. With separate libraries, you can choose the best tool for each layer and swap components independently, but you also take on the integration burden. Pi's telemetry package with conformance tests is a specific advantage, because it standardizes how agents emit telemetry, which is rare in the DIY world. If you value consistency over flexibility, Pi is the better choice; if you need to customize every layer, a DIY approach gives you more control.

Editorial conclusion

Adopt Pi if you want a TypeScript-native coding agent that you can extend and run across multiple LLM providers, and if you are comfortable with its explicit lack of a built-in permission system. Do not adopt it if you need out-of-the-box sandboxing or a stable, long-term supported API, because the project is under active development with frequent releases and a contribution policy that auto-closes new contributor PRs. Before adopting, verify the current release version, read the containerization docs, and test the agent with your provider and your specific codebase.

Official sources

1. Official README
2. Project repository
3. Release notes