Pi Agent Quick-Start Guide
Pi Agent is a general-purpose AI agent with a minimal core. It extends its capabilities by installing Skills on demand, and it focuses on automating daily workflows rather than writing code. Whether it's searching for information, reading PDFs, organizing spreadsheets, or building a PPT — whatever Skill you install is what it can do.
📚 Table of Contents (click to jump)
- Prerequisites
- What Is Pi Agent?
- Get Started in 5 Minutes
- Hands-On: Build a PPT with Pi
- Pi's Design Philosophy: Minimal Core + Skills on Demand
- Common Shortcuts
- Common Slash Commands
- Pros and Cons
- Who It's For
- FAQ
Prerequisites
Before you begin, make sure your environment is ready:
- Node.js 20+ (the latest LTS is recommended)
- A working AI model API key (e.g., DeepSeek, Claude, OpenAI), or a subscription account (Claude Pro, ChatGPT Plus)
- A project directory (we recommend launching Pi in your project root so it can read local files automatically)
What Is Pi Agent?
On OpenRouter's leaderboard, Pi's daily token usage ranks fifth, right behind OpenClaw.
More importantly, Pi works on "low consumption, high frequency." For a task of the same scale, Pi uses only about a third of the tokens that Claude Code would — yet its total usage still ranks in the top six. That tells you a lot of people are using it frequently for everyday work.
What's the difference between Pi and Claude Code?
| Dimension | Claude Code | Pi Agent |
|---|---|---|
| Core purpose | Write code, ship software | Complete everyday work tasks |
| Preinstalled abilities | A full set of dev tools: code index, test running, Git, coding standards | Just four base abilities: read files, write files, edit files, run commands |
| How to extend | Via MCP / Hooks | Via Skills installed on demand |
| Target users | Developers | Anyone with daily productivity needs |
| Typical scenarios | Writing features, fixing bugs, doing code review | Research, reading PDFs, organizing spreadsheets, writing reports, making PPTs |
In one sentence: Claude Code solves development efficiency; Pi solves workflow efficiency. Not everyone writes code every day, but everyone has chores to handle every day.
Get Started in 5 Minutes
Step 1: Install
Run this in your terminal:
curl -fsSL https://pi.dev/install.sh | sh
Once installed, all config, session records, and Skill packages live in the ~/.pi/agent/ directory.
Step 2: Launch and log in
Launch Pi in your project directory:
pi
Type /login to log in. You have two options:
Option 1: Subscription login (if you already have Claude Pro, ChatGPT Plus, etc.)
Type /login, select a provider, and follow the authorization prompts.
Option 2: API key (recommended; easier to manage Secrets)
Step 3: Pick a model
After logging in, type /model or press Ctrl+P to open the model picker. Press Shift+Tab to switch the thinking level.
Using DeepSeek as an example: select DeepSeek, then enter your DeepSeek API key to start chatting.
Step 4: Start chatting
Once configured, you can talk to Pi directly.
Hands-On: Build a PPT with Pi
Install a PPT Skill, describe what you need in one sentence, and Pi builds a PPT from scratch for you.
Install the PPT Skill
pi install git:github.com/op7418/guizang-ppt-skill
Generate a PPT in one sentence
Just tell Pi what you want:
Make a PPT introducing the scenery of Nanjing
Pi first analyzes the request and lists an outline; you confirm the style and theme color, then it starts generating.
The result
Below is the plain-text version generated directly (for better visuals, you'd tune the prompt and parameters further).
Pi's Design Philosophy: Minimal Core + Skills on Demand
Pi Agent's core idea is the opposite of most agents: everyone else is adding; Pi is subtracting.
Its core keeps only four base abilities: read files, write files, edit files, run commands. Nothing else is preinstalled.
Why design it this way? Because Pi wants you to build an Agent that is your own:
- A researcher → install a PDF-reading and search Skill
- An office worker → install a spreadsheet Skill
- Want to make videos → install Hyper Frames
- Want it to speak → install Edge TTS
- Want image assets → install GPT Image 2
Install one Skill and the Agent gains one more ability. Every Pi in everyone's hands looks different.
Pi's official site puts it precisely:
There are many different agents out there, but this Pi Agent is your own Agent.
Core principle:
Adapt Pi to your workflows, not the other way around
Common Shortcuts
| Feature | How |
|---|---|
| Reference files | Type @ to fuzzy-search project files |
| Path completion | Press Tab to complete paths |
| Multi-line input | Shift + Enter (use Ctrl + Enter in Windows Terminal) |
| Paste images | Ctrl + V (Windows: Alt + V), or drag an image into the terminal |
| Run shell commands | !command (output is sent to the model) |
| Hide shell commands | !!command (output is not sent to the model) |
| External editor | Ctrl + G opens $VISUAL or $EDITOR |
Common Slash Commands
Type / in the conversation to open the command completion menu.
| Command | Description |
|---|---|
/model | Switch models |
/settings | Configure thinking level, theme, message delivery, transfer protocol |
/resume | Pick and continue a previous session |
/new | Start a new session |
/name <name> | Set the session's display name |
/session | Show session file, ID, message count, tokens, and cost |
/tree | Jump to any node in the session tree and continue |
/fork | Create a new session from an earlier user message |
/clone | Copy the current active branch into a new session |
/compact [prompt] | Manually compress context (with optional custom instructions) |
/copy | Copy the last assistant message to the clipboard |
/export [file] | Export the session as HTML |
/reload | Reload shortcuts, extensions, skills, prompts, and context files |
/hotkeys | Show all keyboard shortcuts |
/changelog | Show version history |
/quit | Exit Pi |
Pros and Cons
Pi Agent's strengths
- Minimal core: only four base abilities preinstalled — nothing bloated, easy to pick up
- On-demand expansion: install a Skill and it learns a new ability; every Pi is different
- Low consumption, high frequency: a task of the same scale uses about a third of Claude Code's tokens
Limitations / things to note
- Capabilities depend on Skills: without installing any, it can only read, write, edit, and run commands
- You bring the model: an API key or subscription is on you, and usage is billed by the model provider
- Built for daily tasks: complex software engineering is better served by developer-focused agents
Who It's For
- Non-developers with daily chores (research, reading PDFs, spreadsheets, reports, PPTs)
- People who want a personal "Agent of your own" and are happy to extend it with Skills
- Users who want low-cost, high-frequency AI for workflow automation
FAQ
What's the difference between Pi Agent and Claude Code?
Claude Code is for developers writing code, with code index, testing, and Git tools preinstalled. Pi Agent is for everyone doing daily tasks: its core is minimal and its capabilities come from installing Skills on demand. See the comparison table above.
Is Pi Agent free?
Pi Agent itself is an open-source tool and costs nothing. You provide your own model API key or subscription account; usage fees are charged by the model provider.
Which models does Pi Agent support?
Pi supports many models; view and switch them with the /model command. Common options include DeepSeek, Claude, and OpenAI models.
Why doesn't my Skill take effect after installing it?
Confirm the install path is correct, then run /reload. If it still doesn't work, check whether the Skill file exists under ~/.pi/agent/.