Pi Agent Harness: A TypeScript Toolkit with a Unified LLM API and a Self-Extensible Coding Agent

What it is

earendil-works/pi - project name Pi Agent Harness - is a TypeScript AI agent toolkit under the MIT license. The repo was created on 2025-08-09 and as of 2026-08-06 it sits at 84,648 stars and 10,479 forks (stars move in real time; the numbers here are same-day snapshots). This week it placed #10 on the GitHub weekly trending chart with a weekly gain of 4,896 stars.

It is not a single CLI. It is a monorepo that splits the layers you need to build an agent into five independently usable npm packages:

The official one-liner is "AI agent toolkit: unified LLM API, agent loop, TUI, coding agent CLI" - which maps directly onto the five packages above. The project lives at pi.dev, docs at pi.dev/docs/latest, and Slack/chat automation lives in a separate repo, earendil-works/pi-chat.

One word that recurs in the README is "self extensible" - the coding agent is designed as an extensible harness, not a closed product.

What pain it solves

If you have ever glued an LLM agent together yourself, you have probably hit these:

1. Multi-provider fragmentation. OpenAI, Anthropic, and Google all differ in API shape, streaming protocol, and tool-calling schema. Every swap means rewriting the call layer. pi-ai unifies that, so upper-layer agent code does not move when the model does.
2. Reinventing the agent runtime. The tool-calling loop, the state machine, interrupt/resume, context management - easy to get wrong every time. pi-agent-core extracts that into a reusable runtime with tool calling and state management.
3. Hand-writing a TUI hurts. Differential rendering, long-output scrolling, streaming-token display. pi-tui ships a differential-rendering TUI library.
4. Telemetry locked to a vendor. Observability formats follow the vendor SDK; switching providers loses instrumentation. pi-telemetry is vendor-neutral with contracts, a reference adapter, and conformance tests.
5. Building a coding agent from zero. pi-coding-agent ships an interactive CLI and is extensible.
6. Permission boundaries nobody owns. Most agent tools run with full permissions by default. Pi's README states plainly that it ships no built-in permission system - and then offers three containerization patterns. That is a pain point taken seriously, not hidden.

Core features

1. Five packages, take what you need

The monorepo layout means you do not have to adopt the whole thing. Want only the unified LLM API? Install pi-ai. Want only the runtime? Install pi-agent-core. Building your own terminal agent UI? Take pi-tui. This "toolkit" posture differs from agent tools that ship as one sealed product.

2. A self-extensible coding agent

pi-coding-agent is an interactive coding agent CLI, and the README stresses it is "self extensible." Its tool set and behavior are not closed - they can be extended (the extension mechanism lives in pi.dev/docs; the README does not elaborate). The positioning is a harness, not a fixed product.

3. Permissions and containerization (important)

The README spends a full section here and opens directly:

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.

In other words: Pi inherits the full permissions of the user and process that launch it. It does not block files, processes, the network, or credentials. For stronger boundaries, you containerize or sandbox it yourself. The README gives three patterns, with details in packages/coding-agent/docs/containerization.md:

This matters for production deploys: choosing Pi means accepting that permissions are your job - but the project writes the playbook instead of leaving you to figure it out.

