Pi: a minimal, extensible harness for coding agents

Everything worth knowing about earendil-works/pi: an MIT-licensed monorepo bundling an interactive coding CLI, an agent loop, a model API, and an extensible terminal interface.

What Pi is

Pi is a terminal coding harness. Its main package, @earendil-works/pi-coding-agent, offers an interactive conversation with read, write, edit, and command-execution tools; the same repository publishes the pi-agent-core runtime, the multi-provider pi-ai API, the pi-tui interface library, and telemetry contracts.

It doesn’t aim to be a closed environment that enforces a methodology. The official documentation defines it as a small core extended with TypeScript extensions, skills, prompt templates, themes, and Pi packages shareable via npm or Git. It also exposes four ways to use it: interactive interface, print or JSON output, RPC, and an SDK for embedding it in another application.

The origin: Mario Zechner’s deliberate minimalism

The package documentation links to Mario Zechner’s essay, “What if you don’t need MCP?”, and his “Pi Coding Agent” post from November 30, 2025. That material explains the founding tension: instead of piling into the CLI the features other agents ship by default, Pi keeps a small core and lets the user build or install whatever they need.

The stance is visible in what the project chooses not to include in the core: MCP, subagents, permission dialogs, planning mode, task lists, and background commands. That doesn’t mean those capabilities are impossible: the README lists explicit alternatives, such as extensions, external packages, tmux, TODO.md files, and containers. It’s an architecture and governance decision, not a claim that those features lack value.

Philosophy and principles

Minimal core, maximum extension. CONTRIBUTING.md warns that a feature that doesn’t belong in the core should be an extension, and that requests bloating it will likely be rejected.

A small glowing cube representing a minimal core, with neon lines branching out into floating modules.

Adapt the tool to the workflow. The official proposal is to adapt Pi to existing processes through TypeScript modules, skills, and packages, not to force the team into a predetermined sequence.
Operator responsibility. Pi doesn’t build in permissions to limit files, processes, network, or credentials: it runs with the permissions of the process that launches it. The documentation recommends a container, OpenShell, or the Gondolin extension when stronger limits are required.

A holographic terminal enclosed in a translucent neon container, with untrusted processes bouncing off the barrier.

Code and dependency review. The repository pins direct versions, uses --ignore-scripts on compatible installs, and checks the dependency lockfile; it also requires that contributors understand the code, even if they used AI to write it.

How it works

A futuristic command center with panels showing a file tree, code diffs, and bash output, with the read, write, edit, and bash tools active.

The CLI uses the current directory as the workspace and hands the model the read, write, edit, and bash tools; there are additional configurable read-only utilities. Providers authenticate with /login or an API key, and /model switches the model. Sessions are stored as JSONL in ~/.pi/agent/sessions/, with a message tree for resuming, forking, or cloning conversation branches.

A conversation tree branching out in a dark void, with glowing nodes representing JSONL sessions that can be forked and cloned.

Customization is organized by files and modules:

AGENTS.md, CLAUDE.md, and AGENTS.override.md provide context from the current directory and its ancestors.
~/.pi/agent/settings.json and .pi/settings.json store global and per-project configuration.
TypeScript extensions can register tools, commands, event handlers, and interface components; with them you can add MCP integration, permission gates, subagents, or Git checkpoints.
Skills follow the Agent Skills standard and can be installed as /skill:name or loaded automatically.

A floating holographic toolbox with icons of modular skills loading into a transparent terminal.

Pi packages distribute extensions, skills, instructions, and themes via npm or Git.

The project supports Claude, ChatGPT/Codex, and GitHub Copilot subscriptions, plus a wide list of API providers and llama.cpp. The v0.83.0 release added credential export with OAuth renewal, OpenRouter login completion over SSH, and Claude Opus 5 support through GitHub Copilot.

A glowing terminal cursor emitting beams of light toward holographic logos of Claude, ChatGPT, and GitHub Copilot.

Official and semi-official status

Pi is a project maintained by Earendil Inc., with an official site and documentation at pi.dev, an official npm package, and an official Discord community. No evidence was recovered that it is an official product of Anthropic, OpenAI, GitHub, or any marketplace run by those providers: subscriptions to those services are supported authentication options, not a product certification.

Its use as an extensible harness is visible in the related packages and projects listed by the documentation itself and in outside conversations, but no formal de facto standard designation was found. That open adoption should be distinguished from an endorsement by a model provider.

The ecosystem

Components and projects in the same scope

earendil-works/pi-chat: the root README links it for Slack automation, chat, and workflows.
Gondolin: an extension noted by the README to keep Pi and authentication on the host and send tools and ! commands to a local Linux micro-VM. A Hacker News comment attributes Gondolin to the same creator of Pi.
earendil-works/absurd: a related project mentioned in Hacker News comments as another development from the team; the comment describes it as minimalist and controllable, but that characterization is the author’s opinion, not independent proof.
badlogic/pi-share-hf and the badlogic/pi-mono set on Hugging Face: official channels linked by the README for publishing open coding sessions and gathering data on tasks, tools, failures, and fixes.

