Pi is an open-source terminal coding agent built by Mario Zechner, the author of libGDX. Its core is just 418 lines of TypeScript, providing four tools by default — read, write, edit, and bash — with all advanced features supplied through extensions and packages. Previously I analyzed Pi’s design philosophy at the architecture level. This article focuses on real-world use: how to install it, configure it, pick extension packages, and weave Pi into your daily development workflow.

Positioning: Pi’s role in the toolchain

Pi isn’t meant to replace every coding tool. Taking DeepakNess’s actual usage as an example, three tools each have their own division of labor:

• OpenAI Codex: handles complex tasks on the main project
• Cursor: everyday coding on the main project
• Pi: side projects, experimental tasks, and one-off scripts, usually paired with cheaper open-source models

The core logic behind this layered strategy: use strong models plus heavyweight tools for high-complexity tasks, and lightweight agents plus low-cost models for simple or exploratory tasks — keeping overall spending in check.

Installation and first-time configuration

Installing Pi only takes a single command:

Once installed, launch it by typing pi in the terminal and authenticate with the /login command. Pi supports two authentication methods:

1. Subscription login: supports Claude Pro/Max, ChatGPT Plus/Pro, GitHub Copilot, Google Gemini CLI, and more
2. API key: choose “Use an API key” and enter your provider’s secret (e.g., DeepSeek)

Use /model or Ctrl+L to open the model selector. The author defaults to deepseek-v4-pro with the xhigh thinking level for deep analysis, switching to deepseek-v4-flash for quick tasks.

Three core extension packages

Pi installs extension packages with pi install. The following three cover most practical scenarios:

pi-web-access

Gives Pi web search, content scraping, YouTube transcription, and GitHub repository exploration capabilities.

The configuration file lives at ~/.pi/web-search.json:

pi-codex-goal

Adds a goal-tracking mechanism for long-running tasks, well-suited to complex tasks that require multiple steps.

pi-vision-proxy

When the main model lacks vision capabilities, it proxies image-analysis requests to a vision-capable model (such as Kimi K2.6).

The configuration-file system

Pi’s configuration is divided into two layers:

AGENTS.md (project context): placed in the project root or ~/.pi/agent/AGENTS.md, its contents are injected into the system prompt. Good for defining a project’s tech stack, coding conventions, and so on.

APPEND_SYSTEM.md (global behavior rules): located at ~/.pi/agent/APPEND_SYSTEM.md, appended to the end of the system prompt and given higher priority than AGENTS.md. Good for defining cross-project behavioral conventions, such as:

• Automatically use the vision proxy when the main model lacks vision
• Prefer local files, and only search the web when necessary
• Explain high-risk edits and commands
• Write concisely and avoid AI-sounding language

Shortcuts and common commands

Pi’s interaction design focuses on terminal efficiency:

Common commands include /model, /settings, /resume, /new, /tree (session-branch management), /compact (manually compact context), and /session.

A real-world cost example

A typical use case: crawling 285,000 URLs with DeepSeek v4 Flash took about 1.5 hours for a total cost of $1. This illustrates Pi’s cost advantage when paired with open-source models.

Why choose Pi

Pi’s core strengths come down to:

• Terminal-native: no UI lag, responsive
• Model-agnostic: switch providers anytime via /model, with seamless context migration
• Highly customizable: the extension and package mechanism lets users assemble features on demand
• Session-tree management: the /tree command supports branching and navigating conversation history
• Automatic context compaction: automatically summarizes when approaching the context limit

For terminal users, Pi’s value lies not in “having the most features” but in “having the highest controllability.” Every one of its behaviors is transparent, and every feature is explicitly installed. This design philosophy makes it the ideal choice for side projects and experimental tasks.

Sources:

• DeepakNess: Setting Up and Using the Pi Coding Agent
• Pi official documentation