Chapter 1 · What Is Pi: The Minimal Terminal Coding Agent

Chapter goals: Understand pi's "harness" design philosophy and four run modes; clearly articulate its essential differences from IDE-built-in agents and heavy Agent frameworks; build a panoramic认知 of the five extension points.

1.1 What "Harness" Means in Coding Agents

In the context of AI coding tools, harness refers to "that layer of tack put around the model": it connects the model to tools (read/write files, execute commands), manages conversation context and session persistence, then hands控制权 back to the model. The harness本身 does not prescribe a workflow; it only provides a reliable execution底座.

pi's design philosophy is minimal core + on-demand扩展:

• The core默认 only gives the model 4 tools: read (read files), write (write files), edit (patch edits), bash (execute commands) — the model combines these to compose almost any capability;
• A group of read-only tools (grep, find, ls) can be enabled via tool options;
• "Heavy features" like sub-agents and plan mode are deliberately not built into the core — when needed, let pi help you write an extension, or install a third-party pi包.

This forms a stark contrast with many "全家桶"-style tools: those decide the workflow for you; the more features the messier the menu; pi主张 let pi适配 your workflow, not the other way around.

1.2 Four Run Modes

Mode	Launch	Scenario
Interactive (TUI)	pi	Daily human-machine pair programming
Print mode	pi -p "prompt"	One-shot tasks, shell pipelines
JSON mode	pi --mode json	Programmatic event stream parsing
RPC mode	pi --mode rpc	Integrated and driven by other processes
SDK	Import in a Node app	Embed pi into your own products

# Interactive mode: launch directly in the current project directory
cd /path/to/project
pi

# Print mode: one-shot question; output then exit
pi -p "Summarize this repo's directory structure"

# Pipe input also supported
cat README.md | pi -p "Summarize this doc in three sentences"

The same model config, session storage, and extension体系贯穿四种模式 — the provider config you调好 in interactive mode同样生效 in script modes. Later chapters delve逐一深入: Chapter 4 covers interactive mode; Chapter 5 covers sessions; Chapters 14–16 cover SDK/RPC/JSON and automation.

1.3 Comparison with IDE-Built-in Agents and Heavy Frameworks

vs IDE Built-in Agents (e.g. VS Code Copilot Chat)

• IDE agents深绑图形界面与厂商托管服务; pi is a纯 terminal program; works equally well SSH'd to a remote server;
• IDE agents have有限行为定制空间; pi's editor, keybindings, system prompt, and toolset全部可替换 or extensible.

vs Heavy Agent Frameworks (LangGraph/CrewAI etc.)

• Those frameworks解决 "how to orchestrate multiple LLM calls"; you搭建 your own session persistence, context compaction, UI;
• pi直接给你一个生产可用的 terminal agent,同时暴露 SDK/RPC for you to programmatically接管 —相当于 "orchestration framework + finished client"二合一.

One-sentence定位

pi = a minimal-core terminal coding agent + TypeScript extension system + embeddable SDK. It is both a daily tool and the foundational地基 for building your own agent product.

1.4 Five Extension Points Panorama

pi's customizability is composed of five层次, complexity ascending:

1. Prompt Templates: Markdown files defining reusable prompts; expand注入 via /templateName;
2. Skills: metadata-tagged skill packs (SKILL.md); discovered and loaded on-demand by the model; explicitly called via /skill:name;
3. Extensions: TypeScript programs;可 register custom slash commands, custom tools, replace the editor UI, intercept events;
4. Themes: Terminal color schemes;
5. Pi Packages: Bundle以上 resources into npm/git packages for distribution and安装.

Low customization cost ◄──────────────────────────────► High customization power
 [Prompt Templates] → [Skills] → [Themes] → [Extensions] → [Pi Packages]
   prompt reuse        capability inject   skin swap    behavior编程       package分享

This tutorial unfolds chapter by chapter in this order (Chapters 8–13). Core心法: use a template if one solves it; use a skill if one solves it; don't写 an extension unless necessary.

1.5 Suitable and Unsuitable Scenarios

适合用 pi:

• Developers whose primary workspace is the terminal, especially working inside remote servers / containers;
• Teams wanting precise control over what the agent can do (tool allowlists, project trust机制);
• Teams wanting to embed coding agents into their own products (SDK/RPC);
• Heavy users sensitive to subscription accounts, wanting to freely切换 dozens of model providers.

不太适合:

• Users with zero命令行 experience who just want to click buttons (go use an IDE-built-in agent first);
• Scenarios needing a GUI code review interface (pi's output is a text stream;可配合 /share to export HTML for sharing).

1.6 Chapter Summary

• Pi is a minimal terminal coding harness: 4 default tools + on-demand扩展; no预设 workflow;
• Five形态: interactive TUI, Print, JSON, RPC, SDK; config and sessions fully打通;
• More open and remote-capable than IDE agents; a finished product rather than an orchestration framework;
• Five extension层次: template → skill → theme → extension → package; choose按需 based on cost.

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. What are pi's four default tools给 the model?

2. To ask pi a one-shot question in a shell script and get output then exit, which mode to use?

3. Regarding pi's design philosophy, which statement is correct?

4. To turn "the team's unified code review prompt" into a reusable asset, what is the lowest-cost approach?

🛠️ Hands-on Practice

1. Read the Philosophy section of the pi repo README; write down 3 differences between pi and a tool你熟悉 in your own words.
2. List 3 coding tasks from the past week; judge which run mode each suits (interactive/Print/JSON/RPC).
3. Browse the ~/.pi/agent/ directory (if already installed); confirm the settings.json, sessions/ etc. structure matches this chapter's description.

Ready? Proceed to Chapter 2: Installation and Quickstart to get pi running.