Install Pi - your first agent in the terminal

Pi (a.k.a. pi-coding-agent) is a terminal agent by Mario Zechner. Unlike Claude Code or Cursor, Pi is deliberately minimal: a few hundred tokens of system prompt, four built-in tools - read, write, edit, bash - and otherwise an empty desk. Extension doesn't happen through a fat feature list, but through two simple mechanisms: an AGENTS.md file that Pi loads automatically, and so-called Skills, which you write yourself as Markdown files.

That same reduction is what makes Pi the most honest entry-level agent: you understand what happens because so little happens. And you understand how agents generally work because Pi puts no magic between you and the model.

By the end of this tutorial you'll have:

• Pi installed and your first conversation done
• Pi wired to an endpoint of your choice - local (Ollama) or free in the cloud (Groq, OpenRouter, Anthropic trial)
• Understood how Pi learns its behaviour from your AGENTS.md
• Written your first custom skill and run it
• Downloaded three ready-made example skills you can drop straight in

What is Pi, exactly?

Before installing, a quick picture of what Pi is and what it isn't.

Pi is a thin layer between you and a language model. You type a task in the terminal, Pi sends it to an LLM, the LLM either replies with text or calls one of the four tools. Pi executes the tool call (read a file, write a file, run a shell command), feeds the result back to the model, and the loop repeats until the task is done.

Pi is not a sealed-off coding bot. Despite the name coding agent, Pi works for any file-oriented task: keeping a journal, sorting notes, curating a newsletter, parsing CSVs, tidying photo folders, writing maintenance logs. Anything that lives as a file on your machine is fair game for Pi.

Pi is not automatically safe. Out of the box, Pi runs whatever command the model suggests. That's deliberate - but the security conversation belongs at the start, not the end, of the tutorial. More on that in step 7.

Step 1 - Install Pi

Pi is available as a one-liner installer or as an npm package. Both install the same thing.

Via installer script (recommended on macOS/Linux):

Via npm (all platforms, Node.js 18+):

Either path places a binary named pi on your PATH. Quick check:

Windows setup

Pi runs on Windows, but needs two extra pieces because Pi internally invokes Bash (its bash tool):

1. Install Git for Windows. It ships bash.exe, which Pi finds automatically (C:\Program Files\Git\bin\bash.exe). Download: git-scm.com/download/winExternal - Opens in a new tab - run the standard installer, defaults are fine.

At startup, Pi looks for a Bash in this order:

1. A custom path in ~/.pi/agent/settings.json (field shellPath)
2. Git Bash (C:\Program Files\Git\bin\bash.exe)
3. Any bash.exe on PATH (Cygwin, MSYS2, WSL)

Git Bash works for the vast majority of cases. If you prefer WSL, install Pi inside WSL - the Linux path (curl … | sh) applies there.

2. Install Node.js. Easiest via the official installer at nodejs.orgExternal - Opens in a new tab (LTS). After install, check in Windows Terminal (see below): node --version and npm --version.

Then install Pi with the same npm command from above, either in PowerShell or Git Bash:

Step 2 - Choose an endpoint

Pi is only the shell. The actual thinking is done by a language model that you wire up. You have three realistic ways to start completely for free:

Option A - Local with Ollama (recommended, no account needed)

If you've gone through the Ollama tutorial and the Hermes tutorial, you already have a local endpoint on http://localhost:11434. Pi talks to it directly - you only need to tell Pi where the model lives.

Create the following file (or download the example models.json below):

apiKey is required by the spec; Ollama ignores the value. The compat block is important: several OpenAI-compatible servers (Ollama, vLLM, SGLang) don't understand the developer role marker and the reasoning_effort field that Pi otherwise sends - both flags false switches that off.

Option B - Free in the cloud with Groq

If you don't have a powerful machine, or simply want to try something quickly: Groq offers a generous free tier with no credit card. You get 30 requests/minute and 14,400 requests/day per model - more than enough for learning - and Groq is extremely fast (500-800 tokens per second because they run dedicated inference chips, so-called LPUs).

1. Sign up at console.groq.comExternal - Opens in a new tab (email address is enough).
2. Create a new key under API Keys.
3. Export the key:

Groq is a built-in provider in Pi. After launch, pick a model with /model. Good free models for agent tasks:

• llama-3.3-70b-versatile - general-purpose, very stable on tool-use.
• llama-3.1-8b-instant - faster, lighter, good for short tasks.

Option C - Anthropic trial (Claude)

If you have an Anthropic account (even without an active Pro plan, signup gives trial credits), Pi works out of the box with Claude:

Alternatively log in via OAuth from Pi directly with /login if you hold a Claude Pro or Claude Max subscription.

Step 3 - First conversation

Start Pi simply with:

On first run you'll see a welcome, a status bar at the bottom (working directory, current session, loaded AGENTS.md, selected model), and an input cursor.

Switch to the model you set up - shortcut Ctrl+L or the command /model. Then type a task:

You'll see Pi think (brief status), then the planned tool call (write), the path, and the content. No confirmation was required in default mode - Pi writes directly.

It looks unspectacular but this is the core. A model autonomously decided write was the right tool, formulated the arguments, and Pi executed the call. That is an agent.

Step 4 - Understand AGENTS.md

Pi puts almost nothing into its system prompt. What Pi always loads is an AGENTS.md file. In fact several, concatenated top to bottom:

1. ~/.pi/agent/AGENTS.md (global, applies everywhere)
2. AGENTS.md in every parent folder (from the current directory walking up to home)
3. AGENTS.md in the current folder

That's a quiet but powerful mechanism: you can drop a separate behaviour codex per life area (~/Clients/X/AGENTS.md, ~/Journal/AGENTS.md) without flipping switches or configuring anything. Pi finds the file and respects what's in it.

