Building Pi: A Minimal, Extensible Coding Agent Framework

pi · Tech · 2026 · source Agentic: yes · promotional bias: low · source-backed · extracted with prompt 0.5.5 (schema v2)

Generated from extraction.json — do not edit by hand. Every claim cites verbatim source evidence; stated means the quote directly asserts the claim, implied means it supports it indirectly.

Problem

Domain: Extensible coding-agent frameworks

Pi addresses the problem that many coding-agent harnesses became opaque, feature-heavy, difficult to extend, weak at context management, and tied to specific providers or workflows. The project tests whether a minimal agent core with strong extensibility, model choice, observability, and user-controlled workflow primitives can perform competitively without copying every built-in feature from commercial coding agents.

Constraints:

• Developers need visibility into what the agent is doing instead of hidden behavior or UI simplification that obscures context and tool use.
• Context-management choices must preserve prompt-cache economics and avoid injecting misleading intermediate errors.
• The framework must support model choice, custom providers, custom tools, and project-specific extensions without requiring a fork.
• Security and approval should not rely on users repeatedly clicking through prompts they will stop reading.
• The system needs to be small enough to experiment with, but still usable as a TUI, SDK, and headless backend.

Architecture

Pi is built as a minimal, extensible coding-agent framework. Its core consists of an AI package for multiple providers and transports, an agent core with a generalized agent loop, tool invocations and verification, a small terminal UI, and the coding agent itself as both SDK and TUI. The built-in tool surface is intentionally limited to read, write, edit, and bash. Everything else is pushed into TypeScript extensions that hot-reload: custom tools, UI, skills, prompt templates, themes, providers, permission gates, compaction strategies, and overrides for the built-in file/bash tools. Pi keeps sessions as trees, exposes cost tracking and export/streaming paths, and relies on external primitives such as tmux, markdown files, CLI tools, and containerization rather than baking in sub-agents, plan loading, MCP, background bash, or approval prompts.

Diagram confidence: reconstructed (reconstructed from prose).

flowchart LR
  ai-provider-package["AI provider package"] --> agent-core["Agent core"]
  agent-core --> built-in-tool-set["Built-in tool set"]
  agent-core --> typescript-extension-loader["TypeScript extension loader"]
  typescript-extension-loader --> custom-tools["Custom tools"]
  typescript-extension-loader --> custom-ui["Custom UI"]
  typescript-extension-loader --> custom-providers["Custom providers"]
  custom-providers --> ai-provider-package
  typescript-extension-loader --> permission-gate-extensions["Permission gate extensions"]
  typescript-extension-loader --> tool-override-extensions["Tool override extensions"]
  tool-override-extensions --> built-in-tool-set
  typescript-extension-loader --> custom-compaction["Custom compaction"]
  custom-compaction --> session-tree["Session tree"]
  agent-core --> session-tree
  agent-core --> terminal-ui["Terminal UI"]
  agent-core --> headless-sdk["Headless SDK"]
  terminal-ui --> export-and-streaming["Export and streaming"]
  headless-sdk --> export-and-streaming
  terminalbench["TerminalBench"] --> headless-sdk
  oss-access-gate["OSS access gate"]

Components

Data flow

A user runs Pi as a TUI or SDK. The coding agent sends conversation state into the agent core, which calls the AI provider abstraction and invokes the small built-in tool set or any loaded TypeScript extensions. Extensions can override file and shell operations, add custom tools/UI/providers, implement compaction or permission gates, and hot-reload while the agent is running. Session state is held as a tree so the user can branch, summarize, return to the root, and preserve observability. Outputs can be inspected through the TUI, exported as HTML/JSON, streamed headlessly, or evaluated through external harnesses such as TerminalBench.

Why this architecture

Pi chooses a small core because the speaker believes the industry has not yet converged on the right coding-agent architecture and needs a malleable substrate for experimentation. TerminalBench's Terminus result is used as evidence that a minimal interface can perform strongly, so Pi avoids hardcoding MCP, sub-agents, plan loading, background bash, to-do lists, LSP feedback, and approval gates. Instead it exposes extension points so developers can implement those features when they fit a workflow, while preserving observability, model choice, and control.

