Why Pi Gets 77K Stars Despite No MCP, No Permission System, and Only Four Packages

Overview

Pi is a terminal AI programming assistant that has attracted 77.7 K stars on GitHub. Its creator, Mario Zechner, built it to solve hidden system‑prompt and context‑management problems that other tools, such as Claude Code, leave unresolved.

1. Token Count – Real Measurement Shows 1520 Tokens

The author claims Pi’s system prompt and tool definitions use "under 1000 tokens". By calling the internal estimateTokens function (which simply divides character count by 4) and reproducing the same algorithm, the measured token count for the default four‑tool configuration is 1520, about 50 % higher than claimed.

The excess comes from an absolute file‑path embedded in the system prompt (which can consume a few hundred tokens depending on the Node installation method) and the coarse nature of the character‑division estimation compared with a real tokenizer.

Importantly, the token count can be measured by any user, eliminating the need to rely on the project's documentation.

2. Stable Workflow – Prompt Snippets Are Assembled Dynamically

System prompts shrink automatically when tools are disabled. Each tool definition contains two fields, promptSnippet and promptGuidelines, which contribute the exact sentences that the tool adds to the system prompt.

Disabling a tool (e.g., using --tools read,grep) removes both its functionality and its explanatory text from the prompt. The code also contains a conditional that adds a bash‑usage hint only when bash is present and none of the file‑search tools (grep, find, ls) are enabled.

This dynamic assembly contrasts with the common practice of hard‑coding a monolithic prompt and then using conditional statements to hide parts, which requires manual prompt updates whenever a feature is removed.

3. Modular Packages – Four Independently Installable npm Modules

Pi is described as an "agent toolkit" consisting of four npm packages that can be installed separately:

pi-ai (21 132 lines)

pi-agent-core (10 028 lines)

pi-tui (12 189 lines)

pi-coding-agent (55 214 lines)

The architecture is cleanly layered: the TUI does not depend on the agent core, and the model‑API layer does not depend on the TUI. The top‑level pi command is provided by pi-coding-agent, which composes the other three packages.

Practical benefit: a project that only needs a terminal UI can install npm i pi-tui, while a project that only needs model‑API abstraction can install npm i pi-ai without pulling the entire coding assistant.

Weekly npm download statistics (checked 2026‑07‑26) show the TUI library receives about 4.37 M downloads, more than three times the 1.32 M downloads of the CLI itself, indicating many users extract only the UI component.

4. Runtime Mechanics – Steering Messages and Safe Truncation

The core loop resides in agent-loop.ts and consists of a double loop: the outer loop processes incoming messages, while the inner loop handles tool calls.

After each inner‑loop iteration, Pi extracts a "steering message" (called a steering message in the source) and inserts it before the next model response, allowing users to correct the agent without restarting.

When model output is cut off by the token limit, Pi marks the entire batch as failed and skips execution of all tool calls in that batch, forcing the model to retry the round. The relevant snippet is:

const executedToolBatch =
  message.stopReason === "length"
    ? await failToolCallsFromTruncatedMessage(toolCalls, emit)
    : await executeToolCalls(...);

Tool execution mode is also dynamic. If any tool in the batch declares executionMode: "sequential", the whole batch falls back to sequential execution:

const hasSequentialToolCall =
  toolCalls.some(tc =>
    tools.find(t => t.name === tc.name)?.executionMode === "sequential");

if (config.toolExecution === "sequential" || hasSequentialToolCall) {
  return executeToolCallsSequential(...);
}
return executeToolCallsParallel(...);

This conservative approach prevents race conditions when tools share mutable state.

5. Long‑Conversation Compression

When the context token count exceeds window‑16384 , Pi triggers compression. It retains the newest messages up to 20 k tokens, discards older messages, and summarizes them into a CompactionEntry. The new summary is then inserted into the refreshed context, ensuring early conversation constraints are not lost.

Compression requests use a separate routing session ID, and for supported providers Pi disables prompt‑cache writes because the request is one‑off and caching would waste quota.

6. Domestic Integration and Dependency Safety

The repository’s .npmrc enforces exact version locking ( save-exact) and a min-release-age=2 rule that skips installing packages released less than two days ago, mitigating supply‑chain attacks during the vulnerable initial release window.

All 15 external dependencies are pinned to exact versions (no caret ranges). The pi-ai package includes adapters for 37 model providers, with 13 Chinese‑region endpoints (identified by the -cn suffix). Example list:

deepseek       kimi-coding
minimax-cn    moonshotai-cn
zai-coding-cn ant-ling
xiaomi        qwen-token-plan-cn

Each region is represented as a separate provider entry, simplifying usage for developers in China.

7. Security – No Built‑In Permission System

Pi runs with the full permissions of the user who launches it; there is no permission‑confirmation dialog, so commands like rm -rf execute without restriction.

"The in‑process sandbox is incomplete and should not be mistaken for a security boundary. True isolation must come from the OS, virtualization, or container layer."

The official security doc clarifies that Pi’s trust model protects only against a repository silently modifying Pi’s configuration or extensions; it cannot reliably prevent prompt‑injection attacks hidden in repository files.

Three containerization options are offered: Gondolin micro‑VM (keeps credentials on the host while running tools in a micro VM), standard Docker, and OpenShell.

Conclusion – Who Should Use Pi

Pi provides a modular, transparent alternative to turnkey solutions like Claude Code. It is well‑suited for users who need any of the five pain‑point solutions illustrated in the opening diagram (e.g., inspectable token usage, dynamic prompt assembly, selective package installation, live steering, or multi‑provider support). Conversely, users who expect out‑of‑the‑box capabilities such as MCP, sub‑agents, or built‑in permission prompts may find Pi regressive.

Related Links

GitHub: https://github.com/earendil-works/pi

Documentation: https://pi.dev/docs/latest

Security notes: https://pi.dev/docs/latest/security

Containerization guide: https://pi.dev/docs/latest/containerization

Author’s blog post: https://mariozechner.at/posts/2025-11-30-pi-coding-agent/