Quick Start

Get Pi running in minutes and start building with AI assistance

Install Pi

Pi is distributed as an npm package and requires Node.js 20 or later.

1. Install Pi globally

   npm install -g @mariozechner/pi-coding-agent
   

   This makes the pi command available system-wide.

2. Set up authentication

   Choose one of two authentication methods:

   API Key (Simple)

   Set an environment variable for your preferred provider:

   export ANTHROPIC_API_KEY=sk-ant-...
   

   Add this to your ~/.bashrc or ~/.zshrc to make it permanent.

   Supported providers:

   • ANTHROPIC_API_KEY - Anthropic
   • OPENAI_API_KEY - OpenAI
   • GEMINI_API_KEY - Google Gemini
   • GROQ_API_KEY - Groq
   • MISTRAL_API_KEY - Mistral
   • And many more

   Subscription (OAuth)

   If you have a subscription to Claude Pro, ChatGPT Plus, or GitHub Copilot:

   pi
   /login
   

   Then select your provider from the menu. Credentials are saved to ~/.pi/agent/auth.json and auto-refresh.

3. Launch Pi

   pi
   

   You’ll see the interactive terminal interface with an editor at the bottom.

4. Start coding

   Type your request and press Enter:

   List all TypeScript files in this directory
   

   Pi will use the built-in tools (read, write, edit, bash) to fulfill your request.

Your First Session

Let’s walk through a typical Pi session:

Terminal

# Start Pi in your project directory
cd ~/my-project
pi

# Pi loads and shows the interface
# Type your first message:
"Create a simple HTTP server in Node.js that responds with 'Hello World'"

# Pi will:
# 1. Create a new file (server.js)
# 2. Write the code
# 3. Show you what it did

# Continue the conversation:
"Add a /status endpoint that returns JSON"

# Pi edits the existing file and shows the changes

Sessions auto-save to ~/.pi/agent/sessions/ organized by working directory. Use pi -c to continue your most recent session.

Essential Commands

Type / in the editor to see all commands. Here are the most useful:

Command	Description
/model	Switch between LLM models
/settings	Adjust thinking level, theme, and more
/tree	Navigate session history and branches
/copy	Copy last assistant message to clipboard
/hotkeys	Show all keyboard shortcuts
/quit	Exit Pi

Essential Keyboard Shortcuts

Key	Action
Ctrl+L	Open model selector
Ctrl+P / Shift+Ctrl+P	Cycle through models
Shift+Tab	Cycle thinking level (off → minimal → low → medium → high → xhigh)
Escape	Cancel current operation
Escape twice	Open session tree view
Ctrl+C	Clear editor (press twice to quit)
Ctrl+O	Collapse/expand tool output
@	Fuzzy-search and reference files

Use Shift+Enter (or Ctrl+Enter on Windows Terminal) for multi-line input.

File References

Include files in your messages using the @ symbol:

@src/server.ts Review this file for security issues

Type @ and start typing to get fuzzy-search suggestions. You can reference multiple files:

@package.json @README.md Update the dependencies and document the changes

Running Bash Commands

Prefix commands with ! to run them and send output to the LLM:

!ls -la src/

Use !! to run without sending output:

!!npm install lodash

Session Management

Continue Previous Session

pi -c

Resumes the most recent session for the current directory.

Browse All Sessions

pi -r

Opens an interactive picker to select from past sessions.

Branch from History

Inside Pi, press Escape twice to open the session tree. Navigate to any point in history, then:

• Press Enter to continue from that point
• Type /fork to create a new session file from that branch

Export or Share

/export my-session.html

Creates a standalone HTML file with your session.

/share

Uploads your session as a private GitHub gist with a shareable HTML link.

Switching Models

Pi supports 20+ LLM providers. Switch models at any time:

1. Open model selector

   Press Ctrl+L or type /model

2. Choose your model

   Use arrow keys and search to find your model. The list shows:

   • Model name and provider
   • Context window size
   • Pricing (input/output tokens)
   • Whether it supports vision and reasoning
3. Continue conversation

   Your session continues with the new model. Pi handles cross-provider compatibility automatically.

Use pi --models "claude-*,gpt-4o" to limit Ctrl+P cycling to specific model patterns.

Next Steps

Now that you have Pi running, explore these key areas:

Installation Details

Platform-specific setup, API keys, and advanced configuration

Interactive Mode

Master the terminal UI, editor features, and message queue

Providers & Models

Set up multiple providers and understand model selection

Customization

Extend Pi with skills, extensions, and prompt templates

Troubleshooting

Pi command not found

After installing globally, you may need to restart your terminal or reload your shell:

source ~/.bashrc  # or ~/.zshrc

If that doesn’t work, check your npm global bin directory is in PATH:

npm config get prefix
# Should output a path like /usr/local or ~/.npm-global

Authentication errors

If you see authentication errors:

1. Verify your API key is set correctly:

   echo $ANTHROPIC_API_KEY
   

2. Check the key format matches your provider’s requirements

3. For OAuth providers, try logging out and back in:

   pi
   /logout
   /login
   

Windows: bash not found

Pi requires bash on Windows. Install Git for Windows which includes Git Bash.

See the Windows setup guide for details.

Node.js version errors

Pi requires Node.js 20 or later. Check your version:

node --version

If needed, install a newer version from nodejs.org or use nvm:

nvm install 20
nvm use 20

For more help, join the Discord community or check the GitHub issues.