Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/badlogic/pi-mono/llms.txt

Use this file to discover all available pages before exploring further.

​
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
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:
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.

​
Verify Installation

# 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

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
Error: EACCES: permission deniedSolution: 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
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
Error: Type errors when building web-uiSolution: 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

Build docs developers (and LLMs) love

Get started for freeTalk to us