I have compiled a complete configuration scheme for Pi Agent, featuring 17 plugins, 18 global Skills, and 2 MCP servers, along with a one-click install script. Out of the box, Pi only has four capabilities: reading/writing files and running commands. This configuration is not simply stacking plugins; it is a complete design centered around actual coding workflows.

At the task orchestration level, I’ve installed sub-agent delegation, goal-driven, and planning modes. Complex tasks can be split across multiple sub-agents to run serially or in parallel, or you can first produce a plan before executing, avoiding making changes to the code prematurely.

At the code understanding level, I’ve installed AST-level search/replace, LSP diagnostics, symbol navigation, and context management. Pi can understand code structure, not just text matching. The context-mode can summarize large outputs: reading 47 files directly consumes ~700KB of context, but using it returns only ~3.6KB. Cross-session memory allows Pi to remember previous project conventions even when opening a new window next time.

For external access, I’ve installed web search, Playwright browser automation, an MCP adapter, and two MCP servers: Context7 and Chrome DevTools. It can look up the latest documentation, remotely debug web pages, and capture network packets.

Additionally, I’ve configured a todo overlay, status bar enhancement, GitHub PR viewing, code review, prompt templates, and themes. Each plugin has been selected based on actual usage; tool switches are finely configured — commonly unused ones are set to inactive by default, and MCP servers are set to lazy start for on-demand loading.

Repo URL: https://github.com/realchendahuang/pi-config

realchendahuang/pi-config

Source: https://github.com/realchendahuang/pi-config

My Pi Coding Agent Configuration

License: MIT

