How to Use Pi Agent: A Beginner-Friendly Tutorial from Installation and Configuration to Automated Workflows
If you're searching for how to use Pi Agent, you've come to the right place. Pi Agent is a general-purpose AI Agent built on a "minimal core" design. Unlike bloated software, it puts the choice in your hands: install whatever Skill (capability) you need.
Whether it's searching for information, reading PDFs, organizing spreadsheets, or making PPTs, Pi handles it all with ease. This article will walk you through the core usage of Pi Agent in 5 minutes, with plenty of illustrations.
# 📑 Table of Contents
- 1. Prerequisites
- 2. What Is Pi Agent?
- 3. Core Tutorial: How to Use Pi Agent
- 4. Hands-On Practice: Generate a PPT with One Sentence
- 5. Pi's Design Philosophy: Extend on Demand
- 6. Common Shortcuts and High-Frequency Commands
- 7. FAQ (Frequently Asked Questions)
1. Prerequisites
Before you start exploring how to use Pi Agent, make sure your computer environment meets these basic requirements:
- Node.js 20+: The latest LTS version is strongly recommended.
- AI model service: Prepare a usable API Key (e.g., DeepSeek, Claude, OpenAI), or have a platform subscription account (e.g., Claude Pro, ChatGPT Plus).
- Project directory: We recommend launching Pi from your project root directory — it will automatically read and manage local files.
2. What Is Pi Agent?
On OpenRouter's latest token consumption leaderboard, Pi holds a solid fifth place, right behind OpenClaw.
The secret behind Pi's rise is "low consumption, high frequency." For tasks of the same scale, Pi often consumes less than one-third of the tokens that Claude Code does. This shows that a large number of users are using it frequently to automate tedious daily work.
# Core Comparison: Pi Agent vs Claude Code
| Dimension | Pi Agent | Claude Code |
|---|---|---|
| Core positioning | Getting everyday office and work tasks done | Writing code, delivering software projects |
| Pre-installed capabilities | Minimal: read files, write files, modify files, run commands | Complex: code indexing, testing, Git operations, and other dev tools |
| How it's extended | Install Skills on demand | Extend via MCP / Hooks |
| Target users | Anyone with everyday office or automation needs | Professional programmers, developers |
| Typical scenarios | Researching information, reading documents, processing spreadsheets, making PPTs | Writing features, fixing bugs, code review |
Core takeaway: If you want to boost your coding productivity, choose Claude Code; but if you want to solve the efficiency problems of your daily workflow, Pi Agent is definitely the best choice.
3. Core Tutorial: How to Use Pi Agent
Next, we'll walk through how to use Pi Agent step by step — you can complete the environment setup in just 5 minutes.
# Step 1: One-Click Installation
Open your terminal and run the install command directly:
curl -fsSL https://pi.dev/install.sh | sh
Tip: After installation, all configuration files, session records, and downloaded Skills are safely stored together in the
~/.pi/agent/directory on your computer.
# Step 2: Launch and Log In
Use the cd command to enter the directory you want to work in, then run the following command to launch:
pi
After launching, type /login and the system offers two login modes:
- Method 1: Subscription login — If you're already a paid user of Claude Pro or ChatGPT Plus, pick the corresponding provider and authorize in your browser as prompted.
- Method 2: API Key (recommended) — Best for users who have their own API keys; this method manages Secrets more safely and efficiently.
# Step 3: Configure Your LLM
After logging in successfully, type /model (or use the shortcut Ctrl+P) to bring up the model selection panel.
- You can use
Shift+Tabto quickly switch the "Thinking Level" of a model. - Taking DeepSeek as an example: select DeepSeek from the list and fill in the DeepSeek API key you applied for.
# Step 4: Start Your First Conversation
Everything is ready! Now you can give Pi instructions directly in the terminal, just like using a messaging app.
4. Hands-On Practice: Generate a PPT with One Sentence
Not sure how to put Pi Agent to work for a specific task? Let's look at this classic example of generating a presentation.
# 1. Install the PPT-specific Skill
Type the install command in the chat:
pi install git:github.com/op7418/guizang-ppt-skill
# 2. Give a Natural-Language Instruction
No need to write complex code — just tell Pi what you want in plain human language:
"Make me a PPT introducing the scenery of Nanjing"
Pi Agent will intelligently analyze your request and draft an outline for you. Once you confirm the design style and theme colors, it automatically moves into the generation phase.
# 3. Check the Final Result
The image below shows the text-only PPT that Pi generated automatically based on your instruction (advanced users can refine the prompt to further improve the visual presentation).
5. Pi's Design Philosophy: Extend on Demand
Most agents on the market are frantically adding features, but Pi Agent chose to subtract.
Its core provides only four indispensable capabilities: read files, write files, modify files, and run commands. Beyond that, it's completely blank — because Pi's vision is to let you build an agent that fits your own work habits perfectly:
- Researchers and academics: install the PDF parsing and web search Skills.
- Admin and operations folks: install the Excel and data-processing Skills.
- Content creators: install Hyper Frames for video processing, or Edge TTS for speech synthesis.
- Designers: install image-generation Skills like GPT Image 2.
As Pi's official documentation puts it:
"Adapt Pi to your workflows, not the other way around."
6. Common Shortcuts and High-Frequency Commands
Mastering the following shortcuts and slash commands can double your operating efficiency.
# High-Efficiency Shortcuts
| Function | How to use it |
|---|---|
| Precise file reference | Type @ for fast fuzzy search of files in the project |
| Automatic path completion | Press Tab to quickly complete the current path |
| Safe multi-line input | Shift + Enter (use Ctrl + Enter in Windows Terminal) |
| One-click image paste | Ctrl + V (Alt + V on Windows), or drag an image directly into the terminal window |
| Run system commands | !command (after running, the output is sent to the AI model for analysis) |
| Silent system commands | !!command (after running, the output is not sent to the AI model) |
| Invoke an external editor | Ctrl + G to quickly open the system default $VISUAL or $EDITOR |
# Core Slash (/) Commands
Type / in the input box to bring up the command menu:
| Command | What it does |
|---|---|
/model | Quickly switch the AI model used in the current conversation |
/settings | Configure thinking levels, UI theme, and data transfer protocol in depth |
/resume | Find and resume previous work sessions |
/new | Clear the context immediately and start a brand-new session |
/session | View the current session's status, token consumption, and estimated cost |
/compact [prompt] | Manually compress a long context (you can append a custom instruction to keep) |
/export [file] | Export the current conversation as a beautifully formatted HTML file |
/reload | Reload the configuration to fix newly installed Skills that aren't taking effect |
/quit | Exit Pi Agent safely |
7. FAQ (Frequently Asked Questions)
# 1. Is Pi Agent completely free?
Yes. The Pi Agent client itself is open-source and completely free. However, the inference APIs for large language models (e.g., DeepSeek, GPT-4) are not free. You need to bind your own API Key or subscription account, and the token fees are charged by the corresponding model providers.
# 2. I installed a new Skill but it doesn't work. What should I do?
If a newly installed Skill doesn't trigger, first type /reload in the chat to reload the environment. If it still doesn't work, check the ~/.pi/agent/ directory to confirm the files were downloaded successfully.
# 3. How do I switch models for different scenarios?
It's very simple. Just type /model in the chat box to bring up the model menu and switch freely. For simple copy-polishing tasks, you can use a basic model to save money; for complex logical analysis, switch to a flagship reasoning model.