Models used: Claude Opus 4.5 · Anthropic Claude models · Codex · Frontier models · Custom providers · Self-hosted models

Scale

• The talk dates the practical coding-agent inflection to early 2025.
  “back in 2025, I think somewhere around April.”transcript, stated
• The speaker has 17 years of open-source experience.
  “I've been in open source for well uh 17 years.”transcript, stated
• OpenCode's compaction pruned tool results before the last 40,000 tokens.
  “It prunes all tool results um before the last 40,000 tokens.”transcript, stated
• The criticized React terminal re-layout path took about 12 milliseconds per update.
  “it takes like 12 milliseconds to re-layout your entire user interface graph.”transcript, stated
• Terminals can render hundreds of frames per second in the speaker's framing.
  “Terminals can render it like a hundreds of frames per second”transcript, stated
• TerminalBench had about 82 computer-use and coding tasks.
  “It has a bunch of computer use and coding related tasks that an agent or the LLM inside an agent harness um needs to uh fulfill. I think it's about 20 uh 82 or so.”transcript, stated
• Pi's TUI is described as about 600 lines of code.
  “a terminal user interface that's like 600 lines of code.”transcript, stated
• Pi has four packages and four built-in tools.
  “It comes with four packages”transcript, stated

  “It only has four tools, read a file, write a file, edit a file, and bash.”transcript, stated
• Permission gates can be implemented in about 50 lines of code.
  “permission gates, you can easily implement them in 50 lines of code”transcript, stated
• The speaker says an SSH-backed override of read/write/edit/bash took five minutes to implement.
  “I have a version of read, write, edit, and bash that works through SSH on a remote machine. For me, that took 5 minutes to implement.”transcript, stated

Alternatives considered (roads not taken)

Feature-rich coding-agent spaceships.

Rejected because: The speaker argues that hidden feature bloat makes it hard to know what the agent is doing and destabilizes developer workflows.

Hardcoded context pruning before the last 40,000 tokens.

Rejected because: Pi favors extensible/custom compaction because the OpenCode pruning approach destroys prompt-cache behavior.

Injecting LSP errors after every individual edit.

Rejected because: The speaker says intermediate compile errors are often expected during a multi-edit task and mislead the model before the natural synchronization point.

Approval dialogs as the primary safety mechanism.

Rejected because: Pi defaults to YOLO because approval prompts create fatigue and become ineffective if users stop reading them.

Built-in MCP, sub-agents, plan loading, background bash, and to-do lists.

Rejected because: Pi treats these as workflow choices that can be handled with CLI tools, extensions, tmux, markdown files, or custom implementations.

Single-provider, single-model agent coupling.

Rejected because: Pi's provider abstraction lets developers switch between providers and register custom proxies or self-hosted models.

Patterns

tool-use-orchestration (agent_architecture)

Pi keeps the built-in tool interface to read, write, edit, and bash while letting developers add or override tools through extensions.

model-routing (model_selection)

The AI package abstracts providers so users can switch models/providers inside a session and register proxies or self-hosted models.

context-compaction (context_management)

Pi leaves compaction to extension code so developers can experiment instead of accepting hardcoded pruning that damages prompt caching.

observability-tracing (operations)

Pi exposes tree-structured sessions, cost tracking, exports, headless streams, and visible sub-agent alternatives instead of hiding agent operations.

cost-aware-routing (operations)

Pi treats prompt-cache preservation, model/provider choice, and full cost tracking as part of making coding-agent operation economically visible.

eval-driven-development (evaluation)

Pi uses TerminalBench to validate the minimalist design against other agent/model combinations.

safety-policy-enforcement (security)

Pi rejects approval dialogs as the default safety model and points users toward stronger isolation such as containerization or custom permission gates.

human-in-the-loop-gate (governance)

The open-source contribution workflow requires a human-written issue and allowlist entry before PRs are accepted.

Tradeoffs

Build a minimal extensible core.

Chose A small core plus extension points over A feature-rich all-in-one coding-agent harness.

Rationale: The speaker believes the industry is still experimenting, so the framework should be malleable rather than prescriptive.

Use only four built-in tools.

Chose read/write/edit/bash over A broad built-in tool and feature surface.

Rationale: TerminalBench and Terminus suggest very small interfaces can still perform strongly, so Pi keeps default tools minimal.

