$ pi –switch

TL;DR. 全局安装 @earendil-works/pi-coding-agent 后在项目里运行 pi：现有 CLAUDE.md 原样加载；/login 用你现有的 provider 登录；MCP 配置由 pi install npm:pi-mcp-adapter 加 /mcp setup 导入；个人规则从 ~/.claude/CLAUDE.md 复制到 ~/.pi/agent/AGENTS.md 即完成主体迁移。

从 Claude Code 或 Cursor 过来？你已经会的大部分东西都有直接对应，而且有一件事比想象中更顺：Pi 原生读取 CLAUDE.md。你的项目记忆文件不用改就能生效——想改名成 AGENTS.md 随时可以，但不是必须。本指南按重要性顺序讲迁移：记忆文件、凭据与模型、命令、MCP、会话。

哪些东西原样沿用

Pi 加载上下文文件的位置与 Claude Code 高度重合，只是统一了命名：

~/.pi/agent/AGENTS.md —— 全局指令，总是加载（Claude Code 对应 ~/.claude/CLAUDE.md）
AGENTS.md 或 CLAUDE.md —— 从父目录（自 cwd 向上）到当前目录都会加载；两个名字都被接受，已有的目录树直接继续工作
AGENTS.override.md —— 按目录覆盖（v0.84.0 新增）
.pi/SYSTEM.md / ~/.pi/agent/SYSTEM.md —— 整体替换系统提示词；任一位置的 APPEND_SYSTEM.md 则是追加

技能采用与 Claude Code 相同的 SKILL.md 格式——为一方写的技能目录在另一方也能用（pi-skills 技能集就是一个两边通吃的例子）。Cursor 用户的路更短：Cursor 自身就把 AGENTS.md 作为项目规则格式支持，仓库根目录放一个文件即可同时服务两个工具。

并排安装

Pi 以全局 npm 包安装，与 Claude Code 和平共处：

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

两者互不共享、互不覆盖——Claude Code 的文件在 ~/.claude/，Pi 的在 ~/.pi/agent/。评估期间完全可以在同一个仓库里并行使用。

凭据与模型

Claude Code 用 /login 做订阅认证、配置放 ~/.claude/settings.json；Pi 把这些拆得更清楚：

/login —— 订阅 provider 的交互式 OAuth 登录（Anthropic、OpenAI、Google 等）
~/.pi/agent/auth.json —— 凭据落盘位置；环境变量同样有效
~/.pi/agent/settings.json —— 行为默认值：defaultProvider、defaultModel、defaultThinkingLevel
models.json —— 自定义端点与模型覆盖，支持网关和本地模型（含 llama.cpp）

你现有的 Anthropic API key 或订阅登录直接可用——Pi 内置了 Anthropic、OpenAI、Google Gemini、DeepSeek、Groq、xAI、OpenRouter、Mistral、Cerebras、Bedrock、Azure、Vertex 等厂商目录。会话内用 /model 或 Ctrl+P 切换模型，与 Claude Code 里 /model 的习惯一致。

你已经认识的命令

Claude Code	Pi
`/login`	`/login`（同名，交互式 OAuth）
`/model`	`/model`，或 Ctrl+P 循环切换
`/resume`	`/resume`
`/compact`	`/compact`
会话分叉	`/fork`、`/tree`、`/clone`
`/help`	`/help`

扩展和技能可以注册自己的斜杠命令，与内建命令并列——和 Claude Code 插件暴露命令是同一个心智模型。

MCP 服务器

针对 MCP 的上下文开销，Pi 的答案是 pi-mcp-adapter：一个约 200 token 的代理工具替代成百上千条工具定义，服务器只在真正使用时启动。迁移接近零配置——适配器自动读取标准 MCP 文件：

项目里的 .mcp.json，或 ~/.config/mcp/mcp.json —— 原样生效
Cursor / Claude Code / Codex 的宿主配置 —— /mcp setup 导入，写入前预览每一处变更

pi install npm:pi-mcp-adapter

会话与历史

Claude Code 把按项目组织的数据放在 ~/.claude/projects/ 下，自动记忆 auto memory 就在这里的 memory/ 子目录；Pi 的会话存在 ~/.pi/agent/sessions/，按工作目录组织，每个会话一个 JSONL 文件。格式是一棵树——每条记录有 id 和 parentId，当前位置就是活动叶子——这正是 /tree、/fork、/clone 得以实现的原因。想为社区公开有用的会话（Pi 作者本人就这么做），用 pi-share-hf 推到 Hugging Face。

迁移清单

全局安装 Pi，在项目里运行 pi —— CLAUDE.md 原样加载
用现有 provider /login，或设置环境变量 key
若在用 MCP 服务器：pi install npm:pi-mcp-adapter，再 /mcp setup 导入宿主配置
把 ~/.claude/CLAUDE.md 里的个人规则复制到 ~/.pi/agent/AGENTS.md
方便时把项目文件改名为 AGENTS.md —— 两个名字都会继续生效
重装你依赖的技能（同 SKILL.md 格式），或让 Pi 指向现有技能目录

从 Claude Code / Cursor 迁移到 Pi