Pi Coding Agent on Windows: Multi-Model Terminal Setup, Extensions and Security Risks

For many developers, that all-inclusive approach is convenient. For others, it feels like trying to write a quick script inside a cockpit designed for a lunar landing. That growing fatigue with feature creep is why MakeUseOf writer Mahnoor Faisal recently spotlighted Pi, a free, MIT-licensed open-source terminal coding agent created by Mario Zechner and maintained under the earendil-works/pi project.

While MakeUseOf frames Pi as a tool that beats the big three at their own game, it is important to separate developer preference from benchmarked performance. There are no controlled test suites here proving that Pi writes better code than Claude Code, Codex, or Antigravity. Instead, Pi’s real appeal is philosophical: it strips the terminal coding agent down to a bare-metal harness, gets out of your way, and lets you decide which tools, workflows, and AI models belong in your terminal. For Windows developers and system administrators who live in Windows Terminal, PowerShell, or WSL, Pi offers a compelling—if sharp-edged—alternative to vendor-locked ecosystems.

The Philosophy of Less: Four Tools by Default​

Most commercial coding agents ship with an opinionated stack of built-in capabilities: sub-agents, automated to-do lists, Model Context Protocol (MCP) bridges, and rigid planning phases. Even open-source contenders like OpenCode have steadily expanded their feature sets to keep pace.

Pi takes the opposite tack. According to the project’s official GitHub documentation, Pi is built as a minimal, aggressively extensible terminal harness. When you fire it up, it exposes just four built-in tools to the underlying language model by default:

• read: Inspects file contents.
• write: Creates new files.
• edit: Modifies existing code and returns standard unified patches alongside terminal diff views.
• bash: Executes shell commands directly.

That doesn't mean those four actions are the limit of Pi's native vocabulary. The agent also ships with built-in grep, find, and ls tools, which you can enable on demand or pass via command-line flags like --tools read,grep,find,ls when you want a strictly read-only code review session.

Why hold back capabilities that are already written into the binary? MakeUseOf points out that keeping unused tool definitions out of the initial prompt avoids cluttering the model's context window. While the project documentation doesn't claim a measured benchmark boost from hiding grep or ls, the design philosophy is clear: fewer default moving parts mean fewer conflicting instructions sent to the model. Pi intentionally omits built-in sub-agents, MCP, background bash daemons, and structured to-do lists because its creator argues those features either confuse models or can be handled more transparently through standard terminal multiplexers, plain Markdown files, or custom extensions.

Summary: Core Architecture​

• Minimalist Core: Ships with only read, write, edit, and bash enabled by default, keeping grep, find, and ls optional.
• Four Run Modes: Operates as an interactive terminal UI (TUI), a print/JSON command-line tool for scripts, a strict LF-delimited JSONL RPC server for subprocess integration, or an embeddable TypeScript SDK.
• Session Branching: Stores conversations locally as tree-structured JSONL files, letting you use /tree or /fork to jump backward in a session and branch off in a new direction without losing your history.

Bring Your Own Model (and Your Own Budget)​

One of the sharpest pain points in the current AI coding market is ecosystem lock-in. If you build your muscle memory around Claude Code, you are paying Anthropic’s subscription or token rates for Claude models. Codex ties you to OpenAI’s frontier models, and Antigravity is centered primarily around Google’s Gemini ecosystem.

Pi decouples the terminal harness from the inference provider. MakeUseOf notes that Pi supports a wide roster of cloud providers—including Anthropic, OpenAI, Google, DeepSeek, Mistral, Groq, xAI, and Cerebras—alongside aggregators like OpenRouter. If you prefer to keep your code off third-party servers altogether, you can point Pi at local inference engines such as Ollama, LM Studio, llama.cpp, or vLLM.

Of course, "no vendor lock-in" does not mean free compute. While Pi itself is free software, cloud API calls still cost money per token, and local models require serious GPU VRAM if you want reasonable coding performance. What Pi actually gives you is cost and capability routing:

1. Authenticate Once: Run /login inside the interactive terminal or supply an API key to link your chosen providers.
2. Switch Mid-Stream: Use the /model command (or press Ctrl+L) to swap models on the fly without closing your session or losing your conversation tree.
3. Dial in Reasoning: Use /thinking (or Shift+Tab) to cycle through reasoning levels—from off and minimal up to high or max—depending on what the active model supports.
4. Offline Catalog Caching: According to Pi’s SDK documentation, model catalogs are cached locally in ~/.pi/agent/models-store.json and refreshed at most once every four hours per provider, or locked down completely if you set the PI_OFFLINE environment variable.

Building the Agent You Actually Want with TypeScript​

If Pi leaves out features like Claude Code’s popular Plan Mode on purpose, how do you get them back when you need them? The answer is Pi’s extension and package system.

Extensions in Pi are TypeScript modules stored globally in ~/.pi/agent/extensions/ or locally inside a project’s .pi/extensions/ directory. According to the project’s extension documentation, these modules can hook into lifecycle events (like before_provider_request or tool_call), register custom slash commands, override built-in tools, and even render custom terminal UI widgets and overlays using @mariozechner/pi-tui.

MakeUseOf points out that because Pi is itself a coding agent, you don't necessarily have to write TypeScript from scratch—you can ask Pi to generate an extension tailored to your workflow. However, developers shouldn't treat natural-language extension generation as magic; complex hooks still benefit from tested code. Fortunately, the official earendil-works/pi repository already ships with a rich library of working extension examples that prove just how far the harness can be stretched:

