Chào mừng trở lại với series GitHub deep dive! Hôm nay, chúng ta sẽ mổ xẻ Pi Mono, một monorepo của Mario Zechner (người tạo ra libGDX) với triết lý hoàn toàn khác biệt về AI coding agent.

Trong khi các công cụ như Claude Code, Cursor, và Aider tích hợp sẵn các tính năng như sub-agents, plan mode, và permission popups, Pi nói: “Tự xây đi.” Nó cung cấp cho bạn các primitives—một API LLM thống nhất, agent runtime, TUI framework, và thư viện web UI—rồi để bạn tự lắp ghép workflow bằng TypeScript extensions.

Hãy phân tích theo Mental Model của chúng ta.

Phần 1: Nền Tảng (Mental Model)

Hãy nghĩ về hầu hết AI coding agent như một ngôi nhà xây sẵn. Bản vẽ đã cố định, tường ở đâu thì ở đó, và nếu bạn muốn thêm cửa sổ trời, bạn phải submit PR rồi cầu nguyện maintainer đồng ý.

Pi giống như một bộ công cụ xây dựng hơn. Nó cho bạn thép (LLM API), hệ thống điện (agent runtime), đồ nội thất (TUI & Web UI), và nói: “Đi xây nhà đi.”

Kết quả? Một coding agent có sẵn 4 tools mặc định (read, write, edit, bash) và dùng được ngay—nhưng đồng thời là một agent bạn có thể biến đổi hoàn toàn mà không cần fork code.

Mental Model: Pi Mono = API LLM Thống Nhất + Agent Runtime Có Trạng Thái + TUI Framework + Web Components + Hệ Thống Extension = AI Agent Của Bạn, Theo Cách Của Bạn.

Phần 2: Khám Phá Kiến Trúc

Pi Mono là một TypeScript monorepo chứa 7 packages, mỗi package giải quyết một vấn đề cụ thể trong stack AI agent:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

┌──────────────────────────────────────────────────────────────┐
│                     pi-coding-agent                          │
│  CLI tương tác với sessions, branching, compaction            │
│  Extensions | Skills | Prompt Templates | Themes             │
├──────────────────────────────────────────────────────────────┤
│        pi-agent-core        │        pi-web-ui              │
│  Agent loop, tools, events  │  Chat panels, artifacts       │
│  Steering & follow-up       │  JS REPL, attachments         │
├─────────────────────────────┤  CORS proxy, IndexedDB        │
│           pi-ai             ├────────────────────────────────┤
│  API đa nhà cung cấp       │         pi-tui                │
│  20+ LLM providers          │  Differential rendering       │
│  Cross-provider handoffs    │  Editor, Markdown, Image      │
│  Tool calling & validation  │  Synchronized output          │
├─────────────────────────────┼────────────────────────────────┤
│          pi-mom             │         pi-pods               │
│  Slack bot tự quản lý       │  Quản lý GPU pod              │
│  Docker sandbox             │  Tự cấu hình vLLM             │
│  Events & scheduled tasks   │  Hỗ trợ multi-GPU            │
└─────────────────────────────┴────────────────────────────────┘

7 Packages Chi Tiết

Phần 3: Đi Sâu Kỹ Thuật

Đây là phần Pi thực sự thú vị cho developers.

1. Hệ Thống Extension: Xây Bất Cứ Gì

Tính năng sát thủ của Pi là extension API. Extensions là các TypeScript modules có thể:

• Thay thế hoàn toàn built-in tools (thay write bằng phiên bản tự động commit git)
• Thêm custom UI components (status lines, headers, overlays—thậm chí cả Doom)
• Triển khai sub-agents và plan mode (Pi cố tình không ship sẵn, để bạn tự xây theo workflow của mình)
• Kiểm soát quyền truy cập và bảo vệ đường dẫn
• Tích hợp MCP servers
• Xây dựng SSH và sandbox execution

1
2
3
4
5

export default function (pi: ExtensionAPI) {
  pi.registerTool({ name: "deploy", ... });
  pi.registerCommand("stats", { ... });
  pi.on("tool_call", async (event, ctx) => { ... });
}

Triết lý rõ ràng: các tính năng mà tool khác tích hợp sẵn thì có thể xây bằng extensions, giữ core tối giản và agent đúng theo cách bạn làm việc.

2. Chuyển Đổi Cross-Provider

Hầu hết thư viện LLM khóa bạn vào một nhà cung cấp trong suốt session. Package pi-ai hỗ trợ chuyển đổi liền mạch giữa các providers ngay giữa cuộc hội thoại:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

import { getModel, complete, Context } from '@mariozechner/pi-ai';

// Bắt đầu với Claude để phân tích
const claude = getModel('anthropic', 'claude-sonnet-4-20250514');
const context: Context = {
  messages: [{ role: 'user', content: 'Phân tích bug phức tạp này' }]
};
const analysis = await complete(claude, context);
context.messages.push(analysis);

