Pi is an open-source coding agent for the terminal. It can inspect a project, edit files, and run commands using a model provider you choose. You can add project instructions and reusable workflows, or extend Pi itself.
Pi fits developers who want an agent to work with their tools and habits. You also decide which extensions and permissions to trust.
Where Pi helps#
Pi can help with repository tasks such as:
- Explore an unfamiliar codebase and find the relevant files.
- Make a focused change, then run the project’s tests or checks.
- Explain a diff, draft tests, or trace a bug through logs and source code.
- Reuse project instructions and task-specific workflows.
- Automate tasks from scripts or embed Pi in another application.
Pi is a terminal interface to a language model. Its built-in feature set is small and does not include sub-agents or plan mode. Add those through extensions or packages if you need them.
Install and connect a model#
Install Pi on macOS or Linux with:
curl -fsSL https://pi.dev/install.sh | shThe installer pins Pi’s dependencies and can install Node.js if needed. The npm option requires Node.js 22.19 or newer, but does not pin transitive dependencies:
npm install -g --ignore-scripts @earendil-works/pi-coding-agentBoth commands appear in the official quickstart. The installer runs a downloaded script, so inspect its source before running it. The quickstart also covers Windows and Nix.
Pi needs a supported model. Connect through a provider account, an API key, or a local model. Then start Pi from the project directory:
cd /path/to/project
piAt the prompt, run /login and follow the instructions. Use /model to select an available model. Authentication and cost vary by provider, so check its terms and pricing.
Get useful results from the first session#
Give Pi the repository context#
Start Pi from the repository root. It uses that directory to find project instructions and group saved sessions. State the task, any constraints, and how you plan to check the result:
Find why the parser rejects trailing commas. Trace the current behavior,
make the smallest compatible fix, add a regression test, and run the
parser tests. Do not change the public API.For a smaller task, type @ in the prompt editor to find and add a file. Naming the relevant files and saying how you will verify the change is more useful than writing a long, generic prompt.
Keep durable instructions in the repository#
Put recurring project guidance in an AGENTS.md file. Describe the project, useful commands, and constraints for future tasks. Pi loads context files from its agent directory, the working directory, and its parent directories. Keep the instructions short and factual; outdated guidance can mislead the model.
For instructions that should apply across projects, add context files to Pi’s agent directory.
Check the work, not just the explanation#
Pi shows its tool calls and results, but does not ask before each one. Review the diff, then run the project’s tests, formatter, or type checker. If a test fails, share the output with Pi and ask it to investigate.
Prefix a command with ! to send its output to Pi:
!git statusBefore a large edit, make sure you can recover your work with version control or a backup.
Continue or compare approaches#
Pi saves sessions automatically. Run pi --continue from the same directory to reopen the latest session, or use /resume to choose another. Use /tree or /fork to try another approach without losing the current conversation. If a session gets long, /compact reduces older context.
Use /model or Ctrl+L to change models. The terminal usage guide covers the editor, queued messages, session commands, and shortcuts.
Customize Pi as needed#
Choose the simplest option that fits the task:
| Need | Pi feature |
|---|---|
| Persistent project guidance | AGENTS.md |
| A reusable prompt you invoke by name | Prompt template |
| Task-specific instructions and supporting files | Skill |
| New executable tools, commands, or event handlers | Extension |
| Share several customizations together | Pi package |
Create a prompt template for a review checklist you use often. Use a skill for tasks that need detailed instructions or supporting files. Choose an extension when you need executable behavior.
Extensions run inside Pi with the same operating-system permissions. Packages can contain extensions or skills that run programs. Check unfamiliar sources before installing or loading them. A package name or project trust prompt does not tell you whether its code is safe.
Pi also has print/JSON, RPC, and SDK modes for scripts and applications. The CLI documentation lists the options for your installed version.
Know what Pi can access#
Pi can read and change files and run commands with the permissions of the account that started it. The working directory guides where Pi looks, but does not limit commands to that directory. See Pi’s security guide for project trust, prompt injection, and isolation.
To limit the risk:
- Give Pi access only to the files and credentials it needs.
- Keep secrets out of prompts and project instructions.
- Check unfamiliar extensions, skills, and packages before enabling them.
- Run untrusted code or unattended tasks in a container or another isolation boundary.
- Review a session before sharing or exporting it. It may contain prompts, source, command output, or secrets.
Is Pi right for your workflow?#
Pi suits developers who prefer the terminal and want to choose a model provider or adapt the workflow. If your process depends on sub-agents or plan mode, you will need an extension or package. Try Pi first on a small task in a repository you know.
