Pi Coding Agent Setup Guide
Setup and configuration for Pi Coding Agent by Earendil Inc. — the minimal agent harness with TypeScript extensions, context engineering, and session trees. Powers OpenClaw under the hood.
Pi Coding Agent
Pi is a minimal agent harness by Earendil Inc., built by Mario Zechner (creator of libGDX). Philosophy: "Primitives, not features." No MCP, no sub-agents, no plan mode built in — everything is an extension. OpenClaw uses Pi's SDK as its agent engine.
Pi competes with Claude Code and Gemini CLI, not with Hermes or OpenClaw. It's a coding agent — it works in your terminal, reads your codebase, and executes tools. What makes it different: aggressive extensibility and context engineering.
Note:
Pi vs Claude Code vs Gemini CLI. Pi is MIT-licensed and extensible. Claude Code is proprietary with the strongest model (Claude Opus). Gemini CLI is free with Google's models. Use Pi when you want to customize the agent harness itself — custom system prompts, compaction strategies, extension pipelines.
Installation
Install the CLI
curl -fsSL https://pi.dev/install.sh | sh
Or via npm:
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
Configure API Keys
Pi reads API keys from environment variables or a config file.
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
Or create ~/.pi/config.json:
{
"providers": {
"anthropic": { "apiKey": "sk-ant-..." },
"openai": { "apiKey": "sk-..." }
}
}
Start a Session
pi
Or in print mode for scripting:
pi -p "Explain the auth flow in src/auth.ts"
Context Engineering
Pi's defining feature: full control over what goes into the context window.
<!-- AGENTS.md (in project root) -->
# Project instructions loaded at startup by Pi
This is a Next.js 15 project with Tailwind CSS v4.
Pages are server components by default.
Use `'use client'` for interactivity.
Pi loads AGENTS.md from ~/.pi/agent/, parent directories, and the current directory — same convention as Claude Code and OpenCode. Add project-specific instructions that load into every session.
<!-- SYSTEM.md (replaces default system prompt) -->
You are a senior TypeScript developer working on a Next.js project.
Prefer server components. Use Tailwind utilities. Avoid unnecessary abstractions.
Compaction is fully customizable via extensions:
// ~/.pi/extensions/compaction.ts
export default {
name: "custom-compaction",
async compact(messages, approachingLimit) {
// Keep system message + last 10 turns, summarize the rest
const system = messages[0];
const recent = messages.slice(-20);
const older = messages.slice(1, -20);
const summary = await summarize(older);
return [system, { role: "user", content: `[Context: ${summary}]` }, ...recent];
}
};
Extensions
Extensions are TypeScript modules with access to tools, commands, keyboard shortcuts, events, and the TUI. Everything Pi can do, extensions can modify.
// ~/.pi/extensions/linter.ts
export default {
name: "auto-lint",
async afterToolResult(name, args, result, messages) {
if (name === "write_file" && args.path.endsWith(".ts")) {
const lintResult = await runESLint(args.path);
return `${result}\n\n[LINT RESULTS]\n${lintResult}`;
}
return result;
}
};
Built-in Extension Examples (50+ available)
Values: built-in example
Values: built-in example
Values: built-in example
Values: built-in example
Values: built-in example
Values: built-in example
Skills System
Skills are capability packages with instructions and tools. Loaded on-demand — progressive disclosure without busting the prompt cache.
<!-- ~/.pi/skills/web-research.md -->
# Web Research Skill
Tools available: web_search, extract_content, cite_source
When performing research:
1. Search for authoritative sources first
2. Extract key facts from at least 2 sources
3. Cite everything with URLs
4. Flag any conflicting information
# Load a skill
/load web-research
# The skill's instructions are injected into context only when loaded
Session Trees
Pi stores sessions as tree structures. Every branch is a decision point you can return to.
# Navigate the session tree
/tree
# Continue from any previous point
/goto 42
# Export session to HTML
/export
# Share via GitHub gist
/share
This is useful for debugging agent behavior — when the agent takes a wrong turn, branch from before the mistake and try a different approach. Both branches are preserved.
Package Ecosystem
Pi packages bundle extensions, skills, prompts, and themes. Install from npm or git:
pi install npm:@foo/pi-tools
pi install git:github.com/badlogic/pi-doom
The community has built packages for MCP support, sub-agents, web browsing, code review workflows, and more. Browse at pi.dev/packages.
Four Modes
Pi operates in four modes depending on your use case:
Values: pi
Values: pi -p "query"
Values: pi --mode rpc
Values: import from @earendil-works/pi
Pi as the OpenClaw Engine
OpenClaw embeds Pi via its SDK mode. Every OpenClaw agent instance runs on Pi's agent harness. This means:
- Extensions you write for Pi work in OpenClaw
- Skills are portable between standalone Pi and OpenClaw
- Context engineering (AGENTS.md, SYSTEM.md, compaction) works identically
// OpenClaw uses Pi like this:
import { createAgent } from "@earendil-works/pi-coding-agent";
const agent = createAgent({
provider: "anthropic",
model: "claude-sonnet-4-20250514",
extensions: ["./openclaw/skills", "./openclaw/tools"],
});
await agent.run({ message: "Review PR #342" });
Note:
When to use Pi standalone vs OpenClaw. Use Pi standalone when you want a minimal coding agent with custom extensions. Use OpenClaw when you want the full Skills & Tools marketplace, messaging platform support, and multi-agent orchestration. OpenClaw IS Pi, plus everything built on top.
Key Takeaway
Pi is the Linux of agent harnesses — minimal, customizable, and you build what you need. If you find yourself fighting Claude Code's built-in behavior or wanting to strip Gemini CLI down to just tool execution, Pi is the answer. If you want everything pre-built with a marketplace, use OpenClaw (which runs on Pi anyway).
Related Articles
AI Agent Blueprints & Configurations
Ready-to-run AI agent blueprints, configurations, and local setup guides. Build research agents, code reviewers, and content writers with copy-paste implementations.
Agent Blueprints
Ready-to-run AI agent implementations. Complete system prompts, tool definitions, and initialization code for research, code review, and content writing agents.
Hermes Agent Setup Guide
Complete setup and configuration guide for Hermes Agent by Nous Research — the #1 self-hosted AI agent on OpenRouter. Skills, security, messaging platforms, and LLM provider wiring.