Moving from Claude Code to free-pi

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 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/<name>/SKILL.md: Copy the skill folder to .agents/skills/<name>/.
• Personal skills, ~/.claude/skills/<name>/SKILL.md: Copy the skill folder to ~/.agents/skills/<name>/.
• 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/<name>.md: Copy the file to .pi/prompts/<name>.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.
• 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.
• 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.
• Different slash commands. Commands such as /usage and /invite are free-pi's. See 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.

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.