// Chuyển sang GPT để triển khai
const gpt = getModel('openai', 'gpt-4o');
context.messages.push({ role: 'user', content: 'Giờ sửa nó đi' });
const fix = await complete(gpt, context);

Thinking blocks từ Provider A tự động được chuyển thành text với tags <thinking> cho Provider B. Tool calls và results được giữ nguyên.

3. Session Branching & Compaction

Pi lưu sessions dưới dạng file JSONL với cấu trúc cây. Mỗi entry có id và parentId, cho phép tạo nhánh tại chỗ mà không cần tạo file mới:

• /tree - Duyệt toàn bộ lịch sử session, nhảy đến bất kỳ điểm nào, và tiếp tục từ đó
• /fork - Tạo session mới từ bất kỳ điểm phân nhánh nào
• /compact - Tóm tắt các tin nhắn cũ để giải phóng context. Toàn bộ lịch sử vẫn nằm trong file JSONL

Cực kỳ hữu ích khi khám phá—thử một cách tiếp cận, tạo nhánh, thử cách khác, và chuyển đổi giữa chúng mà không mất gì.

4. Pi Mom: Bot Tự Quản Lý

pi-mom không giống bất kỳ chatbot framework nào. Đây là Slack bot:

• Tự cài tools (apk add git jq curl)
• Tự viết CLI skills (cần kiểm tra Gmail? Hỏi Mom, cô ấy viết script)
• Tự quản lý credentials (hỏi tokens, lưu trữ an toàn)
• Chạy trong Docker sandbox với full bash access
• Lên lịch events (cron-based periodic tasks, nhắc nhở one-shot)

Mỗi kênh Slack có workspace, lịch sử hội thoại, và file memory riêng. Mom tự động compaction context và có thể grep lịch sử vô hạn từ log.jsonl.

5. Quản Lý GPU Pod với pi-pods

Cho developers tự chạy models, pi-pods tự động hóa việc deploy vLLM:

1
2
3
4
5
6
7
8
9

# Setup DataCrunch pod với NFS storage
pi pods setup dc1 "ssh [email protected]" \
  --mount "sudo mount -t nfs nfs.fin-02.datacrunch.io:/hf-models /mnt/hf-models"

# Khởi chạy Qwen trên H100
pi start Qwen/Qwen2.5-Coder-32B-Instruct --name qwen

# Chat tương tác với file system tools
pi agent qwen -i

Nó tự động cấu hình tool calling parsers cho các models phổ biến (Hermes cho Qwen, GLM4 parser cho GLM, Responses API cho GPT-OSS) và quản lý phân bổ multi-GPU.

Phần 4: Cách Sử Dụng

Bắt Đầu

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# Cài coding agent
npm install -g @mariozechner/pi-coding-agent

# Xác thực
export ANTHROPIC_API_KEY=sk-ant-...
pi

# Hoặc dùng subscription có sẵn
pi
/login  # Chọn provider (Claude Pro, ChatGPT Plus, GitHub Copilot, v.v.)

Pi cung cấp sẵn 4 tools mặc định: read, write, edit, bash. Bắt đầu nói chuyện và model sẽ dùng chúng để thực hiện yêu cầu của bạn.

Mở Rộng Pi

Hệ sinh thái extension của Pi được phân phối qua Pi Packages—gói extensions, skills, prompts, và themes chia sẻ qua npm hoặc git:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# Cài package từ cộng đồng
pi install npm:@foo/pi-tools

# Hoặc từ git
pi install git:github.com/user/repo

# Liệt kê, cập nhật, cấu hình
pi list
pi update
pi config

Sử Dụng Như SDK

Pi không chỉ là CLI. Bạn có thể nhúng nó vào ứng dụng của mình:

1
2
3
4
5
6
7
8
9

import { createAgentSession, SessionManager, AuthStorage, ModelRegistry } from "@mariozechner/pi-coding-agent";

const { session } = await createAgentSession({
  sessionManager: SessionManager.inMemory(),
  authStorage: new AuthStorage(),
  modelRegistry: new ModelRegistry(authStorage),
});

await session.prompt("Liệt kê các file trong thư mục hiện tại?");

Cho các dự án không dùng Node.js, dùng RPC mode qua stdin/stdout: pi --mode rpc.

Mental Model Tổng Kết

Pi Mono dành cho developers muốn AI coding agent thích ứng với workflow của họ, chứ không phải ngược lại. Nó đánh đổi trải nghiệm out-of-the-box bóng bẩy lấy khả năng tổ hợp triệt để—và hỗ trợ điều đó bằng một bộ primitives thực sự tinh tế.

Monorepo này sử dụng giấy phép MIT, được bảo trì tích cực, và có cộng đồng Discord ngày càng phát triển. Nếu bạn từng ước AI coding agent hoạt động khác đi, Pi nói: cứ làm đi.