$ pi –switch

TL;DR. Install @earendil-works/pi-coding-agent globally and run pi in your project: your existing CLAUDE.md loads as-is, /login takes your current provider, pi install npm:pi-mcp-adapter plus /mcp setup imports your MCP config, and copying ~/.claude/CLAUDE.md to ~/.pi/agent/AGENTS.md completes the essentials.

Coming from Claude Code or Cursor? Most of what you know maps directly, and one thing maps better than you’d expect: Pi reads CLAUDE.md natively. Your project memory files work unmodified — rename them to AGENTS.md only when you want to, not because you have to. This guide walks the migration in the order that matters: memory files, credentials and models, commands, MCP, and sessions.

What carries over unchanged

Pi loads context files from the same project-level locations Claude Code does, with one unified name:

~/.pi/agent/AGENTS.md — global instructions, always loaded (Claude Code equivalent: ~/.claude/CLAUDE.md)
AGENTS.md or CLAUDE.md — from parent directories (walking up from the cwd) and the current directory; both names are accepted, so an existing tree keeps working
AGENTS.override.md — per-directory overrides (added in v0.84.0)
.pi/SYSTEM.md / ~/.pi/agent/SYSTEM.md — replace the system prompt entirely; APPEND_SYSTEM.md in either location appends to it

Skills use the same SKILL.md format as Claude Code — a skills directory written for one works in the other (see the pi-skills collection for an example that ships for both). Cursor users have an even shorter path: Cursor itself supports AGENTS.md as a project-rules format, so one file in the repo root can serve both tools.

Install side by side

Pi installs as a global npm package and coexists peacefully with Claude Code:

npm install -g @earendil-works/pi-coding-agent
pi

Nothing is shared or overwritten — Claude Code’s files live under ~/.claude/, Pi’s under ~/.pi/agent/. You can run both against the same repo during evaluation.

Credentials and models

Where Claude Code has /login for subscription auth and ~/.claude/settings.json, Pi splits the concerns:

/login — interactive OAuth login for subscription providers (Anthropic, OpenAI, Google, and more)
~/.pi/agent/auth.json — where credentials land; environment variables also work
~/.pi/agent/settings.json — behavior defaults: defaultProvider, defaultModel, defaultThinkingLevel
models.json — custom endpoints and model overrides for gateways and local models (llama.cpp included)

An Anthropic API key or subscription login you already use works as-is — Pi ships provider catalogs for Anthropic, OpenAI, Google Gemini, DeepSeek, Groq, xAI, OpenRouter, Mistral, Cerebras, Bedrock, Azure, Vertex, and more. Cycle models in-session with /model or Ctrl+P, the way you cycle with /model in Claude Code.

Commands you already know

Claude Code	Pi
`/login`	`/login` (same name, interactive OAuth)
`/model`	`/model`, or Ctrl+P to cycle
`/resume`	`/resume`
`/compact`	`/compact`
session forking	`/fork`, `/tree`, `/clone`
`/help`	`/help`

Extensions and skills can register their own slash commands alongside the built-ins — same mental model as Claude Code plugins exposing commands.

MCP servers

Pi’s answer to MCP’s context cost is the pi-mcp-adapter: one proxy tool (~200 tokens) instead of hundreds of tool definitions, servers starting only when used. Migration is close to zero-config — the adapter reads standard MCP files automatically:

.mcp.json in the project, or ~/.config/mcp/mcp.json — picked up as-is
Cursor / Claude Code / Codex host configs — /mcp setup imports them, previewing every file change before writing

pi install npm:pi-mcp-adapter

Sessions and history

Claude Code keeps its per-project data under ~/.claude/projects/ (its auto memory lives in the memory/ subdirectory there); Pi stores sessions under ~/.pi/agent/sessions/, organized by working directory, one JSONL file per session. The format is a tree — every entry has an id and parentId, and your current position is the active leaf — which is what makes /tree, /fork, and /clone possible. If you want to publish useful sessions for the community (as Pi’s author does), pi-share-hf pushes them to Hugging Face.

A migration checklist

Install Pi globally; run pi in your project — your CLAUDE.md loads as-is
/login with your existing provider, or set an env key
If you use MCP servers: pi install npm:pi-mcp-adapter, then /mcp setup to import host configs
Copy any personal rules from ~/.claude/CLAUDE.md into ~/.pi/agent/AGENTS.md
Rename project files to AGENTS.md when convenient — both names keep working
Reinstall the skills you rely on (same SKILL.md format), or point Pi at your existing skills directory

Switching from Claude Code or Cursor to Pi