Skip to content
Get packs

Guide · Open source

How to use Pi: install the coding agent and run it in a project

Updated · written with AI from the project's own documentation and checked against our catalogue data

Pi is an open-source agent harness that lets an AI model work on tasks, such as editing code in a project folder, from inside your terminal. This guide covers how to install the pi command, start it in a project, and understand what it does and does not include. After reading it, you will be able to run Pi on your own project and know where to look for customization and automation.

Piearendil-works/pi · ★ 119k · MIT

Quick start

  1. 1Check Node.js. Confirm you have Node.js 22.19 or newer, or let the installer add it.
  2. 2Install the CLI. Run the curl command on macOS or Linux, or the PowerShell command on Windows, or install with npm.
  3. 3Open your project. Change into the folder you want Pi to work in.
  4. 4Start Pi. Run pi from that folder to open the interactive session.
  5. 5Connect a provider. Run /login inside Pi to connect a subscription or API key.
  6. 6Give a task. Describe the change you want in plain language and review what Pi does.
  7. 7Update later. Run pi update to update an installer-based install.

What you need before you install Pi

Pi requires Node.js 22.19 or newer. The macOS, Linux and Windows installers can install Node.js for you if it is missing.

Pi works in a terminal. It is built for developers and is not a point-and-click desktop app.

  • Node.js 22.19 or newer, or let the installer add it
  • A terminal on macOS, Linux or Windows
  • An API key or a subscription for a built-in AI provider, connected through /login inside Pi

Install the pi command on macOS, Linux or Windows

The recommended route is the official installer. The installer pins all dependencies, and you update Pi later with pi update.

If you prefer npm, you can install the same package directly. The npm install does not pin transitive dependencies, so the installer is the more reproducible choice.

  • macOS or Linux: run the curl command below
  • Windows: run the PowerShell command below
  • Via npm: install @earendil-works/pi-coding-agent globally with --ignore-scripts
curl -fsSL https://pi.dev/install.sh | sh

Start Pi in your project folder and connect a provider

Pi works on the directory you launch it from. Change into your project first, then start Pi.

For a built-in AI provider, run /login inside Pi to connect a subscription or API key. After that, give Pi a task in plain language.

  • Use cd to move into the project you want Pi to work on
  • Run pi to start it
  • Run /login inside Pi to connect a provider
cd /path/to/project pi

Choose how to run Pi: interactive, scripted or over RPC

You can use Pi interactively in the terminal. You can also automate it in print or JSON mode, control it over RPC, or build your own apps with the Pi TypeScript SDK.

The packages in the monorepo include @earendil-works/pi-ai, a unified multi-provider LLM API, and @earendil-works/pi-tui, a terminal UI library with differential rendering. Teams building their own agent apps can use these libraries directly.

  • Interactive: use Pi in the terminal session
  • Print or JSON mode: automate Pi in scripts
  • RPC: control Pi from another program
  • Pi TypeScript SDK: build your own agent app

Customize Pi with extensions, skills and packages

Pi is designed to be extended. You can add extensions, skills, prompt templates and themes. Bundle them as Pi packages and share them via npm or git.

Pi ships without sub-agents and plan mode. The README says you can ask Pi to build them or install a package that does it your way.

  • Extensions, skills, prompt templates and themes
  • Pi packages shared via npm or git
  • Sub-agents and plan mode are not included by default

Understand Pi's permissions before you run it

Pi has no built-in permission system for restricting filesystem, process, network or credential access. It runs with the permissions of the user and process that launched it.

If you need stronger boundaries, the README describes containerizing Pi with a Gondolin extension, plain Docker, or OpenShell. Read the containerization guide in the repository before running Pi on sensitive machines.

  • No built-in permission controls
  • Runs with the launching user's access
  • Options: Gondolin extension, plain Docker, or OpenShell

What people use it for

  • Editing code in a project folder from the terminal
  • Automating an agent in print or JSON mode
  • Controlling Pi over RPC from another program
  • Building a custom agent app with the Pi TypeScript SDK and unified LLM API
  • Adding your own extensions or skills for a specific workflow

Frequently asked questions

Is Pi free and open source?

Pi is released under the MIT licence and its source is on GitHub. The licence allows you to use and modify it, but any AI provider you connect may charge for its own usage.

What do I need to run Pi?

You need Node.js 22.19 or newer and a terminal. The installers can install Node.js for you if it is missing.

How do I install Pi?

On macOS or Linux, run the curl install script from pi.dev. On Windows, run the PowerShell installer. You can also install @earendil-works/pi-coding-agent globally with npm.

Does Pi have sub-agents or plan mode?

No. The README says Pi skips sub-agents and plan mode by default. You can ask Pi to build them or install a package that adds them.

Is Pi safe to run on my computer?

Pi has no built-in permission system and runs with the access of the user who launched it. For stronger isolation, the README describes running it in a container or sandbox.

How does Pi compare to Aider, Cline, OpenHands or Continue?

Pi is a terminal harness you can extend with your own extensions and skills, and it ships libraries for building agent apps. Aider, Cline, OpenHands and Continue are alternatives you can compare against your own needs, such as editor integration or permission controls.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Pi suits developers who want a terminal coding agent they can customize, or teams who want its TypeScript SDK and unified LLM API. Pick something else if you need built-in permission controls, a point-and-click app, or sub-agents and plan mode out of the box.

Install options & downloads