Community extensions and derivatives recovered

can1357/oh-my-pi appears linked by user theturtletalks as an alternative they were testing alongside Pi. The source isn’t enough to claim full compatibility or official maintenance.
gitsense/pi-brains was presented by sdesol as a routing and context extension for Pi. It’s a community project, not an Earendil component.
The thread “I Built a Telegram Client for Pi” credits at least one Telegram client extension published by atharva-again; the conversation didn’t allow reliably recovering its repository, so no name or metrics are invented.

The fork search was queried via the GitHub API, but the public quota was rejected during this run. Therefore no fork or translation list is offered as if it were exhaustive. No verifiable non-English translation was recovered either.

Repo numbers

Measured: August 5, 2026, public GitHub and npm pages.

Metric	Visible value
Stars	84.2k
Forks	10.4k
Commits	5,488
Branches	50
Tags	308
Visible open issues	65
Visible open pull requests	16
License	MIT
Latest release	`v0.83.0`, published the previous week
npm downloads, last week	1,613,282

GitHub showed the latest commit as 6b461b7, from badlogic, two hours before the query. The releases page places v0.83.0 as the most recent; the official announcement dates it July 29, 2026. The GitHub API returned a rate limit, so real subscribers, primary language, exact dates, and a contributor ranking could not be verified. The 65 issues and 16 pull requests are separate page counters, not the API’s aggregated open_issues_count field.

How to contribute

The process is intentionally selective. Issues and pull requests from new contributors are auto-closed, and maintainers review them daily. For future issues to be able to stay open, a maintainer response with lgtmi is required; for pull requests, lgtm.

A futuristic neon gate filtering a stream of code submissions; some green blocks pass the lgtm scan and others are deflected.

Before opening an approved pull request, the guide requires running:

npm run check
./test.sh

CHANGELOG.md should not be edited. Issues must use one of the two templates, be short, concrete, and written by the submitter; the guide warns that mass or repeatedly careless submissions can end in a block. The documented justification is protecting maintainer time against low-quality automated reports, not excluding reasoned contributions.

Quick usage guide

Installation and first launch

Node and npm are needed for the main path. The official documentation recommends:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent
cd /path/to/project
pi

--ignore-scripts disables dependency lifecycle scripts; Pi states it doesn’t need them for a normal npm install. On Linux and macOS there’s also curl -fsSL https://pi.dev/install.sh | sh. On startup, run /login and pick a subscription provider, or set a key, for example export ANTHROPIC_API_KEY=..., before launching pi.

On first launch Pi may ask whether you trust the project’s local resources. That decision controls whether .pi/settings.json, extensions, and local packages get loaded; it shouldn’t be approved without reviewing the repository.

Common workflows

Inspect and fix a project. Launch pi, type a task, and let it use read, write, edit, and bash. To request a specific check from within the session, use !npm run lint; !!npm run lint runs the command without feeding its output into the model’s context.
Review specific files. Use pi @README.md "Summarize this file" or pi @src/app.ts @src/app.test.ts "Review both". In the interactive editor, @ opens a fuzzy file search.

A dark terminal where the user types a fuzzy search with @ to select README.md and app.ts, with holographic highlights.

Resume or branch an investigation. pi -c continues the most recent session, pi -r lets you pick an earlier one, and pi --session <path|id> opens a specific one. Inside the interface, /tree, /fork, and /clone preserve history branches.
Automate a call. pi -p "Summarize this codebase" produces a one-off run; pi --mode json offers JSON events, and pi --mode rpc integrates an external process via JSONL over standard input and output.

Essential configuration

~/.pi/agent/settings.json: global options, including default project trust and telemetry.
.pi/settings.json: options that override the global ones in a trusted repository.
AGENTS.md or CLAUDE.md: project instructions Pi loads on startup; AGENTS.override.md replaces those from that folder.
~/.pi/agent/skills/ or .pi/skills/: local skills with SKILL.md.
~/.pi/agent/extensions/ or .pi/extensions/: TypeScript extensions for tools, events, and interface.

After modifying context resources, run /reload or restart Pi.

Common pitfalls and solutions

Unexpected permissions. Pi has no built-in permission dialogs and acts with the process’s privileges. For untrusted work, use Docker, OpenShell, or Gondolin; don’t assume the CLI isolates commands on its own.
Local resources not loading. If the project isn’t trusted, .pi configuration and extensions don’t activate. Review the code and approve with /trust, or adjust defaultProjectTrust per team policy.
Installing third-party packages. Extensions can run arbitrary code and skills can instruct dangerous actions. Review the code before pi install; for Git, pin a tag or commit, such as pi install git:github.com/user/repo@v1.
Auto-closed issue or pull request. Follow CONTRIBUTING.md, use a template, describe a brief reproduction, and wait for review; for urgent cases the guide points to Discord.
Session too long. Automatic compaction is active and deliberately lossy; the full history remains in JSONL. Use /compact and /tree to manage context and recover an earlier point.

