# Moving from Claude Code to free-pi How to switch from Claude Code to free-pi: install it, sign in, and bring over your instructions, skills, MCP servers and custom commands. ## Install and sign in Run this in your project folder: ``` npx free-pi-cli@latest ``` Accept the consent screen and sign in with GitHub. There is no plan to pick and no API key to paste. See [Getting started](/docs/getting-started) for the Node.js version you need and what the first run does. free-pi keeps its files under `~/.free-pi/agent`, not `~/.claude`. Nothing in your Claude Code setup is changed, and free-pi does not read it for you. The sections below show what to copy. ## What carries over - **Project `CLAUDE.md`:** Usually nothing to do. The pi agent that free-pi runs reads `CLAUDE.md` or `AGENTS.md` in the working directory and its parent folders. If one folder has both, it loads only one file, and `AGENTS.override.md` or `AGENTS.md` wins over `CLAUDE.md`. In that case, merge your instructions into one file. - **Personal `~/.claude/CLAUDE.md`:** Copy it to `~/.free-pi/agent/CLAUDE.md` or `AGENTS.md`. Use only one of the two names in that folder, with the same precedence as above. - **Project skills, `.claude/skills//SKILL.md`:** Copy the skill folder to `.agents/skills//`. - **Personal skills, `~/.claude/skills//SKILL.md`:** Copy the skill folder to `~/.agents/skills//`. - **Project MCP servers, `.mcp.json`:** Copy the `mcpServers` entries to `.pi/mcp.json`. Instead of `claude mcp add`, use `npx free-pi-cli@latest mcp add`. Servers that use the older SSE transport (`"type": "sse"`) are rejected, so they need a streamable HTTP URL instead. - **Custom commands, `.claude/commands/.md`:** Copy the file to `.pi/prompts/.md`. The file name becomes the slash command. The instruction-file, skill, MCP and prompt rules come from the documentation of the pi agent version bundled with free-pi. Each section below says more. ### Instructions Both tools load a markdown file of standing instructions at the start of a session. If your project already has a `CLAUDE.md` or an `AGENTS.md`, free-pi will pick it up. Only one file per folder is loaded, and `AGENTS.override.md` or `AGENTS.md` is preferred over `CLAUDE.md`, so if you keep both, merge them into one. Claude Code's `@path` imports inside `CLAUDE.md` are a Claude Code feature. free-pi's docs do not describe them, so paste the imported text into the file if you rely on it. ### Skills Both tools use the same skill format: a folder with a `SKILL.md` file that starts with `name` and `description` frontmatter. Copy your skill folders into `.agents/skills/` in the project, or `~/.agents/skills/` for all projects. You can also use `~/.free-pi/agent/skills/` or `.pi/skills/`. free-pi bundles a few skills of its own, such as the security-audit skill. To run a skill yourself, type `/skill:name`. ### MCP servers The `mcpServers` format is the same for local (stdio) servers and streamable HTTP servers. Copy those entries into `.pi/mcp.json` for one project, or `~/.free-pi/agent/mcp.json` for every project. SSE servers (`"type": "sse"`) are not supported: use the server's streamable HTTP URL. Or add servers from the command line (the commands use `npx`, so no global install is needed): ``` npx free-pi-cli@latest mcp add files -- npx -y @modelcontextprotocol/server-filesystem . npx free-pi-cli@latest mcp add docs --url https://example.com/mcp ``` Inside a session, type `/mcp` to check connections and sign in. Use `/reload` after you edit the file by hand. ### Custom commands A Markdown file in `.pi/prompts/` (or `~/.free-pi/agent/prompts/`) becomes a slash command with the file's name. It can take arguments with `$1`, `$2` and `$ARGUMENTS`, the same as Claude Code command files. ### Project trust Project skills, MCP servers and settings can run code. The first time you start free-pi in a folder that has them, it asks `Trust this folder? [y/N]`. If you answer no, those project files are ignored. Instruction files like `CLAUDE.md` load either way. ## Bring over a Claude Code session You can continue the work from a Claude Code session in free-pi. `/import` first shipped in free-pi-cli 0.6.10, so use that version or newer. Start free-pi in the same project folder, then use one of these: - `/import` opens a picker of your recent Claude Code and Codex sessions for this folder. - `/import claude` takes the newest Claude Code session for this folder. `/import codex` does the same for Codex. - `npx free-pi-cli@latest --import` does it at startup. Add `claude` or `codex` to pick which agent, as in `--import claude`. A session counts as being from "this folder" if it ran in the folder or in its git root. If a plain `/import` finds nothing for this folder, it shows the most recent sessions from other folders instead. Before anything is sent, free-pi tells you what it will send and asks you to confirm. Then it reads the session file on your machine, hides things that look like secrets, and asks free-pi's model for a short handoff note. The note covers the goal, what is done, what is left, key decisions, files touched, the last error, and a next step. If the summary fails, free-pi sends a plain extract of the session instead. The note is sent as a message to the agent (your first message, if you used `--import`). It tells the agent that the files in the folder are the source of truth, and asks it to say what it understands and propose a next step without changing anything until you say go. `--import` starts a new session, so it is ignored if you also pass `--session` or `--continue`, and it needs an interactive terminal; without one, free-pi starts normally. If you run `/import` while the agent is still working, it does nothing until the turn ends: run it again after the turn finishes. ## What is different - **Models.** free-pi's default model is DeepSeek V4 Flash. Use `/model` to pick another one from the catalog. See [Models and limits](/docs/models-and-limits). - **Allowance, not a plan.** You get a free daily allowance that refills each day. `/usage` shows how much you have used. See [Models and limits](/docs/models-and-limits). - **A fixed set of tools.** The agent can read, write, edit, search and list files, and run shell commands, plus any MCP tools you add. See [Using the agent](/docs/using-the-agent). - **Different slash commands.** Commands such as `/usage` and `/invite` are free-pi's. See [Commands and flags](/docs/commands-and-flags). - **Not covered in these docs.** Claude Code hooks, subagents, plan mode and automatic memory. If you rely on one of these, check that free-pi has an equivalent before you move your whole workflow. - **Ads and data.** free-pi is free because it shows ads in your terminal, and it may train on session data. See [Ads and privacy](/docs/ads-and-privacy). Because the agent can change files and run commands, keep your project under version control. ## Going back You can use both. Your `CLAUDE.md`, `AGENTS.md` and `.mcp.json` files stay where they are, and Claude Code ignores the copies you made for free-pi.