Pi Harness Architecture and Extension Boundaries

This case preserves the Pi version and observation dates recorded below. Read the harness overview for shared responsibilities; this page examines how one implementation distributes them.

Pi: A Programmable Minimal Harness

Pi describes itself as a minimal terminal coding harness. It keeps model calls, the agent loop, tool execution, branchable sessions, and the terminal interface in the core, then leaves workflow-specific behavior to composable resources. By default the model receives only read, write, edit, and bash. grep, find, and ls are also built-in tools, but must be selected explicitly or enabled by configuration.

Beyond the interactive TUI, Pi supports one-shot -p output, a JSON event stream, stdin/stdout RPC, and an SDK for embedding the agent in a Node.js application. Providers can be switched. Sessions are stored as branchable JSONL trees; /tree, /fork, /clone, and /compact cover in-file exploration, separate sessions, and context compression.

The Pi details below were checked on 2026-08-28 against the locally installed Pi 0.84.3 documentation. They are versioned product facts, not a permanent compatibility promise.

What Each Customization Layer Owns

Layer	Typical entry point	Good home for	Do not confuse it with
Project context	AGENTS.md, CLAUDE.md, .pi/SYSTEM.md	stable rules, path boundaries, acceptance commands	a plugin or sandbox
Prompt template	.pi/prompts/review.md → /review	a repeatable, parameterized starting prompt	an automatically executed workflow
Skill	.agents/skills/*/SKILL.md → /skill:name	on-demand procedures, scripts, and references	a permission boundary or separate process
Extension	.pi/extensions/*.ts	new tools, commands, event policy, UI, providers, and session behavior	an inherently safe “lightweight plugin”
Pi package	pi install ..., pi config	distribution of extensions, skills, prompts, and themes through npm, Git, or local paths	isolation or trusted signing
SDK / RPC	createAgentSession(), pi --mode rpc	embedding, tests, or cross-language process integration	a mandatory layer for ordinary repositories

Global resources normally live under ~/.pi/agent/; project resources live under .pi/ or .agents/skills/. A prompt expands text. A skill uses progressive disclosure, keeping only its name and description in default context. An extension changes harness behavior directly. Prefer a skill when the missing piece is a method, a prompt when it is reusable input, and an extension only when a new tool, event hook, or UI is actually required.

For Pi's verified request, Steering, Follow-up, compaction, and session flow, see Bounded Agent Loops. Session branches change the conversation seen by the model; they do not restore files on disk. The practical commands below remain here as an operator reference.

Extensions: Pi's Plugin Layer

An extension is a TypeScript module loaded directly by Pi. It can:

• register model-callable tools and user slash commands;
• hook model turns, tool calls and results, model changes, and session lifecycle events;
• block or rewrite dangerous calls and add protected paths or approval UI;
• customize compaction, session state, terminal components, and rendering;
• register providers, or implement MCP, subagents, plan mode, and sandbox integration.

The last item matters: examples or third-party packages can implement those capabilities, but they are not core defaults. A small core permits competing designs while making the installer responsible for their policy, maintenance, and recovery behavior.

Auto-discovered extensions go in ~/.pi/agent/extensions/ or a trusted project's .pi/extensions/; run /reload after changing them. Use pi -e ./extension.ts for a temporary experiment without installing it. A Pi package can distribute extensions, skills, prompts, and themes together:

pi install npm:@scope/package@1.2.3  # pin a version
pi install ./local-package -l        # project scope
pi list
pi config                            # enable or disable individual resources
pi update --extensions

Extensions execute arbitrary code with the current user's authority, and a skill may instruct the model to run bundled scripts. A package is therefore a distribution unit, not a security boundary. Read source and dependencies before installation, pin versions when useful, and enable only the resources the workflow needs.

Daily Use

An ordinary project does not need a large control plane on day one:

A small project may use only the files it needs:

• AGENTS.md for rules and acceptance commands;
• .pi/prompts/review.md for an optional short repeated prompt;
• .agents/skills/release/SKILL.md for an optional reusable procedure;
• .pi/extensions/policy.ts only when host-level policy requires code.

Common launch patterns:

cd my-project
pi --name "parser repair"             # interactive session
pi -c                                 # continue the latest session
pi --no-session -p "Summarize this repository"  # ephemeral one-shot

# Expose only read-only tools for a review
pi --no-session --tools read,grep,find,ls -p "Review the change"

# Skip discovery and load only the resource under test
pi --no-extensions -e ./.pi/extensions/policy.ts
pi --no-skills --skill ./.agents/skills/release/SKILL.md

The first interactive commands worth remembering are:

Command	Purpose
/model	switch the model
/name, /session	name the session and inspect its file, tokens, and cost
/tree	revisit a previous node and branch inside the same JSONL file
/fork, /clone	copy an earlier point or the active branch to a new session
/compact	lossy compression of old context; the full record remains in the session file
/reload	reload extensions, skills, prompts, themes, and context files
/skill:name, /template	load a skill explicitly or expand a prompt template

Safety Baseline

Pi's project trust decides whether project .pi settings, resources, and executable extensions are loaded. It is not a filesystem or network sandbox. Non-interactive modes do not show the built-in project-trust prompt, so automation must make an explicit --approve decision instead of permanently trusting arbitrary repositories by default.

A conservative starting point is:

1. inspect Git status, AGENTS.md, and the allowed write scope before trusting project resources;
2. use --tools read,grep,find,ls for review work, then widen the tool set only when writes are required;
3. run unfamiliar repositories or dangerous commands in a container or VM, leaving credentials, the Docker socket, and unrelated directories outside;
4. use --no-extensions, --no-skills, and related flags to construct a reproducible minimal resource set;
5. review and pin third-party packages, treating every extension as code with full user authority;
6. judge completion with tests, lint, diffs, and final process state rather than the model's claim that it is done.

This is Pi's central exchange with more productized harnesses: the core is smaller and more malleable, but safety policy and workflow quality do not appear automatically.

Pi and DeepSeek Harness: Who Carries the Complexity?

The Pi walkthrough and the DeepSeek Harness video describe systems that look similar at first. Both can switch models, connect tools, and add plugins. The more useful distinction is not feature count, but when complexity appears and who has to manage it.

Pi starts with a small core. If a user wants plan mode, subagents, MCP, or a specialized interface, they assemble that capability when it becomes useful. This keeps the default system understandable, but leaves compatibility, permissions, and maintenance with the user.

The DeepSeek Harness video starts from "Everything is a plugin." Models, tools, interfaces, and workflows share one composition surface. That can make repeated workflows easier to reuse across a team, while moving dependency, version, and debugging work into the plugin platform.

Neither approach removes complexity. Pi delays it and gives it to the person building the workflow; the design shown in the DeepSeek video concentrates more of it in the platform. For my current workflow, Pi should stay small. Only capabilities that recur and have already stabilized are worth turning into shared components. A unified plugin workbench becomes useful when those components are numerous enough to be difficult to maintain separately.

My reading · Opened notes are remembered in this browser.