Make model choice part of the core provider abstraction.

Chose Provider/model agnosticism over Tight coupling to one model vendor.

Rationale: Developers can switch providers within a session and add proxies or self-hosted models without waiting on the framework author.

Prefer tmux and external artifacts for workflow primitives.

Chose tmux, markdown plans, CLI tools, and extensions over Built-in sub-agents, plan loaders, background bash, and to-do lists.

Rationale: The speaker sees these as observable, reusable, and already-good primitives rather than core features the framework should own.

Default to YOLO mode rather than approval prompts.

Chose Fast execution with isolation/custom gates over Mandatory per-action approval dialogs.

Rationale: The speaker believes approval dialogs produce fatigue and weak security behavior, while isolation and custom gates are better foundations.

Keep the terminal UI small and non-React-like.

Chose A roughly 600-line TUI over A complex terminal UI described as a game engine.

Rationale: The speaker argues terminal UI complexity caused flicker and performance issues in other tools, while a simpler TUI can render smoothly.

Restrict open-source contributions through human verification.

Chose Allowlisted human contributors after a human-written issue over Open PR intake from any coding-agent user.

Rationale: The maintainer found coding-agent spam costly enough to add gatekeeping despite the contribution friction.

Gotchas (what bit them)

Feature bloat can make an agent harness opaque and unstable for power users.

Root cause: Commercial tools can add many hidden features and behavior changes while trying to serve a large user base.

Resolution: Pi strips the core down and lets developers add the workflow-specific parts themselves.

Naive session compaction can destroy prompt-cache economics.

Root cause: Pruning historical tool results before a fixed token boundary rewrites the prompt structure and loses cache hits.

Resolution: Pi exposes custom compaction as an extension point rather than hardcoding a pruning policy.

Continuous LSP feedback can punish correct multi-step edits.

Root cause: A file often does not compile after the first edit in a sequence, but injecting that temporary error as model feedback can make the model abandon the plan.

Resolution: Run linting/type checking at natural synchronization points when the agent thinks it is done.

Approval gates can become security theater.

Root cause: Users either disable prompts or approve them without reading once the workflow becomes repetitive.

Resolution: Use stronger isolation as the base security boundary and make permission gates optional extensions when a team wants them.

Open-source projects can be overwhelmed by low-quality AI-generated contributions.

Root cause: Coding-agent users can mass-submit issues and PRs that look generated and waste maintainer time.

Resolution: Pi uses OSS vacation periods and a human-verification allowlist before accepting PRs.

A built-in server architecture introduced a remote-code-execution concern in another harness.

Root cause: The speaker claims OpenCode exposed a server/client architecture without sufficient security maturity.

Resolution: Pi's design emphasizes explicit control and avoids assuming every architectural convenience should be in the core.

Evaluation

Pi is evaluated with TerminalBench, which compares agent harness and model combinations across computer-use and coding tasks. The speaker also uses architectural critiques as qualitative evaluation criteria: context-cache behavior, LSP feedback quality, UI performance, model choice, extensibility, cost tracking, and observability.

Metrics: TerminalBench leaderboard rank · Approximately 82 TerminalBench tasks · Claude Opus 4.5 model pairing · Whether compaction preserves prompt caching · Terminal UI responsiveness · Cost tracking availability · Extension implementation time · Observability of sub-agent workflows

Outcomes

• Pi demonstrates a minimal coding-agent architecture with four built-in tools and extension-based customization.
• Pi ranked behind Terminus on TerminalBench with Claude Opus 4.5, according to the presentation.
• The framework supports hot-reloaded TypeScript extensions for tools, UI, providers, permission gates, compaction, and built-in tool overrides.
• The speaker reports implementing SSH-backed read/write/edit/bash overrides in about five minutes.
• Pi's open-source governance pattern inspired a more general project called Vouch.

The presentation gives several concrete dimensions: four packages, four built-in tools, an approximately 600-line TUI, about 82 TerminalBench tasks, a second-place-like TerminalBench placement behind Terminus 2 with Claude Opus 4.5, permission gates in about 50 lines, SSH tool overrides in five minutes, and 17 years of open-source maintainer experience behind the governance choices.