• plan-mode/: Recreates a Claude Code-style read-only exploration mode with a /plan command and step tracking.
• permission-gate.ts & protected-paths.ts: Prompts for confirmation before risky commands like rm -rf or blocks writes to sensitive directories like .env and .git/.
• git-checkpoint.ts: Automatically stashes git checkpoints at every turn so you can restore code states when forking a session.
• subagent/ & ssh.ts: Delegates isolated tasks to sub-agents or routes all tool execution to a remote machine over SSH.
• doom-overlay/: Renders playable DOOM at 35 FPS as a terminal overlay—because no extensible developer tool is truly complete until somebody runs DOOM inside it.

Beyond raw TypeScript extensions, Pi also supports reusable prompt templates and on-demand capability packages following the open Agent Skills standard, all of which can be bundled into shareable "Pi Packages" and installed via npm or git.

Setup and Practical Quirks for Windows Users​

If you want to test Pi on a Windows 11 workstation, the official npm package page (@earendil-works/pi-coding-agent, which recently reached version 1.3.0) outlines two installation paths and a few important platform prerequisites.

First, check your Node runtime: Pi requires Node.js 22.19.0 or newer (though a legacy-node20 tag exists on npm for older environments).

If you want Pi to pin all of its dependencies and manage its own updates via pi update, the project documentation provides a native PowerShell bootstrapper:

powershell -c "irm [url]https://pi.dev/install.ps1[/url] | iex"

Alternatively, if you already maintain a modern Node.js environment and prefer managing global packages through npm—the method highlighted by MakeUseOf—you can install it directly without running third-party dependency lifecycle scripts:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

Once installed, cd into your project folder and run pi.

Two Windows Terminal Gotchas to Fix Right Away​

According to Pi’s official usage and README documentation, Windows users running Windows Terminal will hit two minor keyboard shortcut collisions out of the box:

1. The Alt+Enter Follow-up Clash: While Pi is actively streaming a response, pressing Enter queues a "steering" message that interrupts remaining tool calls after the current tool finishes. Pressing Alt+Enter queues a gentler "follow-up" message that waits until the agent finishes its entire task. In Windows Terminal, however, Alt+Enter toggles fullscreen mode by default. You will want to remap that keybinding in your Windows Terminal settings JSON or customize ~/.pi/agent/keybindings.json so Pi can capture the shortcut.
2. Pasting Images: If you want to paste a screenshot directly into the terminal prompt for a vision-capable model to inspect, Windows uses Alt+V rather than Ctrl+V (or you can drag and drop the image file onto the terminal window).

The Security Catch: Minimalism Means No Guardrails​

Here is where the veteran sysadmin alarm bells need to ring. Commercial tools frequently annoy developers by asking "Are you sure?" before running a shell command. Pi skips permission pop-ups entirely by default.

As both MakeUseOf and Pi’s official security documentation emphasize, Pi does not include a built-in sandbox. Every built-in tool (read, write, edit, bash) and every installed TypeScript extension executes with the full operating-system permissions of the user account that launched the pi process.

Even more importantly, Pi’s documentation explicitly warns against confusing Project Trust with sandboxing:

• When you launch Pi in a repository that contains .pi/settings.json or project-local extensions, Pi asks whether you trust the directory (storing your decision in ~/.pi/agent/trust.json).
• That trust prompt is strictly an input-loading guard so a cloned repo cannot silently hijack your Pi configuration or run malicious .pi/extensions on startup.
• It does not confine the AI model to your project folder. Once a session begins, a hallucinated bash command or a prompt-injection attack hidden inside a repository's README, source comments, or AGENTS.md file (which loads regardless of project trust unless disabled) can read or modify any file on your PC that your user account can touch.

MakeUseOf notes that community extensions like pi-permission-system—or the official permission-gate.ts example—can add rule-based approval prompts back into your workflow. That is a smart first step for catching accidental typos, but an in-process TypeScript check is not an OS security boundary.

How to Run Pi Safely on Windows​

If you are letting Pi loose on untrusted repositories, running it in non-interactive modes (-p, --mode json, or --mode rpc, where project trust prompts aren't displayed), or automating tasks unattended, follow the official security guidelines:

• Isolate the Process: Run Pi inside a Dev Container, a Docker container, a dedicated WSL2 distribution, or a hypervisor VM/micro-VM (Pi’s examples include integrations for @anthropic-ai/sandbox-runtime and Gondolin micro-VMs).
• Limit Filesystem Mounts: Only mount the specific workspace folder the agent needs. Do not bind-mount your host ~/.pi/agent directory or SSH keys into a container unless necessary.
• Audit Third-Party Packages: Because Pi packages and extensions execute arbitrary code with full system access, always inspect the TypeScript source and skill definitions before running pi install on a third-party repository.

Summary: Security and Setup Takeaways​

• Node Requirement: Ensure Node.js >=22.19.0 is installed, or use the official PowerShell installer to handle dependencies automatically.
• No Native Sandbox: Launching pi in a folder does not restrict its shell or file tools to that folder; it runs with your full user privileges.
• Containerize Untrusted Work: Use extensions for casual confirmation prompts, but rely on containers or VMs when working with untrusted codebases or unattended automation.

Pi isn't going to make everyone abandon Claude Code, Codex, or Antigravity overnight—especially developers who want turn-key guardrails and zero configuration. But if you are tired of bloated interfaces dictating how you write software and want a fast, hackable terminal agent that works with any model you throw at it, Zechner’s minimalist harness is well worth a spin inside your next container.