Pi (https://pi.dev)

Plugins Skills MCP Platform

GitHub stars (https://github.com/realchendahuang/pi-config/stargazers) Last Commit (https://github.com/realchendahuang/pi-config/commits) Source (https://github.com/realchendahuang/pi-config)

██████╗ ██╗ ██████╗ ██████╗ ███╗ ██╗███████╗██╗ ██████╗ ██╔══██╗██║ ██╔════╝██╔═══██╗████╗ ██║██╔════╝██║██╔════╝ ██████╔╝██║ ██║ ██║ ██║██╔██╗ ██║█████╗ ██║██║ ███╗ ██╔═══╝ ██║ ██║ ██║ ██║██║╚██╗██║██╔══╝ ██║██║ ██║ ██║ ██║ ╚██████╗╚██████╔╝██║ ╚████║██║ ██║╚██████╔╝ ╚═╝ ╚═╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═══╝╚═╝ ╚═╝ ╚═════╝ 17 plugins · 18 global skills · 2 MCP servers · one-line installer

A ready-to-replicate configuration for Pi, shared as a tutorial. Includes 17 plugins, 18 global Skills, 2 MCP servers, and a one-click install script.

Everything in this repo has been filtered through real-world use. The goal is to turn Pi into a versatile terminal coding agent capable of multi-agent collaboration, token savings, and browser automation.

1. What is Pi?

Pi (npm package @earendil-works/pi-coding-agent) is an open-source terminal AI coding agent. You give it a task, and it reads/writes files, runs commands, and calls tools on your local project to get the job done.

If you haven’t installed Pi yet, first run: bash npm install -g @earendil-works/pi-coding-agent Then run pi to enter the interactive interface. All plugins in this repo assume you already have a working Pi installation.

2. Pi’s Overall Architecture

Understanding the architecture helps you choose and write plugins. Pi is a plugin-driven agent loop, with the following core layers:

┌─────────────────────────────────────────────────────┐ │ TUI / RPC / Print ← User interaction layer │ │ (terminal UI / API) │ ├─────────────────────────────────────────────────────┤ │ Agent Loop ← Agent loop: receive prompt → call │ │ model → execute tools → return │ ├─────────────────────────────────────────────────────┤ │ Providers / Models ← Multi-model abstraction: │ │ OpenAI / Anthropic / local / │ │ custom provider │ ├─────────────────────────────────────────────────────┤ │ Tools ← Tools callable by the model: │ │ bash/read/edit/web_search/mcp/custom │ ├─────────────────────────────────────────────────────┤ │ Extensions ← TypeScript modules that can │ │ subscribe to events, register │ │ tools/commands/keybindings/themes │ ├─────────────────────────────────────────────────────┤ │ Skills / Prompts ← Markdown "procedural │ │ knowledge", injected into │ │ model context on demand │ ├─────────────────────────────────────────────────────┤ │ Themes ← JSON color schemes │ ├─────────────────────────────────────────────────────┤ │ Packages ← Distribution units for the above │ │ (npm / git / local path) │ └─────────────────────────────────────────────────────┘

Key Concepts:

• Extension: TypeScript modules, the most powerful way to modify. Can subscribe to lifecycle events (e.g., tool_call can intercept/modify/block tool calls), register custom tools, register commands, modify system prompts, and customize rendering.
• Skill: A SKILL.md file describing “how to do a certain type of task”. Loaded on demand by the model, persists across sessions. Pi implements the Agent Skills standard, so skills from Claude Code / OpenAI Codex can be used directly.
• Prompt: Reusable .md templates, invoked via /template.
• Theme: JSON color scheme file.
• Package: Packages the above into a distributable unit via npm / git / local path. pi install installs a package.

General flow of the agent loop:

1. User inputs a prompt
2. before_agent_start event (extensions can inject messages / modify system prompts)
3. Enter turn loop: call model → model may call tools → tool_call event (can intercept) → execute tool → tool_result event (can modify result) → pass back to model
4. Model stops calling tools → agent_end → agent_settled

Extensions can hook into any of these stages.

3. Pi Ecosystem & Package Marketplace

Package Marketplace (pi.dev/packages)

Pi has an official package marketplace. Any npm package with the pi-package keyword in its package.json automatically appears there. Each package page shows version, downloads, dependencies, repo link, and even demo videos/screenshots.

You can also search packages directly in Pi: ``bash

Using the pi-marketplace extension (already installed in this repo)

Or via command line:

pi install npm:@some/package ``

Three Package Sources

Configuration File Locations

4. How to Modify / Extend Pi

Pi provides three levels of modification, from light to heavy. Choose according to your needs:

Lightweight: Write a Skill

The simplest extension. Write a markdown file at ~/.agents/skills/my-skill/SKILL.md describing the standard process for a certain type of task. The model will load it on demand. The chrome-devtools skill in this repo is in this form.

Suitable for: Codifying process knowledge like “how to debug a certain framework” or “how to release a version”, zero code.

Medium: Install / Write an MCP Server

MCP (Model Context Protocol) is a cross-agent tool protocol. You write an MCP server (any language), register it in ~/.config/mcp/mcp.json, and Pi connects its tools via pi-mcp-adapter. The two MCP servers in this repo (context7, chrome-devtools) are connected this way.

Suitable for: Accessing external services (databases, APIs, browsers, documentation sources), tools reusable across agents.

Heavyweight: Write an Extension

The most powerful modification. Create ~/.pi/agent/extensions/my-ext.ts:

``typescript import type { ExtensionAPI } from “@earendil-works/pi-coding-agent”; import { Type } from “typebox”;

export default function (pi: ExtensionAPI) { // Intercept dangerous commands pi.on(“tool_call”, async (event, ctx) => { if (event.toolName === “bash” && event.input.command?.includes(“rm -rf”)) { const ok = await ctx.ui.confirm(“Danger!”, “Allow rm -rf?”); if (!ok) return { block: true, reason: “User cancelled” }; } });

// Register a custom tool pi.registerTool({ name: “greet”, label: “Greet”, description: “Greet someone by name”, parameters: Type.Object({ name: Type.String() }), async execute(_id, params) { return { content: [{ type: “text”, text: Hello, ${params.name}! }] }; }, });

// Register a command pi.registerCommand(“hello”, { description: “Say hello”, handler: async (_args, ctx) => ctx.ui.notify(“Hello!”, “info”), }); } ``

Test with pi -e ./my-ext.ts; for production use, place it in ~/.pi/agent/extensions/ and run /reload.

Suitable for: permission gates, git checkpoints, custom compaction, external integrations, stateful tools. Subscribable events cover the full lifecycle of session / agent / message / tool / model / provider.

Packaging & Distribution

After writing, add a package.json with the pi manifest and pi-package keyword, publish to npm:

json { "name": "my-pi-ext", "keywords": ["pi-package"], "pi": { "extensions": ["./extensions"], "skills": ["./skills"] } }

Then pi install npm:my-pi-ext — others can use your extension.

5. Quick Start (3 Steps)

``bash

1. Clone this repo

git clone https://github.com/realchendahuang/pi-config.git cd pi-config

2. One-click install (install 17 plugins + merge MCP config)

bash install.sh

3. Restart Pi to activate all plugins and MCP servers

``

The script will automatically install the 17 plugins using pi install and merge the configuration of the 2 MCP servers into ~/.config/mcp/mcp.json (if that file already exists, it will preserve your existing servers and only add the new ones).

After installation, you still need to configure the model provider/key yourself via pi config — that part varies per user and is outside the scope of this repo.

6. Plugin Directory (17 plugins, grouped by purpose)

Below is a detailed explanation of each plugin: what it does, why it was chosen, and a link to its repo for deeper exploration.

🤖 Agent Orchestration & Workflow

pi-subagents

Sub-agent delegation framework. Allows the main agent to delegate tasks to sub-agents with five operation modes:

• single: A single sub-agent completes a task independently
• chain: Multiple sub-agents form a pipeline, output of one feeds into the next
• parallel: Multiple sub-agents run the same type of task in parallel
• async: Execute in background asynchronously, notify when done
• forked-context: Fork an independent context from the parent session

Ideal for complex workflows like “let one agent research, another implement, and a third review.” Comes with a pi-subagents skill that teaches the model how to orchestrate.

• 📦 Repo:

@narumitw/pi-goal

Goal-driven mode. Set a goal with /goal, and Pi will autonomously work towards it until completion. If blocked, it actively stops and waits for you. Great for long tasks like “finish this feature.”

• 📦 Repo:

@narumitw/pi-plan-mode

Read-only planning mode (similar to Codex’s read-only collaboration). The model first produces a plan, discusses it with you, then proceeds to execution. Prevents random code changes.

• 📦 Repo:

🔍 Code Intelligence & Context Management

pi-lens

Pi’s “IDE eyes.” Adds AST-level code understanding:

• ast-grep based structural search/replace (more precise than plain-text grep)
• tree-sitter based syntax rule checking
• LSP diagnostics: check type errors before building
• Symbol search, module reporting, reading symbol bodies — “cheap code reading” tools

Comes with 4 skills: pi-lens-ast-grep, pi-lens-lsp-navigation, pi-lens-write-ast-grep-rule, pi-lens-write-tree-sitter-rule (teaches you to write custom rules).

• 📦 Repo:

context-mode

Core token-saving plugin. Routes large outputs (logs, build results, web content, git diffs, etc.) into a sandbox, processes them with code, and returns only a summary to the model. Includes an FTS5 full-text search knowledge base that can index documents, web pages, and historical sessions for later retrieval.

Effect: Analyzing 47 source files via direct read would consume ~700KB of context; using context-mode returns only ~3.6KB. Comes with 8 skills (ctx-search / ctx-index / ctx-stats / ctx-purge / ctx-insight / ctx-doctor / ctx-upgrade / context-mode itself).

• 📦 Repo:

pi-hermes-memory

Cross-session memory. Lets Pi remember things you’ve told it before (your preferences, project conventions, past pitfalls), even in new sessions. Memory is categorized as user / memory / project / failure, and is searchable. Default policy-based token-aware memory with SQLite FTS5 retrieval and automatic compaction.

• 📦 Repo:

🌐 Browsing, Search & External Access

pi-web-access

Web access all-in-one:

• web_search: Multi-engine web search (OpenAI / Brave / Exa / Tavily / Perplexity / Gemini)
• fetch_content: Fetch URL content and convert to markdown; supports YouTube transcripts, GitHub repo cloning, PDF extraction, local video frame extraction
• Includes librarian skill: library research with permanent GitHub links, ideal for deep-diving into internal implementations of open-source libraries
• 📦 Repo:

pi-playwright

Playwright browser automation. Lets Pi open a browser, fill forms, click buttons, take screenshots, inspect console/network. Comes with playwright-browser skill. Great for testing web apps and end-to-end automation.

• 📦 Repo:

pi-mcp-adapter

MCP (Model Context Protocol) adapter. Allows Pi to connect to any MCP server and use its tools. The 2 MCP servers in this repo work through it. Supports OAuth, security reviews, and lazy loading on demand.

• 📦 Repo:

pi-marketplace

Pi package marketplace entry point. Search, view details, security audit, and install pi packages from npm directly in Pi. Includes tools: marketplace_search, marketplace_detail, marketplace_audit, marketplace_install. Very convenient for discovering new plugins.

• 📦 Repo:

✨ Utilities & Themes

@juicesharp/rpiv-todo

A to-do list for the model, rendered as a live overlay that survives /reload and session compaction. Visual progress tracking for multi-step tasks, preventing the model from going off track.

• 📦 Repo:

@narumitw/pi-statusline

Enhanced status bar. Replaces Pi’s default footer, displaying model info, context usage, git status, and more — a quick glance tells you the current state.

• 📦 Repo:

@narumitw/pi-github-pr

View GitHub PR reviews, checks, and comment statuses inside Pi without switching to the browser.

• 📦 Repo:

pi-simplify

Reviews recently changed code, giving suggestions from clarity, consistency, and maintainability perspectives. Run after making changes to clean up code smells.

• 📦 Repo:

@firstpick/pi-prompts-git-pr

A set of reusable prompt templates: commit messages, PR descriptions, PR review workflows. Invoke with / followed by the template name, saving you from writing them each time.

• 📦 Repo:

@firstpick/pi-skill-deep-research

Includes the deep-research skill: a two-stage rigorous research workflow with schema/policy validation. Suitable for high-stakes research requiring multi-source evidence and fact-checking.

• 📦 Repo:

@victor-software-house/pi-curated-themes

A curated collection of dark terminal themes (ported from iTerm2-Color-Schemes), including the one I use, github-dark-colorblind. Also includes the adapt-ghostty-theme-to-pi skill: converts a Ghostty terminal theme into a Pi theme.

• 📦 Repo:

7. Global Skill List (18 skills)

All skills are global — once installed, they are available everywhere, regardless of the current project.

The chrome-devtools skill is a custom global skill I placed in ~/.agents/skills/, not in any npm package. You’ll need to create it yourself (refer to “Write a Skill” in section 2).

8. MCP Servers (2)

Configuration is in mcp.json; the install script merges it into ~/.config/mcp/mcp.json.

context7

Upstash’s Context7 MCP. Fetches the latest documentation for third-party libraries in real time, preventing the model from using outdated training knowledge when writing code.

json { "command": "npx", "args": ["-y", "@upstash/context7-mcp@latest"], "lifecycle": "lazy" }

chrome-devtools

Chrome DevTools remote control, with 29 tools (click, screenshot, network capture, performance analysis, etc.). Works well with the chrome-devtools skill for debugging web pages.

This server requires a local binary called chrome-devtools-mcp. The path in mcp.json is hardcoded; please change it to your own path when using on a different machine.

Both are set with "lifecycle": "lazy" — they start on demand, not permanently, saving resources.

9. Repository Contents

10. After Installation, How to Use

1. Configure the model: Run pi config and add your own provider and model. This repo does not cover that part.
2. Restart Pi: To activate all newly installed plugins and MCP servers.
3. Try skills: In Pi, simply describe a task, and the model will automatically match the appropriate skill. You can also use slash commands like /context-mode:ctx-stats to invoke skills manually.
4. Adjust tool toggles (optional): Pi’s tools.json allows you to set infrequently used tools to inactive, keeping the tool list clean. My personal practice is to set ast_grep_* / grep / find / ls / lsp_navigation to inactive, and use pi_lens_activate_tools on demand. config.json contains my full tools configuration for reference.

11. Star Trend

Star History Chart

The repo is newly created; the curve will update in real time as stars grow. Click the image to go to the interactive star-history page.

12. Contribution Activity Line Chart

The following ASCII line chart is generated from the real git log of this repo (commits binned by hour), drawn with monospaced block characters — it serves both as a contribution trend visualization and a test of GitHub’s monospace rendering.

Hourly commit distribution (2026-07-25) 4 │ ●─ │ ●─ │ ●─ │ ●─ │ ╱ ●─ │ ●─ ●─ └┴───┴─── 17:00 18:00 Total commits: 5 | Time span: 17:34 → 18:13

As commits increase, this chart will auto-redraw by hour/day. The generation script idea: git log --pretty=format:%ad → bin by hour → draw with ● / ╱ / ─.

License

MIT