Integrations and migration

Pi can integrate with applications via SDK or with another process via pi --mode rpc. To extend the CLI with MCP, subagents, approvals, or deployment tools, the documented path is a TypeScript extension; there’s no native MCP server. Packages are installed with pi install npm:@organization/package or from Git, and -l installs them locally in the project. Anyone coming from a CLI with built-in features must translate those expectations into extensions, skills, or packages, rather than looking for equivalent native flags.

How the community received it

The verifiable reception combines praise for the simplicity with objections about the project’s scope and discipline:

On Hacker News, thread 49176038, “Pi’s Minimalism Is Its Advantage,” had 509 points and 275 comments. User manoji said they were building an agent on top of the harness and praised its simplicity. That’s a personal experience, not a controlled comparison.
Thread 48804801, about a Telegram client for Pi, had 72 points and 44 comments. tough placed it “in spirit” alongside Claude Code, Codex, and OpenCode and noted it’s easy to extend; that assessment is a commenter’s opinion, not an endorsement of the projects cited.
In 48865001, 154 points and 143 comments, theturtletalks said they had replaced Codex CLI with Pi and were testing oh-my-pi. That’s a signal of individual usage and of a derivative, not proof of superiority.
There’s also operational criticism. In 48259192, with 196 points and 147 comments, the_mitsuhiko flagged a Pi issue that didn’t follow the template and called it low-quality generated analysis. That complaint fits the repository’s strict contribution policy, but doesn’t prove all reports are like that.

Direct queries to Reddit on r/programming, r/selfhosted, r/LocalLLaMA, r/devops, r/netsec, and r/MachineLearning were blocked by the site, so no threads or opinions from those communities are attributed. The Dev.to API did return a review by andrew-ooo and a Cloudflare article by harshil1712, but their conclusions weren’t used without retrieving the full texts. Product Hunt presented a verification page, and the X search didn’t allow retrieving a verifiable public conversation; the README does link two badlogic posts on X about sharing sessions and a demo video from that post.

Pi versus other approaches

Approach	Verifiable overlap	Documented difference
Claude Code	Both are terminal coding agents, and Pi allows login with a Claude subscription.	Pi doesn’t integrate permissions, subagents, or planning mode by default; its README proposes extensions or containers for those features.
Codex CLI	Both can be used as coding assistants; Pi accepts ChatGPT/Codex login.	Pi can use multiple providers and exposes packages, RPC, and an SDK; no benchmark was found to justify a quality comparison.
OpenCode	A Hacker News comment groups them as first-tier harnesses.	The only source recovered is that opinion; no equivalence of features or performance is claimed.
`can1357/oh-my-pi`	A community derivative or extension cited by a Hacker News user.	The recovered source doesn’t document its design or compatibility, so it should be evaluated separately before migrating.

Use cases and who this repository can help

Developers who want a CLI adaptable to several providers can use /login, /model, API keys, and llama.cpp to work from a single interface without switching harnesses for each provider.
Teams with repository conventions can declare checks and limits in AGENTS.md or CLAUDE.md, use global and project context, and resume saved sessions to preserve a task’s work.
People building developer tools can integrate the agent via SDK or RPC and create TypeScript extensions to register tools, UI, approvals, telemetry, subagents, or MCP connectors.
Organizations with isolation requirements can run Pi in Docker or OpenShell, or route tools to Gondolin, always understanding that isolation isn’t part of the CLI by default.
Maintainers who want to share reusable automations can distribute skills, templates, themes, and extensions as npm or Git packages, pinning references to reduce unexpected changes.

Resources

Repository: https://github.com/earendil-works/pi
Documentation and installation: https://pi.dev/docs/latest and https://pi.dev/docs/latest/quickstart
npm package: https://www.npmjs.com/package/@earendil-works/pi-coding-agent
Official news and changes: https://pi.dev/news and https://github.com/earendil-works/pi/releases
Contributing guide: https://github.com/earendil-works/pi/blob/main/CONTRIBUTING.md
Project RFCs: https://rfc.earendil.com/keyword/pi/
Discord community: https://discord.com/invite/3cU7Bz4UPx
Discussions and reviews: https://news.ycombinator.com/item?id=49176038, https://news.ycombinator.com/item?id=48804801, https://news.ycombinator.com/item?id=48865001, https://news.ycombinator.com/item?id=48259192, https://dev.to/andrew-ooo/pi-coding-agent-review-the-minimal-terminal-harness-5b46, https://dev.to/cloudflare/how-i-run-the-pi-coding-agent-on-cloudflare-ld5
Video and open sessions linked by the project: https://x.com/badlogicgames/status/2041151967695634619, https://github.com/badlogic/pi-share-hf, https://huggingface.co/datasets/badlogic/pi-mono

Note: this article combines the README and CONTRIBUTING.md retrieved from the repository, pi.dev documentation and news, public GitHub pages, the npm API, and Hacker News results consulted on August 5, 2026. Figures change over time; metrics the GitHub API didn’t deliver due to rate limiting have been flagged as such.