Create your global file:

A good starting content - you can also download the example AGENTS.md below and adapt it:

Restart Pi (or /reload in the running session) and try something you had done before:

Pi should now first briefly explain what it's about to do, instead of writing immediately. You've retrained Pi with a single Markdown file. That's the lever.

Step 5 - Your first skill

A skill is a Markdown file that captures a chunk of task knowledge. When your prompt matches what's described in the skill header, Pi loads the skill's content into context only then (Pi-speak: progressive disclosure). That saves tokens and keeps the model focused.

Skills follow an open standard at agentskills.ioExternal - Opens in a new tab. In Pi, each skill lives in its own folder with a SKILL.md inside:

Content of the SKILL.md (or download SKILL-journal.md from the downloads and rename it):

/reload inside the running Pi, or restart Pi. The startup screen now lists "skills: journal". Try it:

Pi spots the word journal, loads the skill, may ask for missing details (weather, tags), then writes ~/Journal/2026-05-10.md in the agreed structure. You can also force the skill explicitly with /skill:journal.

Step 6 - Skills for your everyday work

We've prepared three production-ready skills as downloads. Each file ships with instructions for which folder it belongs in as SKILL.md:

• Journal skill - the one shown above, in full length.
• Meeting notes skill - turns a transcript or bullet list into a structured meeting note with - [ ] task lists that you can later filter with ripgrep.
• Newsletter curation skill - groups stored articles by theme and writes a 4-sentence framing per cluster.

Download them below, create a folder under ~/.pi/agent/skills/<name>/ for each, and rename the file to SKILL.md.

Step 7 - Think about safety first

By default, Pi runs every tool call immediately. That's deliberate - Pi's author considers confirmation popups a source of attention erosion. But you should know what you're dealing with:

• bash is powerful. A hallucinated rm -rf ~/important is as quick to execute as a harmless ls.
• write overwrites. Pi can replace an existing file if it believes the task requires it.
• AGENTS.md is your first line of defence. Put your non-negotiables there ("never read .env", "always ask before rm") - the model takes those rules seriously.

For the start, three safeguards are enough:

1. Only run Pi in folders where you could afford to lose files without anything bad happening. Never in ~/, never in a git repo with uncommitted changes you can't recover.
2. Version important folders (git init and frequent git commit). Any Pi mistake becomes a git restore.
3. Set this rule in your global AGENTS.md: "Before rm, mv, git push, git reset --hard, or creating files outside the current folder: always ask first." Pi obeys this very reliably in practice.

Step 8 - Turn off telemetry and update checks (optional)

On startup, Pi pings two endpoints: one for version checks, one for anonymous install/update telemetry. You can disable either or both - via environment variables or globally via settings.json.

In addition or alternatively, in your shell:

For local-only setups, PI_OFFLINE=1 is the clean switch. Pi works fully offline then - assuming your model is local too.

Step 9 - Sessions, branches, resume

Every Pi conversation is automatically stored under ~/.pi/agent/sessions/ as a JSONL file. That has two useful consequences.

First - resume. Closing Pi and picking it up later is trivial:

Second - branches. A Pi session isn't linear, it's a tree. With the command /tree (or Escape twice) you open the tree navigator and can jump to any earlier point of the session - without losing the rest. Typing a new message after that creates a new branch.

That's the Pi way of asking "what if I'd phrased question X differently?". For a consulting setup, a conflict prep, or an experimental architecture discussion, that's pure gold - no need to start over.

Step 10 - Print mode for scripts and cron jobs

Pi doesn't have to run interactively. With -p (for print) you get a single response and an exit code:

That opens the door to automation: a nightly cron job that prepares your weekly reflection; a git hook that lets Pi suggest commit messages; a script that pulls action items out of inbound emails.

In print mode, Pi also reads standard input - so you can hang Pi into Unix pipes:

Done - what's next?

Three directions to go next:

• Write more skills. Any task you do three times a week is a skill candidate. Write the skill the next time you do it manually.
• Compare models. Use /model to switch between a small local model and a cloud model and see where the difference really matters (hint: rarely on structured tasks, dramatically on creative writing).
• Tailor Pi per area. Put an AGENTS.md in every life folder - ~/Clients/<company>/AGENTS.md, ~/Family/AGENTS.md, ~/Projects/<repo>/AGENTS.md. Pi automatically switches behaviour as you cd around.

Troubleshooting

"command not found: pi" - either the global npm bin is not in PATH, or the installer script put the binary somewhere else. Check npm config get prefix and add $(npm config get prefix)/bin to your PATH if needed.

"Provider … not authenticated" - the env variable name must match exactly (ANTHROPIC_API_KEY, GROQ_API_KEY, OPENAI_API_KEY, …). Pi reads the variable at startup, not during the session - open a fresh shell or restart Pi after export.

Reply arrives but no tool use - small models (e.g. llama3.2:3b) often answer in plain text instead of calling tools. Switch to a larger or explicitly tool-trained model (hermes3:8b, qwen2.5-coder:7b, llama-3.3-70b-versatile on Groq).

Pi doesn't find AGENTS.md - ~ is expanded by the shell, not by Pi. If you create the file from a script, use $HOME/.pi/agent/AGENTS.md instead of ~/.pi/agent/AGENTS.md.

Skill isn't loading - three common causes: (1) the file isn't named exactly SKILL.md, (2) the skill folder isn't directly under ~/.pi/agent/skills/, (3) the "When to use" section is too vague. Make the trigger explicit with keywords the user is likely to type.

Ollama connection fails - verify in another terminal that curl http://localhost:11434 returns "Ollama is running". If you use a non-default port, update the baseUrl field in models.json accordingly.