Skip to content
/
Tier A A8 Cross-runtime harness

pi (badlogic/earendil)

pi-coding-agent · badlogic/pi-mono · ★ 55k · last commit 2026-05-26

Primitive shape 1 total
Skills 1
00

Summary

Pi Coding Agent — Summary

Pi (by badlogic/earendil-works) is a minimal yet extensible terminal coding harness built in TypeScript/Tauri-style (pure Node.js/CLI, not Electron) that ships four default tools (read, write, edit, bash), is designed around extensibility via TypeScript Extensions and Markdown Skills, and runs in four modes: interactive, print/JSON, RPC (for process integration), and SDK (for embedding). Its philosophy is "adapt pi to your workflows, not the other way around" — it deliberately skips subagents and plan mode, instead letting users or packages add those capabilities. Pi ships a unified multi-provider LLM API (packages/ai) supporting OpenAI, Anthropic, Google Gemini, DeepSeek, Groq, Amazon Bedrock, and more. The monorepo includes a Textual-style TUI library (packages/tui) with differential rendering and session branching/compaction. The .pi/ directory houses project-specific Skills, Prompt Templates, Extensions, and Git integration helpers.

Compared to seeds: architecturally closest to spec-driver (skills-only behavioral framework) in component pattern, but pi is a full standalone binary rather than a Claude Code plugin. The key delta: pi's extensibility model (TypeScript Extensions as npm packages) enables a community ecosystem analogous to Claude Code's plugin system, but independent of any specific IDE.

01

Overview

Pi Coding Agent — Overview

Origin

Created by Mario Zechner (badlogic / badlogicgames). Repository: badlogic/pi-mono. MIT license. ~55,166 GitHub stars (the pi-mono monorepo, actively maintained as of 2026-05-26). The primary package is @earendil-works/pi-coding-agent.

Philosophy

From README:

"Pi is a minimal terminal coding harness. Adapt pi to your workflows, not the other way around, without having to fork and modify pi internals. Extend it with TypeScript Extensions, Skills, Prompt Templates, and Themes."

"Pi ships with powerful defaults but skips features like sub agents and plan mode. Instead, you can ask pi to build what you want or install a third party pi package that matches your workflow."

Key values:

  • Minimal defaults: 4 tools (read, write, edit, bash); nothing else baked in
  • Extensibility without forking: TypeScript Extensions as npm packages
  • Supply-chain hardening: pinned dependencies, shrinkwrap, pre-commit lockfile guards
  • Session data sharing: pi-share-hf for publishing coding sessions to Hugging Face (training data)
  • Multi-provider unified LLM API: packages/ai is a standalone library for any provider

Manifesto-style quote (from coding-agent README)

"Pi ships with powerful defaults but skips features like sub agents and plan mode. Instead, you can ask pi to build what you want or install a third party pi package that matches your workflow."

Distribution

  • npm install -g --ignore-scripts @earendil-works/pi-coding-agent
  • curl -fsSL https://pi.dev/install.sh | sh (first-party installer)
  • Binary: pi

Supply-Chain Hardening (unique in batch)

The README describes explicit supply-chain security measures:

  • Direct deps pinned to exact versions
  • .npmrc with save-exact=true and min-release-age=2
  • package-lock.json as ground truth
  • npm-shrinkwrap.json in CLI package
  • Pre-commit blocks lockfile changes without PI_ALLOW_LOCKFILE_CHANGE=1
  • Release smoke tests in isolated environments
02

Architecture

Pi Coding Agent — Architecture

Distribution & Install

  • npm install -g --ignore-scripts @earendil-works/pi-coding-agent
  • curl -fsSL https://pi.dev/install.sh | sh
  • Binary: pi

Required Runtime

  • Node.js (version not specified; LTS recommended)
  • TypeScript (compiled; not needed at runtime)
  • Build: npm install --ignore-scripts && npm run build

Monorepo Structure

badlogic/pi-mono/
├── packages/
│   ├── coding-agent/     # @earendil-works/pi-coding-agent — the CLI
│   │   ├── src/
│   │   │   ├── core/
│   │   │   │   ├── system-prompt.ts     # System prompt builder
│   │   │   │   ├── agent-session.ts     # Session management
│   │   │   │   ├── compaction/          # Context compaction logic
│   │   │   │   ├── extensions/          # Extension loading
│   │   │   │   └── model-resolver.ts    # Multi-provider model routing
│   │   │   ├── cli/                     # Interactive CLI modes
│   │   │   └── modes/                   # interactive, print, rpc, sdk
│   │   └── npm-shrinkwrap.json
│   ├── agent/            # @earendil-works/pi-agent-core — runtime + tool calling
│   ├── ai/               # @earendil-works/pi-ai — unified multi-provider LLM API
│   │   └── src/providers/ # OpenAI, Anthropic, Google, Bedrock, Mistral, Groq, DeepSeek...
│   └── tui/              # @earendil-works/pi-tui — TUI library
├── .pi/
│   ├── skills/           # Project-specific skills
│   │   └── add-llm-provider.md
│   ├── prompts/          # Prompt templates
│   │   ├── cl.md         # changelog audit
│   │   ├── is.md
│   │   ├── pr.md
│   │   └── wr.md
│   ├── extensions/       # TypeScript extensions
│   ├── git/              # Git integration helpers
│   └── npm/              # npm integration helpers
├── AGENTS.md             # Project-specific agent instructions
└── CONTRIBUTING.md

