Installing Pi

Pi is a terminal coding agent. You install it once globally, authenticate a model provider, then run pi inside any project.

Requirements

• A recent Node.js runtime (Node 18+ recommended).
• A terminal. Platform notes exist for Windows, Termux/Android, and tmux.

Install

The recommended install uses npm with lifecycle scripts disabled:

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

--ignore-scripts disables dependency lifecycle scripts during install. Pi does not require install scripts for normal npm installs.

There is also a one-line installer:

curl -fsSL https://pi.dev/install.sh | sh

Node version managers

If you use nvm, mise, asdf, etc., make sure the global install lands in a Node context that stays on your PATH. You can pin the npm command Pi uses for package installs via npmCommand in settings.json (see Installing packages).

Authenticate

Pi supports 15+ providers and hundreds of models. Two ways to authenticate:

API key — export the relevant variable, then run pi:

export ANTHROPIC_API_KEY=sk-ant-...
pi

Subscription (OAuth) — start Pi and log in interactively:

pi
/login   # then select your provider

Subscriptions include Anthropic Claude Pro/Max, OpenAI ChatGPT Plus/Pro (Codex), and GitHub Copilot. API-key providers include Anthropic, OpenAI, Azure OpenAI, Google Gemini/Vertex, Amazon Bedrock, Mistral, Groq, Cerebras, xAI, OpenRouter, Hugging Face, Together AI, and many more.

Switch models mid-session with /model (or Ctrl+L), and cycle favourites with Ctrl+P.

Your first session

Just talk to Pi. Out of the box the model has four tools: read, write, edit, and bash. Everything else — sub-agents, plan mode, web search, MCP — is added through the extensions and skills documented in this guide.

cd my-project
pi

Useful first commands:

Command	What it does
/model	Switch the active model
/settings	Thinking level, theme, message delivery
/reload	Reload extensions, skills, prompts, themes, context files
/hotkeys	List all keyboard shortcuts
/share	Upload the session as a shareable HTML gist

Project context

Pi loads AGENTS.md (or CLAUDE.md) at startup from ~/.pi/agent/, parent directories, and the current directory — use it for project conventions and common commands. You can also replace the system prompt per-project with .pi/SYSTEM.md.

Next step

Head to Installing packages to learn how to add capabilities with pi install.