Installation

Install Pi packages for your use case

Choose Your Installation

Pi is distributed as multiple npm packages. Install only what you need:

Coding Agent CLI

Install globally for interactive development

Library Packages

Install locally for programmatic usage

Prerequisites

Pi requires Node.js 20.0.0 or higher. Check your version with node --version.

node --version  # Should output v20.0.0 or higher

Coding Agent (Global CLI)

For the full interactive coding agent experience:

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

Verify installation:

pi --version

Platform-Specific Notes

Windows: Works best with Windows Terminal. See Windows setup guide.

Termux (Android): Fully supported. See Termux setup guide.

Terminal Configuration: For best experience, see terminal setup guide.

Library Packages

LLM API Only

For unified LLM access without the agent runtime:

npm install @mariozechner/pi-ai

Includes:

• Multi-provider LLM streaming and completion
• Tool calling with TypeBox validation
• Automatic model discovery
• OAuth support

Use when: Building custom LLM integrations, need simple completion/streaming API

Agent Runtime

For building stateful agents with tool execution:

npm install @mariozechner/pi-agent-core @mariozechner/pi-ai

Includes:

• Agent state management
• Event-driven architecture
• Tool execution loop
• Message queue and steering

Use when: Building custom agents, need event streaming and state management

Terminal UI

For building terminal-based interfaces:

npm install @mariozechner/pi-tui

Includes:

• Differential rendering
• Built-in components (Editor, Markdown, SelectList, etc.)
• Overlay system
• Autocomplete providers

Use when: Building CLIs, need terminal UI components

Web UI

For building browser-based chat interfaces:

npm install @mariozechner/pi-web-ui @mariozechner/pi-agent-core @mariozechner/pi-ai

Peer dependencies:

npm install @mariozechner/mini-lit lit

Includes:

• Chat panel components
• Artifact viewer
• File attachments (PDF, DOCX, XLSX, images)
• IndexedDB storage
• CORS proxy handling

Use when: Building web apps, browser extensions, need browser-based chat UI

Slack Bot

For running the coding agent in Slack:

npm install @mariozechner/pi-mom

Includes:

• Slack socket mode integration
• Thread management
• Agent delegation

Use when: Need team collaboration via Slack

vLLM Pod Management

For managing GPU pods and vLLM deployments:

npm install @mariozechner/pi-pods

Use when: Self-hosting LLM inference on cloud GPU providers

Full Development Setup

To work on Pi itself or use all packages:

1. Clone the Repository

   git clone https://github.com/badlogic/pi-mono.git
   cd pi-mono
   
2. Install Dependencies

   npm install
   
3. Build All Packages

   npm run build
   
4. Run Tests

   ./test.sh  # Skips LLM tests without API keys
   

Development Note: npm run check requires npm run build to be run first, as the web-ui package uses TypeScript which needs compiled .d.ts files from dependencies.

API Keys & Authentication

After installation, configure authentication for your LLM provider:

API Keys

Set environment variables for your provider:

# Anthropic
export ANTHROPIC_API_KEY=sk-ant-...

# OpenAI
export OPENAI_API_KEY=sk-...

# Google Gemini
export GEMINI_API_KEY=...

# xAI
export XAI_API_KEY=...

# Groq
export GROQ_API_KEY=...

# Cerebras
export CEREBRAS_API_KEY=...

# Mistral
export MISTRAL_API_KEY=...

See AI Providers for complete list.

OAuth (Subscriptions)

For subscription-based providers (Claude Pro, ChatGPT Plus, GitHub Copilot):

Coding Agent:

pi
/login  # Interactive provider selection

Library (pi-ai):

npx @mariozechner/pi-ai login
npx @mariozechner/pi-ai login anthropic  # Specific provider

See OAuth Providers for details.

Google Vertex AI

Google Vertex AI uses Application Default Credentials:

Local Development:

gcloud auth application-default login
export GOOGLE_CLOUD_PROJECT="my-project"
export GOOGLE_CLOUD_LOCATION="us-central1"

Production (Service Account):

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"
export GOOGLE_CLOUD_PROJECT="my-project"
export GOOGLE_CLOUD_LOCATION="us-central1"

Azure OpenAI

Azure OpenAI requires resource configuration:

export AZURE_OPENAI_API_KEY=...
export AZURE_OPENAI_RESOURCE_NAME=my-resource
# OR
export AZURE_OPENAI_BASE_URL=https://my-resource.openai.azure.com

# Optional: Override API version (defaults to v1)
export AZURE_OPENAI_API_VERSION=v1

# Optional: Map model IDs to deployment names
export AZURE_OPENAI_DEPLOYMENT_NAME_MAP="gpt-4o-mini=my-deployment,gpt-4o=prod"

Verify Installation

Coding Agent

# Check version
pi --version

# List available models (requires API key)
pi --list-models

# Test with a simple prompt
pi -p "Hello, who are you?"

Package Versions

All Pi packages use lockstep versioning. Every release updates all packages together, even if only one package changed. This ensures compatibility across the monorepo.

Current version: 0.55.3 (as of this documentation)

Check for updates:

npm outdated -g @mariozechner/pi-coding-agent  # Global CLI
npm outdated @mariozechner/pi-ai               # Library packages

Update to latest:

npm update -g @mariozechner/pi-coding-agent    # Global CLI
npm update @mariozechner/pi-ai                 # Library packages

Common Installation Issues

Node version too old

Error: error @mariozechner/pi-coding-agent@0.55.3: The engine "node" is incompatible with this module.

Solution: Update Node.js to v20 or higher. Use nvm for easy version management:

nvm install 20
nvm use 20

Permission errors on global install

Error: EACCES: permission denied

Solution: Use npx instead, or configure npm prefix:

# Option 1: Use npx (no global install needed)
npx @mariozechner/pi-coding-agent

# Option 2: Configure npm to use user directory
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @mariozechner/pi-coding-agent

Module not found errors

Error: Cannot find module '@mariozechner/pi-ai'

Solution: Ensure dependencies are installed:

# For library usage, install peer dependencies
npm install @mariozechner/pi-ai

# For web-ui, install peer dependencies
npm install @mariozechner/mini-lit lit

TypeScript errors in development

Error: Type errors when building web-ui

Solution: Build dependencies first:

npm run build  # From monorepo root

The web-ui package uses TypeScript and needs compiled .d.ts files from dependencies.

Next Steps

Quick Start Guide

Run your first Pi agent in under 5 minutes

LLM Providers

Configure your preferred LLM provider

Coding Agent Guide

Learn the interactive coding agent

API Reference

Explore the programmatic API