Four Execution Modes

Mode Trigger Use case
Interactive pi Terminal conversation loop
Print / JSON pi --print or pi --json Script-friendly single-shot output
RPC pi --rpc Process integration (parent process communicates via stdin/stdout)
SDK Import @earendil-works/pi-coding-agent Embed in custom applications

Built-in Tools (4)

read, write, edit, bash — these are the only tools by default.

LLM Providers (via packages/ai)

Anthropic Claude Pro/Max, OpenAI ChatGPT Plus/Pro (Codex), GitHub Copilot (subscription); plus API keys for Anthropic, OpenAI, Azure OpenAI, DeepSeek, Google Gemini, Google Vertex, Amazon Bedrock, Mistral, Groq, and custom OpenAI-compatible endpoints.

03

Components

Pi Coding Agent — Components

Skills (.pi/skills/ — project-specific)

Skill Purpose
add-llm-provider.md Checklist for adding a new LLM provider to packages/ai

Skills are Markdown files with YAML front-matter (name, description) that appear as available capabilities in the system prompt. Users can add project-specific or global skills.

Prompt Templates (.pi/prompts/ — project-specific)

Template Purpose
cl.md Changelog audit: check all commits since last release have entries
is.md (purpose not fetched in detail)
pr.md (purpose not fetched in detail)
wr.md (purpose not fetched in detail)

Prompt templates are invoked as /cl, /is, /pr, /wr slash-commands in the interactive session.

Packages

Package Purpose
@earendil-works/pi-coding-agent CLI binary (pi); the user-facing agent
@earendil-works/pi-agent-core Agent runtime with tool calling and state management
@earendil-works/pi-ai Unified multi-provider LLM API (standalone, reusable library)
@earendil-works/pi-tui Terminal UI library with differential rendering

Extensions (TypeScript)

TypeScript Extensions are npm-installable packages that add custom tools, hooks, or behaviors. They run in the same Node.js process as pi. The packages/coding-agent/src/core/extensions/ directory handles extension loading.

Core System Prompt Builder

src/core/system-prompt.ts constructs the system prompt from:

  • Available tools list (with one-line snippets)
  • Guidelines (tool-availability-dependent)
  • appendSystemPrompt (additional custom content)
  • Context files (PI.md or project-specific markdown files)
  • Skills (formatted from loaded .pi/skills/)
  • Date + working directory

Session Features

  • Branching: create divergent session paths from any point
  • Compaction: context compaction when approaching limits (src/core/compaction/)
  • Model switching: /model command (Ctrl+L) to switch provider/model mid-session
05

Prompts

Pi Coding Agent — Prompts

System Prompt Construction (verbatim from src/core/system-prompt.ts)

The default system prompt is constructed dynamically:

let prompt = `You are an expert coding assistant operating inside pi, a coding agent harness. You help users by reading files, executing commands, editing code, and writing new files.

Available tools:
${toolsList}

In addition to the tools above, you may have access to other custom tools depending on the project.

Guidelines:
${guidelines}

Pi documentation (read only when the user asks about pi itself, its SDK, extensions, themes, skills, or TUI):
- Main documentation: ${readmePath}
- Additional docs: ${docsPath}
- Examples: ${examplesPath} (extensions, custom tools, SDK)
- When reading pi docs or examples, resolve docs/... under Additional docs and examples/... under Examples
- When asked about: extensions (docs/extensions.md, examples/extensions/), themes (docs/themes.md), skills (docs/skills.md), ...`;

Followed by: context files, skills, and Current date: ... Current working directory: ...

Prompting technique: Conditional guidelines (tool-specific guidelines are added based on which tools are actually available), documentation-routing instruction (agent reads pi docs only when asked about pi itself), and explicit working directory + date injection.

Verbatim Excerpt 2: cl.md Prompt Template (changelog audit)

File: .pi/prompts/cl.md (partial)

---
description: Audit changelog entries before release
---
Audit changelog entries for all commits since the last release.

