You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 311e5e0
Browse filesBrowse the repository at this point in the historyBrowse files
docs(chapters): strip empty intensifiers from en/vi chapter prose
Mechanical cleanup of empty AI-tell adverbs and intensifiers across
the 10 English and 10 Vietnamese chapter files. Applied only outside
frontmatter and code fences (zh chapters untouched: they are the
canonical source from dgzhuya.com).
Removed patterns (per hardikpandya/stop-slop phrases.md):
- empty "really", "very", "just" (before common verbs), "simply",
"literally", "actually", "genuinely", "honestly", "truly",
"deeply", "fundamentally", "inevitably", "interestingly",
"importantly", "crucially", "essentially", "ultimately",
"obviously", "clearly", "naturally", "basically"
- empty "It is worth noting that", "It'"'"'s important to note that",
"It should be noted that", "Needless to say", "As we'"'"'ll see",
"In this section, we'"'"'ll", "Let me walk you through"
- puffery: "delve into", "in the world of", "in the realm of",
"this unlocks"
Meaning-preserving deletions only — no claims were changed. Meanings
of remaining "just" (e.g. "did we just read") and "more importantly"
(introducing the strongest claim) were left intact.
You probably opened this series for one of three reasons:
63
63
64
-
1.**"I want a coding agent that actually works"** — you are tired of bloated tools and want something minimal, transparent, fast.
65
-
2.**"I want to understand how an agent is actually built"** — you have poked at the source of other agent frameworks, and they were either too complex (tens of thousands of lines) or too naive (a single `while` loop calling itself an agent).
64
+
1.**"I want a coding agent that works"** — you are tired of bloated tools and want something minimal, transparent, fast.
65
+
2.**"I want to understand how an agent is built"** — you have poked at the source of other agent frameworks, and they were either too complex (tens of thousands of lines) or too naive (a single `while` loop calling itself an agent).
66
66
3.**"I want to build my own agent"** — you have a vertical use case and need to build on top of an SDK rather than start from scratch.
67
67
68
68
These three questions line up exactly with Pi's three identities. The fact that they all point to a single project is itself worth being curious about.
## 3. View 1: as a coding agent — a daily tool that is actually good
148
+
## 3. View 1: as a coding agent — a daily tool that is good
149
149
150
150
### 3.1 What Pi is: building blocks, not a finished car
151
151
152
152
State Pi's position in one sentence: **Pi is not another Cursor or Claude Code — it is a box of building blocks for assembling your own coding agent, your way.**
153
153
154
-
A useful analogy. Cursor is a finished car — seats, air conditioning, navigation all installed, you sit down and drive. Claude Code is also a finished car, just with a race-engine and reinforced suspension. Pi is different — it gives you the engine, chassis, steering column, and wiring harness, plus a guarantee that "we have already verified this combination works." It ships with a default configuration that runs out of the box (just type `pi` and you are up), but its core value is this: you can take the parts apart, reassemble them, add new ones, or restyle them, and build a **car that fits your workflow exactly**.
154
+
A useful analogy. Cursor is a finished car — seats, air conditioning, navigation all installed, you sit down and drive. Claude Code is also a finished car, just with a race-engine and reinforced suspension. Pi is different — it gives you the engine, chassis, steering column, and wiring harness, plus a guarantee that "we have already verified this combination works." It ships with a default configuration that runs out of the box (type `pi` and you are up), but its core value is this: you can take the parts apart, reassemble them, add new ones, or restyle them, and build a **car that fits your workflow exactly**.
155
155
156
156
This positioning is the source of every design decision in Pi. Once you understand it, the following all make sense:
157
157
@@ -231,7 +231,7 @@ Here are a few dividends you get out of the box:
231
231
232
232
**Tree-shaped sessions: when you go down the wrong path, fork.** Pi stores sessions as a **tree structure** (a DAG, a directed acyclic graph), not a linear log. `/tree` jumps to any historical message and forks a new branch from there. All branches live in the same file. Especially useful for debugging — you can try three different fixes from the same starting point without worrying about "not being able to go back".
233
233
234
-
**YOLO mode and the safety philosophy.** Pi defaults to YOLO — the agent executes actions without approval prompts. Mario's argument: approval-based safety measures cause user fatigue ("prompt fatigue"), and end up either disabled wholesale or reduced to mechanical "yes-clicking" that becomes "security theater". He recommends containerization as the security boundary. If you really need approval flows, about 50 lines of Extension code can build them — the framework exposes every hook you need.
234
+
**YOLO mode and the safety philosophy.** Pi defaults to YOLO — the agent executes actions without approval prompts. Mario's argument: approval-based safety measures cause user fatigue ("prompt fatigue"), and end up either disabled wholesale or reduced to mechanical "yes-clicking" that becomes "security theater". He recommends containerization as the security boundary. If you need approval flows, about 50 lines of Extension code can build them — the framework exposes every hook you need.
235
235
236
236
### 3.4 Up and running in one minute
237
237
@@ -286,7 +286,7 @@ Breaking down the key fields:
286
286
-**`providers`** — top level is a provider map; the keys (`zhipu` / `deepseek`) are names you pick and become the model's `provider` field in the UI.
287
287
-**`api`** — pick the protocol. Most common is `openai-completions` (OpenAI-compatible; nearly every Chinese provider supports it), then `anthropic-messages`, then `openai-responses`. This field decides which request format Pi uses.
288
288
-**`baseUrl`** — the provider endpoint.
289
-
-**`apiKey`** — stored in plaintext. **Make sure `.pi/` is in your `.gitignore`**, otherwise one careless `git add .` leaks it.
289
+
-**`apiKey`** — stored in plaintext. **Make sure `.pi/` is in your `.gitignore`**, otherwise one careless `git add. ` leaks it.
290
290
-**`models`** — the list of models under this provider. `id` is the actual model name passed to the API; `name` is the friendly label shown in the TUI.
291
291
-**`contextWindow` / `maxTokens`** — optional; tells Pi the window and max output length of this model, which informs the context-compaction strategy.
292
292
@@ -335,7 +335,7 @@ Each chapter answers three layers of questions: **what** (the concept), **how**
335
335
336
336
### 4.3 Pi's "philosophy of subtraction": the real lesson is in the trade-offs
337
337
338
-
Looking at a framework that "does everything", you can only learn "what they built". Looking at a framework that deliberately does nothing, you learn "what is actually necessary to build an agent".
338
+
Looking at a framework that "does everything", you can only learn "what they built". Looking at a framework that deliberately does nothing, you learn "what is necessary to build an agent".
339
339
340
340
The "What we did not build" section of Pi's official site is a manifesto written upside down. Competitors list features; Pi lists what it gave up. Every sacrifice is backed by a clear engineering reason:
341
341
@@ -358,7 +358,7 @@ The third identity: Pi is a set of independently reusable SDKs that let you buil
358
358
359
359
### 5.1 SDK stack: three-layer architecture plus one orthogonal UI library
360
360
361
-
Look again at the four-layer architecture diagram from section 2 — note that `pi-tui` is drawn **side by side** with `pi-agent-core`. It is not in the stack chain; it is a "side dependency" used by `pi-coding-agent` only in interactive mode. So from an SDK-reuse perspective, Pi is actually a **three-layer stack** (`pi-ai` → `pi-agent-core` → `pi-coding-agent`), plus an **orthogonal terminal UI library** (`pi-tui`). Each layer of the stack is independently usable, and the UI library is independently usable too — but it solves a different class of problem unrelated to the agent.
361
+
Look again at the four-layer architecture diagram from section 2 — note that `pi-tui` is drawn **side by side** with `pi-agent-core`. It is not in the stack chain; it is a "side dependency" used by `pi-coding-agent` only in interactive mode. So from an SDK-reuse perspective, Pi is a **three-layer stack** (`pi-ai` → `pi-agent-core` → `pi-coding-agent`), plus an **orthogonal terminal UI library** (`pi-tui`). Each layer of the stack is independently usable, and the UI library is independently usable too — but it solves a different class of problem unrelated to the agent.
362
362
363
363
**Layer 1: `pi-ai` — model calls only**
364
364
@@ -432,7 +432,7 @@ await session.prompt("Read the codebase and explain the architecture.");
432
432
433
433
`pi-tui` is Mario's old trade (the libGDX game-engine author), about 12,000 lines implementing:
434
434
435
-
-**Differential rendering** — only the changed cells are redrawn each frame, basically flicker-free.
435
+
-**Differential rendering** — only the changed cells are redrawn each frame, flicker-free.
436
436
-**Retained-mode UI** — a declarative component system similar to React, not the imperative style of ncurses.
437
437
-**Built-in components** — input boxes with autocomplete, a Markdown renderer, syntax highlighting, fuzzy search.
438
438
@@ -477,7 +477,7 @@ Pi is a "trinity" project:
477
477
478
478
1.**As a tool**: a minimal, transparent, steerable terminal coding agent. Clean context, model freedom, tree-shaped sessions, YOLO by default — for developers who want full control of their tools.
479
479
2.**As a textbook**: a high-quality, finishable Agent design reference. 10 chapters cover the core decision points of agent architecture (from Agent Loop to session management), and every line of code comes with a "why this way" answer.
480
-
3.**As an SDK**: a clearly layered, independently reusable development kit. The three-layer stack (`pi-ai` → `pi-agent-core` → `pi-coding-agent`) is usable layer by layer, plus a `pi-tui` terminal UI library decoupled from agents; four run modes cover everything from local to production.
480
+
3.**As an SDK**: a layered, independently reusable development kit. The three-layer stack (`pi-ai` → `pi-agent-core` → `pi-coding-agent`) is usable layer by layer, plus a `pi-tui` terminal UI library decoupled from agents; four run modes cover everything from local to production.
481
481
482
482
But the most important thing Pi proves is that **subtraction is a competitive product stance**. In a market racing toward "all-inclusive", the sentence "what I do not need will not be built" is itself a real feature.
These five customization levers (Extensions, Skills, Prompt Templates, Themes, Pi Packages) essentially provide **a smooth upgrade path from "using Pi" to "modifying Pi"**.
502
+
These five customization levers (Extensions, Skills, Prompt Templates, Themes, Pi Packages) provide **a smooth upgrade path from "using Pi" to "modifying Pi"**.
@@ -93,7 +93,7 @@ If you have worked on Node.js projects before, you have probably used a monorepo
93
93
94
94
But that is not the point. The point is: **why five packages (four extending the core three-piece set, plus one outer orchestration layer)? What is the relationship between them? Can they be merged?**
95
95
96
-
To answer that, we need to figure out what each package actually does.
96
+
To answer that, we need to figure out what each package does.
97
97
98
98
---
99
99
@@ -250,7 +250,7 @@ After reading the section above, you probably have a picture in your head alread
250
250
└──────────┘
251
251
```
252
252
253
-
A very intuitive layering: the bottom calls models, the middle runs the loop, the top handles the business. Right?
253
+
A intuitive layering: the bottom calls models, the middle runs the loop, the top handles the business. Right?
254
254
255
255
But wait —
256
256
@@ -272,7 +272,7 @@ If your mental model says "upper layers may only depend on the adjacent lower la
272
272
}
273
273
```
274
274
275
-
pi-coding-agent depends on **both** the middle layer (pi-agent-core) **and** the bottom layer (pi-ai). That looks like a violation of "strict layering", but it is actually a deliberate design choice.
275
+
pi-coding-agent depends on **both** the middle layer (pi-agent-core) **and** the bottom layer (pi-ai). That looks like a violation of "strict layering", but it is a deliberate design choice.
`AgentTool` is a "molecule" — it still has the `name`, `description`, and `parameters`, but it adds the ability to actually **run**. The Agent loop iterates over `AgentTool[]`, calls each tool''s `execute`, and feeds the result back into the model.
401
+
`AgentTool` is a "molecule" — it still has the `name`, `description`, and `parameters`, but it adds the ability to **run**. The Agent loop iterates over `AgentTool[]`, calls each tool''s `execute`, and feeds the result back into the model.
402
402
403
403
### Layer 3: pi-coding-agent builds molecules into materials
404
404
@@ -475,11 +475,11 @@ interface ToolDefinition {
475
475
476
476
---
477
477
478
-
## 6. Do I really need three layers when writing my own Agent?
478
+
## 6. Do I need three layers when writing my own Agent?
479
479
480
480
You might wonder: this Pi layering looks great, but is it overdesigned for my own Agent project?
481
481
482
-
Let us actually walk through three scenarios to see.
482
+
Let us walk through three scenarios to see.
483
483
484
484
### Scenario A: no layering, everything in one file
485
485
@@ -598,7 +598,7 @@ In this chapter we took an outside look at Pi''s overall architecture. You now k
598
598
- Types expand progressively from bottom to top: `Tool` → `AgentTool` → `ToolDefinition`
599
599
- Three layers are not required; the number of layers depends on your complexity. But dependency-direction control is required.
600
600
601
-
But we have not yet answered a more fundamental question: how does the Agent actually run? How does the LLM keep thinking, calling tools, reading results, thinking again? What does the famous "Agent Loop" actually look like?
601
+
But we have not yet answered a more fundamental question: how does the Agent run? How does the LLM keep thinking, calling tools, reading results, thinking again? What does the famous "Agent Loop" look like?
602
602
603
603
In the next chapter we drill into the Agent''s heart — **the Agent Loop**. We will first understand why a loop is needed (instead of finishing in one call), then trace a single user message''s full journey from pressing Enter until the Agent says "I am done".
0 commit comments