4. Supply-chain hardening (the README's longest section)

This is where Pi separates from most peers. The README lists a long set of measures, summarized faithfully:

• Direct external dependencies are pinned to exact versions. Internal workspace packages stay version-ranged.
• .npmrc sets save-exact=true and min-release-age=2 - the latter blocks dependencies released less than 2 days ago, which catches same-day poison attempts.
• package-lock.json is the dependency ground truth. A pre-commit hook rejects accidental lockfile commits unless PI_ALLOW_LOCKFILE_CHANGE=1 is set.
• The published CLI package carries npm-shrinkwrap.json generated from the root lockfile, pinning transitive deps for npm users.
• Release smoke tests use npm run release:local, building and packing isolated npm and Bun installs outside the repo before tagging.
• CI installs with npm ci --ignore-scripts, and a scheduled GitHub workflow runs npm audit --omit=dev plus npm audit signatures --omit=dev.
• Shrinkwrap generation has an explicit allowlist for dependency lifecycle scripts; new lifecycle-script deps fail checks until reviewed.

For teams that care about supply chain, this is a complete practice checklist - you can hold your own project up against it.

5. Sharing OSS coding-agent sessions

The README closes by asking users to share session data from using Pi (or other coding agents) on open-source work. The rationale: public OSS session data improves coding agents on real tasks, tool use, failures, and fixes - better than toy benchmarks. The publishing tool is badlogic/pi-share-hf, publishing to Hugging Face, and the author publishes his own pi-mono sessions to badlogicgames/pi-mono. If you care about training-data reuse, this is a channel to be aware of.

Three-minute start

A caveat first: Pi's README is aimed at contributors. End-user install and usage live at pi.dev/docs. The commands below are all copy-pasteable from the README.

Running from source (contributor path)

npm install --ignore-scripts  # Install all dependencies without lifecycle scripts
npm run build         # Refresh model data, then build all packages
npm run build:offline # Rebuild using existing model data, no network needed
npm run check         # Lint, format, and type check
./test.sh            # Run tests (skips LLM-dependent tests without API keys)
./pi-test.sh         # Run pi from sources (can be run from any directory)

--ignore-scripts shows up repeatedly on purpose - Pi does not trust dependency lifecycle scripts by default. That is part of the supply-chain posture above.

Building standalone binaries (from release source)

GitHub releases include a versioned source archive covered by the release's SHA256SUMS file. Extract and run the official build script:

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"

--offline-model-data builds against the release's bundled provider model-data snapshot instead of refreshing from live provider catalogs. The script still installs dependencies, builds the monorepo, compiles the Bun executable, and stages runtime assets. Package maintainers who supply dependencies separately can pass --skip-install --skip-deps.

npm package

@earendil-works/pi-coding-agent is published to npm (the README carries a version badge); the exact install command is on pi.dev/docs. When configuring provider auth, an API key looks like sk-xxx and follows each provider's environment-variable convention - the README does not elaborate.

Who it is for, and gotchas

Who it is for

• Developers who want a self-extensible coding agent. pi-coding-agent is a harness, not a sealed product; you can extend it.
• Teams that need a unified multi-provider LLM API. pi-ai adapts OpenAI/Anthropic/Google behind one layer; swapping models does not touch the upper layer.
• People who do not want to reinvent the agent runtime. pi-agent-core packages the tool-calling loop and state management as a reusable module.
• TypeScript teams. Everything is TS; typed schemas and type checks are part of the build pipeline.
• Teams that care about supply-chain security. Pi's hardening list works as a template.

Gotchas

1. No built-in permission system. The biggest one. Pi inherits the host user/process permissions, meaning the agent can read your private keys, run rm -rf, and reach the network. For production, isolate with one of the three containerization patterns in the README.
2. New-contributor issues and PRs are auto-closed. README verbatim: "New issues and PRs from new contributors are auto-closed by default." It is not a cold shoulder - maintainers review auto-closed issues daily - but the first time your PR is closed seconds after submission, do not panic; it is process.
3. The README is not for end users. Install, config, and usage are at pi.dev/docs. The README is for people changing source. Before you run npm run build, confirm you actually want the contributor path.
4. min-release-age=2 blocks fresh dependencies. If you fork and try to add a package released today, the npmrc rule may reject it. That is an intentional safety policy, not a bug.
5. New dependencies with lifecycle scripts fail checks. When extending dependencies, a new package with an install script that is not on the allowlist will fail npm run check and require review.
6. Session data is shareable by design. If you use Pi on closed-source or sensitive projects, note that pi-share-hf is meant for OSS sessions - do not push sensitive sessions to Hugging Face.

How it compares

The coding-agent CLI lane is crowded. Names that belong in the same conversation as Pi include Claude Code, Aider, Cline, and Cursor CLI. The table below states only Pi-side facts verifiable from the README; it does not fabricate numbers for competitors. The competitor column only names the commonly known positioning - verify specifics on each project's site.

One-line differentiation: Pi splits "building an agent" into separately usable packages, and makes explicit the two things most peers leave implicit - permissions and supply chain. The cost is that end-user docs are not in the README (you go to pi.dev/docs); the payoff is that when you build your own agent, nearly every layer has a ready package.

References

• earendil-works/pi README: https://github.com/earendil-works/pi
• Project site: https://pi.dev
• Docs: https://pi.dev/docs/latest
• npm package @earendil-works/pi-coding-agent: https://www.npmjs.com/package/@earendil-works/pi-coding-agent
• Pi RFCs: https://rfc.earendil.com/keyword/pi/
• Containerization docs: packages/coding-agent/docs/containerization.md (in-repo)
• Session-sharing tool: https://github.com/badlogic/pi-share-hf
• Author's pi-mono session dataset: https://huggingface.co/datasets/badlogicgames/pi-mono