## Process

1. **Find the last release tag:**
   ```bash
   git tag --sort=-version:refname | head -1
  1. For each commit, check:
    • Skip: changelog updates, doc-only changes, release housekeeping
    • Skip: changes to generated model catalogs unless accompanied by an intentional product-facing change
    • Verify a changelog entry exists in the affected package(s)
    • For external contributions (PRs), verify format: Description ([#N](url) by [@user](url)) ...
  2. Report:
    • List commits with missing entries
    • Add any missing entries directly

**Prompting technique**: Process checklist with explicit skip rules and cross-package duplication rules. The template encodes institutional knowledge about what changes need changelog entries and what don't — a pattern that would otherwise require tribal knowledge.

## Skill Format (`.pi/skills/`)

Skills use identical format to Codex CLI skills: YAML front-matter (`name`, `description`) + Markdown body.
09

Uniqueness

Pi Coding Agent — Uniqueness & Positioning

Differs from Seeds

Pi is architecturally closest to spec-driver (skills-only behavioral framework with project-level context files) but is a fully standalone binary rather than a Claude Code plugin. The key deltas from all seeds: (1) four execution modes including RPC (process integration) — no seed supports being driven as a subprocess via stdin/stdout JSON; (2) session branching — no seed supports creating divergent conversation threads from a shared history; (3) TypeScript Extensions as npm packages — extensibility without forking the tool; (4) unified multi-provider LLM API (packages/ai) as a reusable standalone library — the most comprehensive multi-provider LLM abstraction in the batch; (5) supply-chain hardening with exact dependency pinning and shrinkwrap — no seed framework documents explicit supply-chain security measures; (6) session data sharing to Hugging Face for LLM training contribution — unique in the corpus.

Positioning

A "polished minimal" coding agent — more capable than micro-agent/mini-swe-agent but deliberately less complex than RA.Aid or Codex CLI. Designed for developers who want a hackable, multi-provider terminal agent that adapts to their workflow without IDE dependency.

Key Differentiators

  1. RPC mode: can be driven as a subprocess by external orchestrators
  2. Session branching: divergent conversation threads from shared history
  3. TypeScript Extensions as npm packages: ecosystem extensibility
  4. packages/ai as standalone library: most complete multi-provider LLM abstraction
  5. Supply-chain hardening: documented, explicit security measures unique in batch
  6. Session data sharing: pi-share-hf for contributing to LLM training datasets
  7. Skips subagents and plan mode by design: avoids scope creep

Observable Failure Modes

  • No sandboxing: all commands run in user's live environment
  • Documentation routing: system prompt instructs agent to only read pi docs when asked about pi — but agents may sometimes read them unnecessarily
  • Extension isolation: TypeScript extensions run in the same process — a misbehaving extension can affect all sessions
  • No TDD enforcement: unlike micro-agent, no test-first guardrails
04

Workflow

Pi Coding Agent — Workflow

Primary Workflow (Interactive)

pi
  → Load context files (PI.md, AGENTS.md, .pi/skills/, .pi/prompts/)
  → Build system prompt (tools, guidelines, context, skills, date)
  → Start interactive TUI session
  → User types message or /command
  → Agent uses read/write/edit/bash tools
  → Continue until user exits

Prompt Template Invocation

/cl    → Load cl.md template, inject into conversation
/pr    → Load pr.md template, inject into conversation

Session Branching

[during session]
  → user branches at any point
  → creates a new session thread
  → both threads retain history up to branch point

Phases & Artifacts

Phase Action Artifact
Session start Load context files + build system prompt System prompt
Tool use read/write/edit/bash tool calls File changes, shell output
Compaction Context size check → auto-compact if needed Compacted context
Session end Save session to disk Session file (for branching/resume)

Approval Gates

Tool calls require user confirmation in interactive mode (standard per the agent harness model). No documented hard gates for specific operations — behavior is governed by the model's judgment and system prompt guidelines.

Pi Packages (Ecosystem)

Users can install community pi packages from npm or git:

pi install <package-name>

Pi packages can add new skills, prompt templates, extensions, and themes without modifying pi internals.

06

Memory Context

Pi Coding Agent — Memory & Context

Session-Level Memory

  • Sessions: conversations are saved to disk and can be resumed
  • Branching: sessions can be branched at any point, creating parallel conversation threads
  • Compaction: src/core/compaction/ handles context compaction when approaching model limits
  • Session files: stored in pi's data directory (exact format not fully documented in public source)

Context Files

The system prompt builder reads:

  1. Project-specific markdown context files (like PI.md or project AGENTS.md)
  2. .pi/skills/ files (formatted as a skills section in the system prompt)
  3. appendSystemPrompt from configuration

From system-prompt.ts:

if (contextFiles.length > 0) {
  prompt += "\n\n<project_context>\n\n";
  prompt += "Project-specific instructions and guidelines:\n\n";
  for (const { path: filePath, content } of contextFiles) {
    prompt += `<project_instructions path="${filePath}">\n${content}\n</project_instructions>\n\n`;
  }
  prompt += "</project_context>\n";
}

Skills in Context

Skills are injected into the system prompt (if read tool is available):

if (hasRead && skills.length > 0) {
  prompt += formatSkillsForPrompt(skills);
}

Global vs. Project Memory

  • Global context files: ~/.pi/ (exact structure not documented)
  • Project context files: .pi/ in project root

Cross-Session Handoff

Yes — session files persist across sessions; branching preserves full history.

07

Orchestration

Pi Coding Agent — Orchestration

Multi-Agent

No — pi explicitly skips subagents and plan mode by design. From README:

"Pi ships with powerful defaults but skips features like sub agents and plan mode."

However, extensions can add these capabilities.

Orchestration Pattern

Sequential interactive loop.

Execution Mode

Interactive loop (primary) + one-shot (print/JSON mode) + event-driven (RPC mode for process integration).

Isolation Mechanism

None built-in — tool calls execute in the user's live environment.

Multi-Model

Yes — full multi-provider support via packages/ai. Users can switch models mid-session with /model (Ctrl+L). The model-resolver.ts handles per-provider default model assignments. The unified packages/ai library abstracts across all providers.

Model switching per-session is supported; per-role routing is not baked in (but Extensions could implement it).

Context Compaction

Yes — src/core/compaction/ directory implements context compaction when approaching limits.

Session Branching

Users can branch a session at any point, creating two parallel conversation threads from the same history. This is unique in the batch — no other framework explicitly supports session branching.

RPC Mode (process integration)

Pi can be run as a subprocess with communication via stdin/stdout JSON, enabling it to be driven by external orchestrators (the openclaw project uses this pattern).

08

Ui Cli Surface

Pi Coding Agent — UI & CLI Surface

Dedicated CLI Binary

  • Binary name: pi
  • Not a thin wrapper: full TypeScript agent runtime
  • Install: npm install -g --ignore-scripts @earendil-works/pi-coding-agent or curl installer

Terminal UI (TUI)

  • Type: terminal-tui
  • Stack: Custom TUI library @earendil-works/pi-tui with differential rendering
  • Features:
    • Interactive conversation with streaming
    • Session branching
    • Model switching (Ctrl+L or /model)
    • Keybindings management (configurable via ~/.pi/keybindings.json)
    • Theme support

CLI Modes

Mode Invocation Use case
Interactive pi Full TUI session
Print pi --print "prompt" Single-shot text output
JSON pi --json "prompt" Machine-readable output
RPC pi --rpc Process integration via stdin/stdout

Slash Commands (in interactive mode)

  • /model — switch provider/model
  • /login — authenticate with provider
  • /<prompt-name> — invoke a prompt template (e.g., /cl, /pr)
  • Skill invocation: skills appear in the system prompt context and are activated by the model

Programmatic SDK

import { createAgent } from '@earendil-works/pi-coding-agent';
// Embed pi capabilities in custom applications

Used by openclaw/openclaw as a real-world SDK integration example.

Session Data Sharing

badlogic/pi-share-hf tool for publishing completed coding sessions to Hugging Face datasets. Designed to contribute to open-source LLM training data.

Related frameworks

same archetype · same primary tool · same memory type

claude-mem (thedotmack) ★ 78k
A8 Cross-runtime harness

Background worker service captures every tool call as an observation, AI-compresses sessions, and auto-injects relevant past…

Agent Skills (Addy Osmani) ★ 46k
A8 Cross-runtime harness

Encodes senior-engineer software development lifecycle as 23 auto-routed skills and 7 slash commands for any AI coding agent.

wshobson/agents Plugin Marketplace ★ 36k
A8 Cross-runtime harness

Single Markdown source for 83 domain-specialized plugins that auto-generates idiomatic artifacts for five AI coding harnesses.

TabbyML/Tabby ★ 34k
A8 Cross-runtime harness

Self-hosted AI coding assistant server (alternative to GitHub Copilot) with admin dashboard, RAG-based completions, and multi-IDE…

Compound Engineering ★ 17k
A8 Cross-runtime harness

Make each unit of engineering work compound into easier future work via brainstorm→plan→execute→review→learn cycles.

Qodo (PR-Agent) ★ 11k
A8 Cross-runtime harness

Open-source AI PR reviewer with single-call tool architecture, PR compression for large diffs, self-reflection quality gate, and…