How-to

Should you try Pi, the minimal coding agent?

Pi is a lean, open-source coding agent you shape yourself, and developers are trying it beside Claude Code or in its place. This prompt checks your own Claude Code setup against Pi’s docs and says try, switch or stay.

Caleb, a developer who blogs at caleb.software, wrote up his move to Pi in a post updated on 7 November, enjoying its “stability, minimalist approach, and the extreme level of customizability”. It reached 708 points and 440 comments on Hacker News on 8 November, with Pi fans and sceptics in the replies.

The prompt: try Pi, switch, or stay

Run it inside Claude Code from your project folder, so it can read your settings, or paste your settings into any AI chat with the secrets taken out. It reads your setup and changes nothing.

Prompt Should I try Pi
You are helping me decide whether to try Pi, an open-source coding agent, alongside Claude Code, switch to it, or stay where I am. Work like a senior developer who has run both. If you push me to switch and I lose a safety net I rely on, such as a deny rule or a hook that blocks risky commands, an agent could run a destructive command on my machine with nobody asking first. If you wave me off for no reason, I miss a tool that might suit me better. So judge from my real setup and the facts below, and say plainly when you cannot tell.

FACTS ABOUT PI (from Pi's README and docs, read on 9 November 2026, when the latest release was 1.5.1 (10 November); use only these, add nothing from memory, and if today is much later, tell me to recheck them at pi.dev)
- Pi is open source under the MIT licence and runs in a terminal. It needs Node.js 22.19 or newer.
- Pi has no built-in permission system for files, processes, network or credentials. It runs with the permissions of the user who started it and does not ask before every tool call.
- For stronger limits, Pi's docs suggest running it in a container or sandbox: a Gondolin micro-VM extension, plain Docker, or OpenShell.
- Pi skips sub-agents and plan mode by default. Its repo has example extensions for plan mode, sub-agents and permission gates (for example, confirm before rm -rf or sudo).
- Extensions are TypeScript modules that run inside Pi's own process, with the same permissions. An extension can block or change a tool call before it runs.
- Prompt templates give reusable message text.
- Skills follow the Agent Skills specification. Pi finds them in its own skills folders and in .agents/skills/ and ~/.agents/skills/. The docs do not mention .claude/skills/.
- MCP is built in, over stdio or streamable HTTP. The older SSE transport is not supported. Servers live in ~/.pi/agent/mcp.json and .pi/mcp.json, and an existing Claude Code mcpServers entry can be copied across.
- Pi loads AGENTS.md and CLAUDE.md files as project context.
- Pi works with many providers, including Anthropic, OpenAI, Google, OpenRouter, GitHub Copilot, Amazon Bedrock, Mistral, DeepSeek, local models through llama.cpp, and any OpenAI-compatible API such as Ollama, vLLM or LM Studio. It takes API keys or a sign-in.
- Pi's AI library README lists sign-in for a Claude Pro or Max subscription, a ChatGPT Plus or Pro subscription (through OpenAI Codex), and a GitHub Copilot subscription.
- Anthropic's Claude Code legal page says subscription sign-in is "intended exclusively for purchasers" of Claude plans and "designed to support ordinary use of Claude Code and other native Anthropic applications", and that Anthropic may enforce these restrictions "without prior notice". The same page says Anthropic does not permit third-party developers to "offer Claude.ai login into their own applications". Anthropic's help page says third-party app usage still draws from subscription limits "for now".
- Pi saves sessions as trees you can branch and export, and compacts older messages automatically.
- Pi has a setting, warnings.anthropicExtraUsage, on by default, that warns when Claude subscription sign-in may use paid extra usage.
- Anonymous install and update reporting is on by default (the enableInstallTelemetry setting).
- Anything not listed here is NOT STATED.

ABOUT ME (I fill this in once; any line can say "not sure")
- Where I am running this: [e.g. "Claude Code, in my project folder", "an AI chat, I will paste my files"]
- What I mostly use Claude Code for: [e.g. "bug fixes in a large Django app at work", "weekend side projects in TypeScript"]
- How I pay for models: [e.g. "Claude Max", "Claude Pro", "Anthropic API key", "my company's account"]
- Work or personal machine, and any company rules on AI tools: [e.g. "work laptop, approved tools only", "personal Mac", "not sure"]
- What I want from Pi: [e.g. "cheaper or local models", "less prompt overhead", "write my own tools", "just curious"]
- Features I think I rely on: [e.g. "plan mode most days", "a hook that runs tests after edits", "the GitHub MCP server", "not sure"]
- How much setup I will put in: [none / about an hour / a weekend]
- Would I run Pi inside a container or virtual machine: [yes / no / not sure]

SAFETY RULES FOR THIS CHAT
- Never print the value of any key, token, password or environment variable you find. Name it only, for example "ANTHROPIC_API_KEY is set".
- If I paste a secret by mistake, tell me to delete it from the chat and rotate it, and do not repeat it.
- Do not install, run or configure Pi, and do not change any of my files. This is a read-and-advise job.

HOW TO WORK
Check that I filled in ABOUT ME. If it is blank, ask for it once and wait. Then do Jobs 1 to 5 in order.

Job 1. Gather my real Claude Code setup.
- If you can read files where you are running (for example, you are Claude Code in my project): read whichever of these exist: .claude/settings.json, .claude/settings.local.json, ~/.claude/settings.json, .mcp.json, the mcpServers section of ~/.claude.json, .claude/agents/, ~/.claude/agents/, .claude/skills/, ~/.claude/skills/, .claude/commands/, CLAUDE.md and AGENTS.md. Tell me which you read and which were missing.
- If you cannot read files: ask me to paste those I have, with every secret value replaced by REDACTED, and wait.
- List what you find under these headings: permission rules (count of allow, ask and deny rules, and the riskiest allow rule), default permission mode, hooks (the event and what each one does), MCP servers (name and transport: stdio, HTTP or SSE), subagents, skills, custom slash commands, plugins, sandbox settings.
- Tag each item USED (seen in my files), CLAIMED (I said so in ABOUT ME but you did not see it) or NOT FOUND.

Job 2. Map each item to Pi, using only the FACTS.
- Deny rules, ask rules, or a default mode that asks before acting: Pi has no built-in permission system. Tag GAP-SAFETY, and name the two fixes in the FACTS: a permission-gate extension or a container.
- A hook that blocks or checks a tool call before it runs: an extension can do this. Tag EXTENSION. Any other hook: NOT STATED.
- MCP over stdio or HTTP: BUILT IN, copy the entry. MCP over SSE: GAP, not supported.
- Skills in .claude/skills/: tag MOVE, since the docs list .agents/skills/ and do not mention .claude/skills/. Mark the folder change [CHECK IN PI'S DOCS].
- Subagents or plan mode: EXTENSION (an example exists, and I would install or adapt it).
- Custom slash commands: prompt templates may cover them. Tag MOVE.
- Plugins, sandbox settings, or anything else: NOT STATED.
- CLAUDE.md: BUILT IN, Pi loads it.

Job 3. Check how I would pay.
- Anthropic API key: Pi takes it, and it is billed as API usage.
- Claude Pro or Max: quote both facts, Pi's README listing the sign-in and Anthropic's legal page wording. Do not tell me it is allowed or banned. Give me my options: an Anthropic API key, another provider from the FACTS, or reading Anthropic's consumer terms myself before signing in.
- My company's account or a work machine: tell me to ask whoever approves AI tools before installing anything, and mention that install reporting is on by default.
- Not sure: ask me, and wait.
Settled means an API key, another provider from the FACTS, or I confirm I have read Anthropic's consumer terms.

Job 4. Give one verdict, checking these rules in this order and stopping at the first that fits.
1. STAY if my work machine's rules do not allow new AI tools, or if I said "none" for setup. Say what would change the verdict.
2. SWITCH only if every USED or CLAIMED item is BUILT IN, MOVE or EXTENSION, nothing is GAP, any GAP-SAFETY item is covered because I said yes to a container, at most one item I use is NOT STATED, my payment route from Job 3 is settled, and I will put in a weekend. Even then, tell me to keep Claude Code installed until Pi has carried a week of my real work.
3. TRY ALONGSIDE in every other case. If anything is GAP-SAFETY, the trial runs in a container or a throwaway clone with no secrets in it.
Give the three reasons that decided it, each pointing at an item from Job 1.

Job 5. If the verdict is TRY ALONGSIDE or SWITCH, give me a first run in this order: where to run it (container or throwaway clone if anything is GAP-SAFETY); install from pi.dev; sign in with the route from Job 3; copy my MCP entries; move my skills; then one task I have already done in Claude Code, so I can compare the two results side by side. Mark any command or menu name that is not in the FACTS as [CHECK IN PI'S DOCS].

MY RESULT
End with a table (Feature | Where you found it | Pi | Tag), my payment line, the verdict and its three reasons, the first-run plan if there is one, and a list of everything NOT STATED that I should look up. Tell me to save it, since you may not have this chat later.

SELF-CHECK BEFORE YOU ANSWER
- No secret value appears anywhere in your answer.
- Every claim about Pi comes from the FACTS, or is marked NOT STATED or [CHECK IN PI'S DOCS].
- You did not say subscription sign-in in Pi is allowed or banned.
- The verdict follows the Job 4 rules in order.
- You changed no files and ran nothing.

What Pi does well

Pi describes itself as a minimal agent harness you make your own. It is MIT-licensed, has more than 120,000 stars on GitHub, and its maker Earendil last updated the repo on 8 November, with release 1.5.1 on npm on 10 November.

  • A small core you add to. Extensions are TypeScript modules, skills follow the Agent Skills format, and you can bundle both as packages to share through npm or git.
  • Lots of models. It works with Anthropic, OpenAI, Google, OpenRouter, GitHub Copilot and more, plus local models through llama.cpp or anything OpenAI-compatible, such as Ollama.
  • Your existing setup carries over in part. It reads AGENTS.md and CLAUDE.md, and its MCP docs say to copy a Claude Code mcpServers entry across as it is.
  • Sessions you can branch. Pi.dev shows sessions saved as a tree you browse with /tree, export to HTML, and steer mid-run by pressing Enter.

What it leaves out on purpose

Pi skips some things Claude Code builds in, and expects you to add them back with an extension, so map each one before you lean on it.

Permission prompts

In Pi: no built-in permission system. It runs with your user account’s permissions and does not ask before each tool call.

To add it back: a permission-gate extension that confirms commands like rm -rf, or a container, which the security docs call “usually the strongest practical option”.

Plan mode and subagents

In Pi: skipped by default.

To add it back: the repo’s example extensions include a full plan mode and one that spawns sub-agents.

Hooks

In Pi: extensions listen for events, and one can block or change a tool call before it runs.

To add it back: rewrite each hook as an extension, which runs inside Pi with your permissions, so read any you install.

Skills and MCP

In Pi: skills load from Pi’s folders and .agents/skills/; the page does not mention .claude/skills/. MCP works over stdio and HTTP, and the older SSE transport is not supported.

To add it back: copy or link your skills folder, copy your mcpServers entries into .pi/mcp.json, and check any SSE server has an HTTP option. Project servers load only after you trust the folder.

What to check before you switch

  1. Which account pays. An Anthropic API key is billed as API usage. Pi’s AI library README lists Claude Pro and Max sign-in as an option.
  2. What Anthropic says about plan sign-in. Its legal page says plan sign-in is designed for “ordinary use of Claude Code and other native Anthropic applications”, which Anthropic may enforce without notice, and that it does not permit third-party developers to “offer Claude.ai login into their own applications”. Read both sides before signing in.
  3. How plan usage is counted. Anthropic’s help page says third-party app usage still draws from your subscription limits “for now”, and Earendil’s pi-claude-code extension, which routes Claude requests through Claude Code, warns that its own future is uncertain.
  4. Leave the extra-usage warning on. If you sign in with a Claude plan, Pi’s warnings.anthropicExtraUsage setting warns when that sign-in may use paid extra usage.
  5. Where it runs. Pi acts with your account’s full access, so keep secrets out of the folder for first runs. It stores keys and sign-in tokens in auth.json, which its docs say never to commit.
  6. What it sends home. Anonymous install and update reporting is on by default; the settings page lists enableInstallTelemetry to turn it off.
  7. Who approves tools at work. On a work machine, ask before installing. Pi loads AGENTS.md and CLAUDE.md even in folders you have not trusted, and install reporting is on by default.

Try it beside Claude Code

The two can share a repo, since Pi keeps its own settings in .pi/ and reads the same CLAUDE.md, so a side-by-side trial costs you no setup in Claude Code.

  1. Install it. Check your Node.js version with node -v first. The README gives curl -fsSL https://pi.dev/install.sh | sh, or npm install -g --ignore-scripts @earendil-works/pi-coding-agent, and needs Node.js 22.19 or newer.
  2. Open a throwaway copy of a real project. Run pi from inside it, so a wrong command lands somewhere you can delete.
  3. Sign in. Type /login, pick the provider the prompt settled on, then /model to choose a model.
  4. Repeat a task you finished in Claude Code last week. Same task, same model if you can, so the only difference is the harness. Judge whether it was right first time, how often you stepped in, and the cost on your provider’s usage page.
  5. Then give it one long task. Long sessions test compaction, and one Hacker News commenter found Pi “awesome until compaction hits”.

The honest bit

  • Where the facts come from: Pi’s README and docs as of release 1.5.1, read without installing it, and Pi changes quickly.
  • Whose story this is: Caleb’s post is one developer’s view. He calls Claude Code “a really cool piece of software”, and his complaint about copying between CLAUDE.md and AGENTS.md is gone now that Claude Code reads AGENTS.md.
  • Your check: after installing, type /login and read the provider list on your own screen. If your plan is not there, the README line does not apply to your version.

The facts here come from Pi’s GitHub repo, docs and pi.dev, Caleb’s post, the Hacker News thread, and Anthropic’s Claude Code and help pages, read 9 November 2026.

Do it now

Open Claude Code in your busiest project and paste the prompt; if it says try, give Pi one task you already know the answer to.

A few quick questions

Does Pi work with local models?

Yes, according to its model docs: it connects to the llama.cpp router, which loads GGUF model files on demand, and to any OpenAI-compatible endpoint such as Ollama, vLLM or LM Studio. How well a small local model codes is a separate question, so test it on a task you know.

Is Pi free?

The software is: Pi is open source under the MIT licence. You pay for the model it calls, through an API key or a plan sign-in with your provider, or nothing extra if you run a local model on your own machine.