Install, First Session, First Task

Before you can write for an agent, you have to run one. This chapter gets you from nothing to a session with real work in it, and then spends most of its length on the part that is actually hard: giving the agent a task it can finish.

Install

On macOS or Linux, Pi has an installer:

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

Or install from npm, which requires Node.js 22.19 or newer:

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

Pi does not require dependency lifecycle scripts for a normal npm installation, which is why --ignore-scripts is there.

Verify it:

pi --version

There is a separate setup path for native Windows, and another for Android under Termux. If you are on either, read the corresponding document before continuing — the differences are in shell selection and storage, not in the agent loop.

The working folder is not a detail

This is the step people skip, and it changes more than you would expect.

cd /path/to/folder
pi

The working folder does three things. It helps Pi discover relevant files, instructions and configuration. It is where Pi looks for context files that apply to what you are working on. And it is how Pi groups saved sessions, which is what makes pi --continue resume the right conversation.

Start Pi in the right directory. A session started in your home directory and a session started in the repository you are working on are not the same session, and they do not see the same instructions.

Authenticate

Inside Pi:

/login

Choose a provider and follow the prompts — use a subscription, or store an API key. Then:

/model

searches available models and shows the ones whose providers have usable authentication. Press Ctrl+S on a model to save it as the default for new sessions.

If you would rather not have Pi write credentials at all, set the provider’s environment variable instead. That is the right choice in CI, and it is also the lowest-priority source: when several credential sources are configured, the one you just exported is often shadowed by a stored one. Chapter 3 gives the exact order.

Give it a task

Pi shows each file read, each search, each command and each edit it performs. It does not ask before every tool call. This is worth saying plainly, because it is the single most important operational fact for anyone running an agent on a real machine.

Some tasks that work well:

Summarize @meeting-notes.md and save the action items to action-items.md.

Explain how this repository is structured and how to run its checks.

Compare @previous.csv with @current.csv and summarize the important changes.

Type @ in the editor to search for a file instead of typing its path.

Then, when Pi finishes, review its response and any changed files. Use version control or backups for important work. For untrusted or unattended work, use a container or another sandbox.

That paragraph is not boilerplate from the documentation. It is the operating contract, and chapter 36 is the chapter that explains what is actually at stake in it.

A first session you can build on

The next chapters build extensions, skills and packages, and Part II is where that starts in earnest. You want a project to build them in — something disposable, with one small thing in it. The smallest useful example is a directory with a .pi/ in it:

my-agent/
├── APPEND_SYSTEM.md      project instructions, appended to the system prompt
├── settings.json         project settings: tools and resources
└── prompts/
    └── review.md         a reusable prompt, available as /review

Pi will ask for project trust the first time. Grant it, and Pi discovers .pi/extensions, .pi/skills and .pi/prompts. Chapter 8 is about what that trust decision actually does, and it is worth understanding before you grant it again.

While you are in there, run this once:

pi config

It shows the discovered resources and pi’s built-in extensions and lets you enable or disable them. When something does not appear, this is the first command to run — far more often than it should be necessary to read the source.

Continue later

Sessions save automatically. To resume the most recent session for the same working folder:

pi --continue

Use /resume to choose another saved session.

Why the first task matters so much

Look at the three examples again. None of them say how to do the job. Each says what the finished thing looks like, names the material, and names where the output goes.

Compare that with the most common first prompt of all:

Fix the bug.

There is nothing wrong with that prompt. It is simply a different request: it delegates the definition of the task as well as the execution, and it does so in a context where the agent has just started and knows nothing about this repository, this codebase’s conventions, or what “fixed” means here.

Three habits worth forming now:

Name the material. @file, a directory, a test suite. The agent can find things, but you know which things are relevant.

Say what the output should be. A file, a diff, a table, a single number in the editor. “Summarise” leaves the format open; “save the action items to action-items.md” does not.

Let it look first. Asking for an explanation of the repository before asking for a change in it is cheap, and it puts the agent’s understanding in front of you while it is still wrong and easy to correct.

Chapter 10 makes this argument at length, because it is the highest-leverage skill in the book and the one with the shortest feedback loop. You can practise it today, before writing a line of extension code.

What just happened

In four commands you started a process, authenticated it, gave it a folder to work in, ran a task, and resumed it later. Everything the rest of this book describes — the extension runtime, the skill router, the settings precedence chain, the session file — operates inside that process, on that conversation, in that folder.

Next

You have a loop that runs and something running inside it. What you do not yet know is what the loop is running on. Model, provider, credential, thinking level and cache state sit underneath every mechanism in this book and produce symptoms that look exactly like bugs in the layer above, so they are the next thing to get right.

Chapter 3: models, providers and thinking level.