Find your next open-source project

Search by name, purpose, or keyword — or paste a GitHub repository URL

earendil-works/pi

Developer Tools

A minimal, extensible AI coding agent harness with a CLI, unified LLM API, agent runtime, and TUI library.

122,885
15,853
TypeScript
MIT
1 year old

What it is

Pi is a monorepo for an AI coding agent harness: a coding agent CLI, an agent runtime with tool calling and state management, a unified multi-provider LLM API, a durable conversation/task runtime, a terminal UI library, and a small object runtime called Chord. It targets developers who want to run an agent in a project directory and customize its behavior rather than adopt a fixed workflow. The defaults are functional, but sub-agents and plan mode are deliberately left out; you add them through extensions, skills, prompt templates, themes, or npm/git packages extensions skills packages.

Pi runs interactively, in print or JSON mode, over RPC, or through a TypeScript SDK, so the same harness can be used by a person in a terminal or embedded in another app usage CLI RPC SDK.

Getting started

Pi needs Node.js 22.19 or newer; the macOS, Linux, and Windows installers can install it if missing. On macOS/Linux, install the CLI with the pi.dev installer:

curl -fsSL https://pi.dev/install.sh | sh

On Windows, use the PowerShell installer:

powershell -c "irm https://pi.dev/install.ps1 | iex"

The installer pins dependencies and updates Pi through pi update. Alternatively, install from npm, which does not pin transitive dependencies:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

Then change into the project you want Pi to work on, start it, and connect a provider inside the interactive session:

cd /path/to/project
pi

Run /login inside Pi to add a subscription or API key, then give it a task. Full setup and usage instructions are at pi.dev/docs/latest; demos are at pi.dev. Nix users can run nix run github:earendil-works/pi/stable, pin a release tag, or build from a checkout with nix build . / nix run . Nix instructions.

Permissions and isolation

Pi has no 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. For stronger boundaries, the documentation describes three containerization patterns: a Gondolin extension that routes built-in tools into a local Linux micro-VM while keeping Pi and provider auth on the host, plain Docker for whole-process isolation, and OpenShell for a policy-controlled sandbox containerization.

Packaging and supply chain

The pi.dev installer installs from a generated install lock that pins transitive dependencies; the npm package itself does not pin them. Direct external dependencies are pinned to exact versions, and local/CI installs use --ignore-scripts where supported. Release binaries can be rebuilt from a versioned source archive covered by SHA256SUMS using scripts/build-binaries.sh supply-chain notes binary build. Development uses npm install --ignore-scripts, npm run build, npm run check, and ./test.sh development. The project is MIT licensed.

HotRepo's take

HotRepo's recorded daily snapshots show steady growth across several months: roughly 53.7k stars on 2026-05-24, 105.5k on 2026-09-15, and 122.9k on 2026-11-19, when it appeared at No. 17 on the TypeScript daily list with 191 stars gained. Those are separate daily records rather than a continuous series, but the long-run direction is consistent. The launch discussion around v1.0.0 drew a user who called Pi their favorite harness while questioning why the release was 1.0.0 rather than 0.100.0 HN thread comment. A more critical thread about the Linux config folder location drew a user who found the handling frustrating enough to explore other coding agents comment, with replies suggesting the simple check-for-existing-folder fix reply and advising forking and patching reply. That split — a minimal, forkable harness whose defaults will not suit everyone — is the practical frame for evaluating Pi.

Written by AI from the project's README, updated . The project's own docs are the source of truth.

Hacker News

Pi coding agent: config folder is out of place on Linux
▲ 56 · 21 comments · August 17, 2026
Pi v1.0.0
▲ 12 · 2 comments · October 1, 2026
Pi: Virtual Models
▲ 2 · 0 comments · November 10, 2026

You might also like

  1. SaladDay/cc-switch-cliA cross-platform CLI and TUI for switching API providers, MCP servers, prompts, skills and sessions across seven AI coding assistants.Rust5,521
  2. ZiChuanLan/pi-purgeA pi extension that swaps the coding agent's system prompt for your own file, so you can run controlled prompt experiments.JavaScript301
  3. google-gemini/gemini-api-cliA Go CLI that lets coding agents and shell scripts call Gemini models, generate media, analyze files, and run managed agents.Go462
  4. nicobailon/pi-subagentsLets Pi coding sessions hand review, scouting and implementation to focused child agents, including parallel and background runs.TypeScript4,071
  5. Gentleman-Programming/engramGives AI coding agents persistent memory across sessions so you stop re-explaining the same project; for developers running MCP-capable agents.Go7,588