pi-map_
中文
← ~/guides

Getting Started with Pi

Last updated: Jul 27, 2026

$ pi –getting-started

Pi is an open-source terminal coding agent from earendil-works (originally created by Mario Zechner as pi-mono). It runs in your project directory, reads and edits files, executes shell commands, and streams everything through a fast TUI. This guide takes you from zero to a working first session.

Prerequisites

  • Node.js with npm — Pi is distributed as an npm package. (Pi can also build standalone Bun-based binaries for releases, but the normal install path is npm.)
  • A terminal that supports modern TUIs. See the official terminal setup notes if you use Windows Terminal, tmux, or an unusual emulator.
  • An LLM account: either a supported subscription (Claude Pro/Max, ChatGPT Plus/Pro, GitHub Copilot, xAI, OpenRouter) or an API key for any supported provider.

Install

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

The --ignore-scripts flag disables dependency lifecycle scripts during install; Pi does not need install scripts for normal npm installs. This is part of the project’s supply-chain hardening: direct dependencies are pinned and the published package ships a shrinkwrap file.

There is also a curl installer (which itself uses npm under the hood):

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

Verify the install:

pi --version

First launch

Start Pi in the directory you want it to work on:

cd /path/to/project
pi

Pi operates on your current working directory and can modify files in it. There is no built-in permission popup system — Pi runs with your user’s permissions — so work on a git-tracked tree (or use a checkpointing extension) if you want easy rollback.

On startup, the TUI shows a header listing loaded context files, prompt templates, skills, and extensions, then the message area and the editor where you type.

Authenticate

Pi supports two authentication styles.

Option 1: subscription login (OAuth)

Run /login inside Pi and pick a provider. Built-in subscription logins include:

  • Claude Pro/Max
  • ChatGPT Plus/Pro (Codex)
  • GitHub Copilot
  • xAI (Grok/X subscription)
  • OpenRouter (mints an API key billed from your OpenRouter credits)
  • Radius

Tokens are stored in ~/.pi/agent/auth.json and auto-refresh when expired. Use /logout to clear credentials.

Option 2: API key

Export an environment variable before launching, for example:

export ANTHROPIC_API_KEY=sk-ant-...
pi

Or run /login and choose an API-key provider to store the key in ~/.pi/agent/auth.json. Other common variables include OPENAI_API_KEY, GEMINI_API_KEY, DEEPSEEK_API_KEY, GROQ_API_KEY, XAI_API_KEY, and OPENROUTER_API_KEY. The full table — over 30 providers — is in the providers doc.

Your first session

Type a request and press Enter:

Summarize this repository and tell me how to run its checks.

By default Pi gives the model four tools: read, write, edit, and bash. Read-only tools grep, find, and ls can be enabled via tool options. The agent loops — model responds, calls tools, reads results, responds again — until the task is done.

Things worth trying immediately:

  • Reference files: type @ in the editor to fuzzy-search project files, or pass files on the command line: pi @README.md "Summarize this".
  • Run shell commands: !npm run lint runs a command and sends its output to the model; !!command runs it without feeding output back into context.
  • Paste images: Ctrl+V (Alt+V on Windows), or drag an image into a supported terminal.
  • Switch models: /model or Ctrl+L; Shift+Tab cycles the thinking level; Ctrl+P cycles through your scoped models.
  • Queue messages while it works: Enter queues a steering message, Alt+Enter queues a follow-up, Escape aborts.

Non-interactive mode

For one-shot prompts and scripting:

pi -p "Summarize this codebase"
cat README.md | pi -p "Summarize this text"
pi -p @screenshot.png "What's in this image?"

--mode json emits JSON event lines; --mode rpc speaks an RPC protocol over stdin/stdout for process integration.

Where things live

All user state is under ~/.pi/agent/:

  • settings.json — global settings (project-level overrides go in .pi/settings.json in the repo)
  • auth.json — OAuth tokens and API keys
  • sessions/ — saved sessions, organized by working directory
  • AGENTS.md — global instructions loaded into every session
  • extensions/, skills/, themes/ — auto-discovered resources
  • trust.json — saved per-project trust decisions
  • models-store.json — cached provider model catalogs

When a project contains .pi/settings.json or project extensions, Pi asks whether to trust the folder before loading them. Save the decision with /trust.

Updating

Pi can update itself:

pi update --self     # update the pi CLI only
pi update --all      # update pi and installed packages

If you installed via npm, plain npm update -g @earendil-works/pi-coding-agent also works. To uninstall: npm uninstall -g @earendil-works/pi-coding-agent — note this leaves ~/.pi/agent/ (settings, credentials, sessions) intact.

Further reading