[{"data":1,"prerenderedAt":1557},["ShallowReactive",2],{"blog-post-pi-coding-agent-setup":3,"related-posts-pi-coding-agent-setup":1529},{"id":4,"title":5,"author":6,"body":11,"category":1508,"date":1509,"description":1510,"extension":1511,"featured":1512,"hideToc":1512,"image":1513,"imageAlt":1514,"imageHeight":1514,"imageWidth":1514,"itemList":1514,"lang":1514,"meta":1515,"navigation":615,"noindex":1512,"path":1516,"readingTime":1517,"redirected":1512,"relatedSlugs":1514,"seo":1518,"seoTitle":5,"stem":1519,"subtitle":1514,"tags":1520,"updatedDate":1514,"__hash__":1528},"blog/blog/pi-coding-agent-setup.md","Pi Coding Agent: Install, Models and Extensions (2026)",{"name":7,"role":8,"avatar":9,"bio":10},"Shabnam Katoch","Growth Head","/img/avatars/shabnam-profile.jpeg","Shabnam leads growth at BetterClaw and has spent the past three years building organic distribution for AI-native products. She writes about no-code agent builders, content strategy, and what it actually takes to grow without an ads budget.",{"type":12,"value":13,"toc":1488},"minimark",[14,18,26,34,37,42,45,48,51,72,76,79,82,115,118,129,132,163,170,181,192,196,199,204,215,218,222,225,250,275,286,301,305,312,419,426,430,454,461,465,468,471,513,527,530,563,566,570,577,584,799,802,817,827,833,843,853,857,860,880,891,902,905,908,939,943,946,1043,1053,1059,1070,1074,1077,1243,1246,1250,1253,1352,1358,1364,1368,1371,1374,1377,1381,1388,1391,1399,1403,1420,1436,1445,1454,1460,1484],[15,16,17],"p",{},"Pi is a small, fast terminal coding agent that you shape with extensions. Here's how to install it, connect any model, add MCP and extensions, and fix the errors you'll actually hit.",[15,19,20,21,25],{},"We pointed Pi at a test folder, gave it a fake model that asked to run ",[22,23,24],"code",{},"rm -rf build",", and pressed enter. The folder was gone before we could read the line.",[15,27,28,29,33],{},"That's not a bug. ",[30,31,32],"strong",{},"Pi doesn't ask before it runs commands, by design",", and it's the first thing you should know before you install it. The second is that most guides online are now out of date: Pi changed its package name, moved its repo, and added MCP in the last few months.",[15,35,36],{},"Everything below was tested on Pi 1.4.0, released 21 October 2026.",[38,39,41],"h2",{"id":40},"what-pi-is-and-what-it-deliberately-leaves-out","What Pi is (and what it deliberately leaves out)",[15,43,44],{},"Pi is an open-source coding agent for your terminal, started by Mario Zechner and now developed by Earendil. It's MIT-licensed, has about 118,000 GitHub stars, and you bring your own model.",[15,46,47],{},"The idea is a small core you extend yourself. Out of the box it has four tools: read, write, edit and bash. Its own README says it \"skips features like sub-agents and plan mode\", and leaves those to extensions.",[15,49,50],{},"Three changes catch people out in 2026:",[52,53,54,66,69],"ul",{},[55,56,57,58,61,62,65],"li",{},"The npm package is now ",[22,59,60],{},"@earendil-works/pi-coding-agent",". The old ",[22,63,64],{},"@mariozechner/pi-coding-agent"," is deprecated and stopped at 0.73.1.",[55,67,68],{},"The repo moved to github.com/earendil-works/pi.",[55,70,71],{},"Pi now has MCP built in, since version 0.99.0 on 29 September 2026. Any guide that says \"Pi has no MCP\" predates that.",[38,73,75],{"id":74},"how-to-install-pi","How to install Pi",[15,77,78],{},"Pi needs Node.js 22.19 or newer if you install it with npm. The official installer handles Node for you.",[15,80,81],{},"On macOS or Linux:",[83,84,89],"pre",{"className":85,"code":86,"language":87,"meta":88,"style":88},"language-bash shiki shiki-themes github-light","curl -fsSL https://pi.dev/install.sh | sh\n","bash","",[22,90,91],{"__ignoreMap":88},[92,93,96,100,104,108,112],"span",{"class":94,"line":95},"line",1,[92,97,99],{"class":98},"s7eDp","curl",[92,101,103],{"class":102},"sYu0t"," -fsSL",[92,105,107],{"class":106},"sYBdl"," https://pi.dev/install.sh",[92,109,111],{"class":110},"sD7c4"," |",[92,113,114],{"class":98}," sh\n",[15,116,117],{},"On Windows (PowerShell):",[83,119,123],{"className":120,"code":121,"language":122,"meta":88,"style":88},"language-powershell shiki shiki-themes github-light","powershell -c \"irm https://pi.dev/install.ps1 | iex\"\n","powershell",[22,124,125],{"__ignoreMap":88},[92,126,127],{"class":94,"line":95},[92,128,121],{},[15,130,131],{},"With npm, on any system:",[83,133,135],{"className":85,"code":134,"language":87,"meta":88,"style":88},"npm install -g --ignore-scripts @earendil-works/pi-coding-agent\npi --version\n",[22,136,137,154],{"__ignoreMap":88},[92,138,139,142,145,148,151],{"class":94,"line":95},[92,140,141],{"class":98},"npm",[92,143,144],{"class":106}," install",[92,146,147],{"class":102}," -g",[92,149,150],{"class":102}," --ignore-scripts",[92,152,153],{"class":106}," @earendil-works/pi-coding-agent\n",[92,155,157,160],{"class":94,"line":156},2,[92,158,159],{"class":98},"pi",[92,161,162],{"class":102}," --version\n",[15,164,165,166,169],{},"Pi's docs recommend the installer, because it pins every dependency. The ",[22,167,168],{},"--ignore-scripts"," flag in the npm command is from the official docs too; Pi doesn't need install scripts to work.",[15,171,172,173,176,177,180],{},"To update later, run ",[22,174,175],{},"pi update",". Use ",[22,178,179],{},"pi update --all"," to update Pi and every package you've installed at once.",[15,182,183,184,187,188,191],{},"If you have the old package installed, remove it first with ",[22,185,186],{},"npm uninstall -g @mariozechner/pi-coding-agent",". Otherwise you'll keep running the old pi, and new extensions written for the ",[22,189,190],{},"@earendil-works"," package won't load.",[38,193,195],{"id":194},"connect-a-model-subscription-api-key-or-local","Connect a model: subscription, API key or local",[15,197,198],{},"Pi works with more than 30 providers. There are three ways to give it a model.",[200,201,203],"h3",{"id":202},"option-1-log-in-with-a-subscription","Option 1: log in with a subscription",[15,205,206,207,210,211,214],{},"Start Pi and type ",[22,208,209],{},"/login",". Pi lists the providers it can sign in to, including GitHub Copilot, ChatGPT plans, Claude Pro and Max, Grok and Kimi, and walks you through a browser or device login. The credential is saved in ",[22,212,213],{},"~/.pi/agent/auth.json",".",[15,216,217],{},"Before you use a subscription this way, check that provider's current terms for third-party tools. They change.",[200,219,221],{"id":220},"option-2-use-an-api-key","Option 2: use an API key",[15,223,224],{},"Set the key as an environment variable and start Pi:",[83,226,228],{"className":85,"code":227,"language":87,"meta":88,"style":88},"export ANTHROPIC_API_KEY=sk-ant-...\npi\n",[22,229,230,245],{"__ignoreMap":88},[92,231,232,235,239,242],{"class":94,"line":95},[92,233,234],{"class":110},"export",[92,236,238],{"class":237},"sgsFI"," ANTHROPIC_API_KEY",[92,240,241],{"class":110},"=",[92,243,244],{"class":237},"sk-ant-...\n",[92,246,247],{"class":94,"line":156},[92,248,249],{"class":98},"pi\n",[15,251,252,253,256,257,256,260,256,263,266,267,270,271,274],{},"Other common ones are ",[22,254,255],{},"OPENAI_API_KEY",", ",[22,258,259],{},"GEMINI_API_KEY",[22,261,262],{},"OPENROUTER_API_KEY",[22,264,265],{},"DEEPSEEK_API_KEY"," and ",[22,268,269],{},"GROQ_API_KEY",". Run ",[22,272,273],{},"pi --help"," for the full list.",[15,276,277,278,281,282,285],{},"One thing we learned the hard way: ",[22,279,280],{},"pi auth check --provider anthropic"," printed \"ready\" for a key we made up. ",[30,283,284],{},"It confirms a key exists, not that it works."," The real test is a one-line prompt:",[83,287,289],{"className":85,"code":288,"language":87,"meta":88,"style":88},"pi -p \"say hi\"\n",[22,290,291],{"__ignoreMap":88},[92,292,293,295,298],{"class":94,"line":95},[92,294,159],{"class":98},[92,296,297],{"class":102}," -p",[92,299,300],{"class":106}," \"say hi\"\n",[200,302,304],{"id":303},"option-3-run-a-local-model","Option 3: run a local model",[15,306,307,308,311],{},"Pi talks to any OpenAI-compatible endpoint through ",[22,309,310],{},"~/.pi/agent/models.json",". This is the example from Pi's docs for Ollama:",[83,313,317],{"className":314,"code":315,"language":316,"meta":88,"style":88},"language-json shiki shiki-themes github-light","{\n  \"providers\": {\n    \"ollama\": {\n      \"baseUrl\": \"http://localhost:11434/v1\",\n      \"api\": \"openai-completions\",\n      \"apiKey\": \"ollama\",\n      \"models\": [{ \"id\": \"qwen2.5-coder:7b\" }]\n    }\n  }\n}\n","json",[22,318,319,324,332,340,355,368,381,401,407,413],{"__ignoreMap":88},[92,320,321],{"class":94,"line":95},[92,322,323],{"class":237},"{\n",[92,325,326,329],{"class":94,"line":156},[92,327,328],{"class":102},"  \"providers\"",[92,330,331],{"class":237},": {\n",[92,333,335,338],{"class":94,"line":334},3,[92,336,337],{"class":102},"    \"ollama\"",[92,339,331],{"class":237},[92,341,343,346,349,352],{"class":94,"line":342},4,[92,344,345],{"class":102},"      \"baseUrl\"",[92,347,348],{"class":237},": ",[92,350,351],{"class":106},"\"http://localhost:11434/v1\"",[92,353,354],{"class":237},",\n",[92,356,358,361,363,366],{"class":94,"line":357},5,[92,359,360],{"class":102},"      \"api\"",[92,362,348],{"class":237},[92,364,365],{"class":106},"\"openai-completions\"",[92,367,354],{"class":237},[92,369,371,374,376,379],{"class":94,"line":370},6,[92,372,373],{"class":102},"      \"apiKey\"",[92,375,348],{"class":237},[92,377,378],{"class":106},"\"ollama\"",[92,380,354],{"class":237},[92,382,384,387,390,393,395,398],{"class":94,"line":383},7,[92,385,386],{"class":102},"      \"models\"",[92,388,389],{"class":237},": [{ ",[92,391,392],{"class":102},"\"id\"",[92,394,348],{"class":237},[92,396,397],{"class":106},"\"qwen2.5-coder:7b\"",[92,399,400],{"class":237}," }]\n",[92,402,404],{"class":94,"line":403},8,[92,405,406],{"class":237},"    }\n",[92,408,410],{"class":94,"line":409},9,[92,411,412],{"class":237},"  }\n",[92,414,416],{"class":94,"line":415},10,[92,417,418],{"class":237},"}\n",[15,420,421,422,425],{},"The ",[22,423,424],{},"apiKey"," is a dummy; Ollama ignores it, but Pi needs something there. LM Studio, vLLM and similar servers work the same way. llama.cpp has its own built-in integration.",[200,427,429],{"id":428},"switching-models","Switching models",[52,431,432,438,441],{},[55,433,434,437],{},[22,435,436],{},"/model"," (or Ctrl+L) opens the model picker.",[55,439,440],{},"Ctrl+P cycles through your favourite models mid-session.",[55,442,443,446,447,450,451,214],{},[22,444,445],{},"--model provider/id"," picks one at launch, and ",[22,448,449],{},":high"," sets the thinking level, as in ",[22,452,453],{},"pi --model sonnet:high",[15,455,456],{},[457,458],"img",{"alt":459,"src":460},"Three ways to give Pi a model — subscription login, API key, or local model via models.json; switch any time with /model","/img/blog/pi-coding-agent-models.jpg",[38,462,464],{"id":463},"add-mcp-servers","Add MCP servers",[15,466,467],{},"This is the part most guides get wrong. Pi used to say \"No MCP\" in its README, and suggested CLI tools instead. That changed in 0.99.0, and MCP is now a built-in extension.",[15,469,470],{},"We added the standard filesystem server:",[83,472,474],{"className":85,"code":473,"language":87,"meta":88,"style":88},"pi mcp add files -- npx -y @modelcontextprotocol/server-filesystem .\npi mcp list\n",[22,475,476,504],{"__ignoreMap":88},[92,477,478,480,483,486,489,492,495,498,501],{"class":94,"line":95},[92,479,159],{"class":98},[92,481,482],{"class":106}," mcp",[92,484,485],{"class":106}," add",[92,487,488],{"class":106}," files",[92,490,491],{"class":102}," --",[92,493,494],{"class":106}," npx",[92,496,497],{"class":102}," -y",[92,499,500],{"class":106}," @modelcontextprotocol/server-filesystem",[92,502,503],{"class":106}," .\n",[92,505,506,508,510],{"class":94,"line":156},[92,507,159],{"class":98},[92,509,482],{"class":106},[92,511,512],{"class":106}," list\n",[15,514,515,518,519,522,523,526],{},[22,516,517],{},"pi mcp list"," came back with \"files: connected, 14 tools\". The config lands in ",[22,520,521],{},"~/.pi/agent/mcp.json",", in the same ",[22,524,525],{},"mcpServers"," format Claude Desktop and Cursor use, so you can often copy an existing config across.",[15,528,529],{},"A few details worth knowing:",[52,531,532,543,554,557],{},[55,533,534,535,538,539,542],{},"Add ",[22,536,537],{},"-l"," to save a server to the project's ",[22,540,541],{},".pi/mcp.json"," instead. Pi only reads project files after you trust the folder.",[55,544,545,546,549,550,553],{},"Remote servers use ",[22,547,548],{},"--url",", and ",[22,551,552],{},"pi mcp login \u003Cserver>"," handles OAuth.",[55,555,556],{},"The old SSE transport isn't supported; use stdio or streamable HTTP.",[55,558,559,562],{},[22,560,561],{},"pi --no-mcp"," starts a session with MCP switched off.",[15,564,565],{},"If a server won't connect, the error is usually \"MCP error -32000: Connection closed\", which means the server process quit.",[38,567,569],{"id":568},"extensions-the-reason-people-pick-pi","Extensions: the reason people pick Pi",[15,571,572,573,576],{},"An extension is a TypeScript file that adds tools, commands or rules to Pi. There's no build step; Pi loads ",[22,574,575],{},".ts"," files directly.",[15,578,579,580,583],{},"Remember the deleted folder from the intro? Here's the extension that stopped it happening a second time. Save it as ",[22,581,582],{},"guard.ts",":",[83,585,589],{"className":586,"code":587,"language":588,"meta":88,"style":88},"language-typescript shiki shiki-themes github-light","import type { ExtensionAPI } from \"@earendil-works/pi-coding-agent\";\n\nexport default function (pi: ExtensionAPI) {\n  pi.on(\"tool_call\", async (event) => {\n    const cmd = String((event.input as { command?: string })?.command ?? \"\");\n    if (event.toolName === \"bash\" && /\\brm\\s+-rf\\b/.test(cmd)) {\n      return { block: true, reason: \"rm -rf is blocked by guard.ts\" };\n    }\n  });\n}\n","typescript",[22,590,591,611,617,641,674,718,766,786,790,795],{"__ignoreMap":88},[92,592,593,596,599,602,605,608],{"class":94,"line":95},[92,594,595],{"class":110},"import",[92,597,598],{"class":110}," type",[92,600,601],{"class":237}," { ExtensionAPI } ",[92,603,604],{"class":110},"from",[92,606,607],{"class":106}," \"@earendil-works/pi-coding-agent\"",[92,609,610],{"class":237},";\n",[92,612,613],{"class":94,"line":156},[92,614,616],{"emptyLinePlaceholder":615},true,"\n",[92,618,619,621,624,627,630,633,635,638],{"class":94,"line":334},[92,620,234],{"class":110},[92,622,623],{"class":110}," default",[92,625,626],{"class":110}," function",[92,628,629],{"class":237}," (",[92,631,159],{"class":632},"sqxcx",[92,634,583],{"class":110},[92,636,637],{"class":98}," ExtensionAPI",[92,639,640],{"class":237},") {\n",[92,642,643,646,649,652,655,657,660,662,665,668,671],{"class":94,"line":342},[92,644,645],{"class":237},"  pi.",[92,647,648],{"class":98},"on",[92,650,651],{"class":237},"(",[92,653,654],{"class":106},"\"tool_call\"",[92,656,256],{"class":237},[92,658,659],{"class":110},"async",[92,661,629],{"class":237},[92,663,664],{"class":632},"event",[92,666,667],{"class":237},") ",[92,669,670],{"class":110},"=>",[92,672,673],{"class":237}," {\n",[92,675,676,679,682,685,688,691,694,697,700,703,706,709,712,715],{"class":94,"line":357},[92,677,678],{"class":110},"    const",[92,680,681],{"class":102}," cmd",[92,683,684],{"class":110}," =",[92,686,687],{"class":98}," String",[92,689,690],{"class":237},"((event.input ",[92,692,693],{"class":110},"as",[92,695,696],{"class":237}," { ",[92,698,699],{"class":632},"command",[92,701,702],{"class":110},"?:",[92,704,705],{"class":102}," string",[92,707,708],{"class":237}," })?.command ",[92,710,711],{"class":110},"??",[92,713,714],{"class":106}," \"\"",[92,716,717],{"class":237},");\n",[92,719,720,723,726,729,732,735,738,741,744,747,750,753,755,758,760,763],{"class":94,"line":370},[92,721,722],{"class":110},"    if",[92,724,725],{"class":237}," (event.toolName ",[92,727,728],{"class":110},"===",[92,730,731],{"class":106}," \"bash\"",[92,733,734],{"class":110}," &&",[92,736,737],{"class":106}," /",[92,739,740],{"class":110},"\\b",[92,742,743],{"class":106},"rm",[92,745,746],{"class":102},"\\s",[92,748,749],{"class":110},"+",[92,751,752],{"class":106},"-rf",[92,754,740],{"class":110},[92,756,757],{"class":106},"/",[92,759,214],{"class":237},[92,761,762],{"class":98},"test",[92,764,765],{"class":237},"(cmd)) {\n",[92,767,768,771,774,777,780,783],{"class":94,"line":383},[92,769,770],{"class":110},"      return",[92,772,773],{"class":237}," { block: ",[92,775,776],{"class":102},"true",[92,778,779],{"class":237},", reason: ",[92,781,782],{"class":106},"\"rm -rf is blocked by guard.ts\"",[92,784,785],{"class":237}," };\n",[92,787,788],{"class":94,"line":403},[92,789,406],{"class":237},[92,791,792],{"class":94,"line":409},[92,793,794],{"class":237},"  });\n",[92,796,797],{"class":94,"line":415},[92,798,418],{"class":237},[15,800,801],{},"Then run Pi with it:",[83,803,805],{"className":85,"code":804,"language":87,"meta":88,"style":88},"pi -e ./guard.ts\n",[22,806,807],{"__ignoreMap":88},[92,808,809,811,814],{"class":94,"line":95},[92,810,159],{"class":98},[92,812,813],{"class":102}," -e",[92,815,816],{"class":106}," ./guard.ts\n",[15,818,819,820,822,823,826],{},"We ran the same test twice: same mock model, same prompt, same folder. Without the extension, Pi ran ",[22,821,24],{}," and the folder was gone. With it, the tool call came back as \"rm -rf is blocked by guard.ts\", the model was told why, and ",[22,824,825],{},"build/"," was still there.",[15,828,829],{},[457,830],{"alt":831,"src":832},"One extension, one saved folder — Pi blocks rm -rf with a 10-line TypeScript guard; the folder survives","/img/blog/pi-coding-agent-extension.jpg",[15,834,835,836,839,840,214],{},"To load an extension every time, put it in ",[22,837,838],{},"~/.pi/agent/extensions/",". For one project only, use ",[22,841,842],{},".pi/extensions/",[15,844,845,848,849,852],{},[30,846,847],{},"This is a seatbelt, not a sandbox."," A regex catches ",[22,850,851],{},"rm -rf",", not every way to delete a file. Pi's own security docs say the strongest protection is running Pi inside a container or VM.",[200,854,856],{"id":855},"packages-skills-and-prompt-templates","Packages, skills and prompt templates",[15,858,859],{},"Other people's extensions come as Pi packages. We installed one from npm:",[83,861,863],{"className":85,"code":862,"language":87,"meta":88,"style":88},"pi install npm:@langchain/langsmith-pi-extension\npi list\n",[22,864,865,874],{"__ignoreMap":88},[92,866,867,869,871],{"class":94,"line":95},[92,868,159],{"class":98},[92,870,144],{"class":106},[92,872,873],{"class":106}," npm:@langchain/langsmith-pi-extension\n",[92,875,876,878],{"class":94,"line":156},[92,877,159],{"class":98},[92,879,512],{"class":106},[15,881,882,883,886,887,890],{},"It was added to ",[22,884,885],{},"~/.pi/agent/settings.json"," and showed up in ",[22,888,889],{},"pi list"," straight away.",[15,892,893,894,897,898,901],{},"Packages can also come from git (",[22,895,896],{},"pi install git:github.com/user/repo",") or a local folder, and ",[22,899,900],{},"pi remove"," takes them out.",[15,903,904],{},"Packages run code with your permissions, so read the source before you install one.",[15,906,907],{},"Skills and prompt templates are lighter:",[52,909,910,924],{},[55,911,912,913,916,917,920,921,214],{},"Skills are folders with a ",[22,914,915],{},"SKILL.md",", in ",[22,918,919],{},"~/.pi/agent/skills/"," or ",[22,922,923],{},".pi/skills/",[55,925,926,927,930,931,934,935,938],{},"Prompt templates are Markdown files in ",[22,928,929],{},"~/.pi/agent/prompts/",". A file called ",[22,932,933],{},"review.md"," becomes the ",[22,936,937],{},"/review"," command.",[38,940,942],{"id":941},"where-pi-keeps-its-files","Where Pi keeps its files",[15,944,945],{},"Everything personal lives in one folder, and every project can add its own.",[947,948,949,962],"table",{},[950,951,952],"thead",{},[953,954,955,959],"tr",{},[956,957,958],"th",{},"Path",[956,960,961],{},"What it holds",[963,964,965,975,984,993,1002,1012,1022,1032],"tbody",{},[953,966,967,972],{},[968,969,970],"td",{},[22,971,885],{},[968,973,974],{},"Defaults and installed packages",[953,976,977,981],{},[968,978,979],{},[22,980,213],{},[968,982,983],{},"API keys and login tokens. Keep it private",[953,985,986,990],{},[968,987,988],{},[22,989,310],{},[968,991,992],{},"Custom endpoints and local models",[953,994,995,999],{},[968,996,997],{},[22,998,521],{},[968,1000,1001],{},"MCP servers for every project",[953,1003,1004,1009],{},[968,1005,1006],{},[22,1007,1008],{},"~/.pi/agent/AGENTS.md",[968,1010,1011],{},"Instructions for every project",[953,1013,1014,1019],{},[968,1015,1016],{},[22,1017,1018],{},"~/.pi/agent/SYSTEM.md",[968,1020,1021],{},"Replaces Pi's system prompt",[953,1023,1024,1029],{},[968,1025,1026],{},[22,1027,1028],{},"~/.pi/agent/sessions/",[968,1030,1031],{},"Every conversation, as files",[953,1033,1034,1040],{},[968,1035,1036,1039],{},[22,1037,1038],{},".pi/"," in a project",[968,1041,1042],{},"Project settings, MCP servers, extensions and skills",[15,1044,1045,1046,266,1049,1052],{},"Pi also reads ",[22,1047,1048],{},"AGENTS.md",[22,1050,1051],{},"CLAUDE.md"," from your project folder and its parents.",[15,1054,1055],{},[457,1056],{"alt":1057,"src":1058},"Where Pi keeps everything — one global folder for credentials and models, one .pi/ folder per project","/img/blog/pi-coding-agent-config.jpg",[15,1060,1061,1062,1065,1066,1069],{},"Two environment variables help on shared machines: ",[22,1063,1064],{},"PI_CODING_AGENT_DIR"," moves the whole agent folder, and ",[22,1067,1068],{},"PI_OFFLINE=1"," stops Pi's startup network checks.",[38,1071,1073],{"id":1072},"common-pi-errors-and-fixes","Common Pi errors and fixes",[15,1075,1076],{},"We triggered most of these ourselves on 1.4.0. The rest come from Pi's changelog and issue tracker.",[947,1078,1079,1092],{},[950,1080,1081],{},[953,1082,1083,1086,1089],{},[956,1084,1085],{},"Error",[956,1087,1088],{},"What it means",[956,1090,1091],{},"Fix",[963,1093,1094,1108,1119,1136,1149,1160,1176,1193,1210,1221,1232],{},[953,1095,1096,1099,1102],{},[968,1097,1098],{},"\"No API key found for the selected model.\"",[968,1100,1101],{},"Pi has no credential for that provider",[968,1103,1104,1105,1107],{},"Run ",[22,1106,209],{},", or export the provider's key variable",[953,1109,1110,1113,1116],{},[968,1111,1112],{},"\"No models available. Use /login to log into a provider via OAuth or API key.\"",[968,1114,1115],{},"No provider is set up at all",[968,1117,1118],{},"Same as above",[953,1120,1121,1126,1129],{},[968,1122,1123],{},[22,1124,1125],{},"401 ... \"authentication_error\",\"message\":\"invalid x-api-key\"",[968,1127,1128],{},"Anthropic rejected your key",[968,1130,1131,1132,1135],{},"Check for typos or a revoked key; don't trust ",[22,1133,1134],{},"pi auth check"," alone",[953,1137,1138,1143,1146],{},[968,1139,1140],{},[22,1141,1142],{},"OpenAI API error (401): ... Incorrect API key provided",[968,1144,1145],{},"OpenAI rejected your key",[968,1147,1148],{},"Create a new key and re-export it",[953,1150,1151,1154,1157],{},[968,1152,1153],{},"\"API key not valid. Please pass a valid API key.\" (400)",[968,1155,1156],{},"Gemini rejected your key",[968,1158,1159],{},"Check the key comes from AI Studio with the API enabled",[953,1161,1162,1167,1170],{},[968,1163,1164],{},[22,1165,1166],{},"Error: Model \"...\" not found. Use --list-models to see available models.",[968,1168,1169],{},"A typo, or a provider you haven't logged in to",[968,1171,1104,1172,1175],{},[22,1173,1174],{},"pi --list-models"," and copy the ID",[953,1177,1178,1183,1186],{},[968,1179,1180],{},[22,1181,1182],{},"Failed to load extension: Cannot find module '@earendil-works/pi-coding-agent'",[968,1184,1185],{},"An old Pi or a mixed install",[968,1187,1188,1189,1192],{},"Uninstall the old ",[22,1190,1191],{},"@mariozechner"," package and update",[953,1194,1195,1200,1203],{},[968,1196,1197],{},[22,1198,1199],{},"Package subpath './node.js' is not defined by \"exports\"",[968,1201,1202],{},"A broken third-party extension",[968,1204,1205,1206,1209],{},"Start with ",[22,1207,1208],{},"pi -ne"," (no extensions), then remove it",[953,1211,1212,1215,1218],{},[968,1213,1214],{},"\"localhost refused to connect\" during login",[968,1216,1217],{},"Windows had reserved the login port",[968,1219,1220],{},"Update to 1.1.0 or later",[953,1222,1223,1226,1229],{},[968,1224,1225],{},"\"Managed install marker is missing or invalid\"",[968,1227,1228],{},"A Windows PowerShell 5.1 file encoding bug",[968,1230,1231],{},"Fixed in 1.4.0; run the installer again",[953,1233,1234,1237,1240],{},[968,1235,1236],{},"Response truncated before completion",[968,1238,1239],{},"The model hit its output limit mid-answer",[968,1241,1242],{},"Switch to a model with a higher output limit, or break the task into smaller steps",[15,1244,1245],{},"That last one also had a nasty follow-on: before 1.4.0, a session could break for good after a truncated tool call, because providers rejected the leftover tool results. If old sessions refuse every message, update.",[38,1247,1249],{"id":1248},"pi-vs-claude-code-vs-opencode","Pi vs Claude Code vs OpenCode",[15,1251,1252],{},"All three are terminal coding agents. They differ most in models, defaults and how much they do for you.",[947,1254,1255,1270],{},[950,1256,1257],{},[953,1258,1259,1261,1264,1267],{},[956,1260],{},[956,1262,1263],{},"Pi",[956,1265,1266],{},"Claude Code",[956,1268,1269],{},"OpenCode",[963,1271,1272,1285,1299,1312,1326,1338],{},[953,1273,1274,1277,1280,1283],{},[968,1275,1276],{},"Licence",[968,1278,1279],{},"MIT, open source",[968,1281,1282],{},"Proprietary",[968,1284,1279],{},[953,1286,1287,1290,1293,1296],{},[968,1288,1289],{},"Models",[968,1291,1292],{},"30+ providers, plus any compatible endpoint",[968,1294,1295],{},"Claude models only",[968,1297,1298],{},"75+ providers, plus local models",[953,1300,1301,1304,1307,1310],{},[968,1302,1303],{},"MCP",[968,1305,1306],{},"Built in since September 2026",[968,1308,1309],{},"Yes",[968,1311,1309],{},[953,1313,1314,1317,1320,1323],{},[968,1315,1316],{},"Extending it",[968,1318,1319],{},"TypeScript extensions and packages",[968,1321,1322],{},"Plugins: skills, agents, hooks, MCP",[968,1324,1325],{},"JavaScript and TypeScript plugins",[953,1327,1328,1331,1334,1336],{},[968,1329,1330],{},"Sub-agents",[968,1332,1333],{},"Not built in; add with a package",[968,1335,1309],{},[968,1337,1309],{},[953,1339,1340,1343,1346,1349],{},[968,1341,1342],{},"Asks before acting",[968,1344,1345],{},"No",[968,1347,1348],{},"Yes, on first use of each tool by default",[968,1350,1351],{},"Mostly no; a few risky actions ask",[15,1353,1354,1355],{},"The short version: ",[30,1356,1357],{},"pick Claude Code if you want the most guardrails and only use Claude, OpenCode if you want the most built in, and Pi if you want the smallest core and plan to build your own.",[15,1359,1360],{},[457,1361],{"alt":1362,"src":1363},"Pi vs Claude Code vs OpenCode — smallest core: Pi; most guardrails: Claude Code; most built in: OpenCode","/img/blog/pi-coding-agent-comparison.jpg",[38,1365,1367],{"id":1366},"where-betterclaw-fits","Where BetterClaw fits",[15,1369,1370],{},"Pi is a coding agent that lives in your terminal, on your machine, while you watch it. That's exactly right for writing code.",[15,1372,1373],{},"It's not built for agents that should keep working when your laptop is closed, like a morning inbox summary, a weekly report or a support triage that runs every hour. That's what BetterClaw is for. Agents run in the cloud, connect to your apps, and keep a history of every run.",[15,1375,1376],{},"You bring your own key from any of 28+ providers with zero markup, the same way you do with Pi. Many people use both: Pi in the terminal for code, BetterClaw for the jobs that run on a schedule.",[38,1378,1380],{"id":1379},"the-takeaway","The takeaway",[15,1382,1383,1384,1387],{},"Pi gives you a small agent and the keys to everything else. That's its appeal and its main risk: ",[30,1385,1386],{},"it does what it's told, without asking",", until you add the rules yourself.",[15,1389,1390],{},"Install it with the new package name, test your key with a real prompt, add MCP servers if you need them, and write a guard extension before you point it at anything you care about.",[15,1392,1393,1394,214],{},"If any of this resonated and you want agents that run on their own, not just in your terminal, give BetterClaw a try. Starter is $19 a month for one agent, Pro is $49 a month for five, and every plan has a 7-day free trial. ",[1395,1396,1398],"a",{"href":1397},"/pricing","See full pricing",[38,1400,1402],{"id":1401},"frequently-asked-questions","Frequently Asked Questions",[15,1404,1405,1408,1409,1412,1413,1416,1417,214],{},[30,1406,1407],{},"How do I install Pi coding agent?"," On macOS or Linux, run ",[22,1410,1411],{},"curl -fsSL https://pi.dev/install.sh | sh",". On any system with Node.js 22.19 or newer, run ",[22,1414,1415],{},"npm install -g --ignore-scripts @earendil-works/pi-coding-agent",". Check it worked with ",[22,1418,1419],{},"pi --version",[15,1421,1422,1425,1426,1429,1430,1432,1433,1435],{},[30,1423,1424],{},"Does Pi support MCP?"," Yes, since version 0.99.0 (29 September 2026). Add a server with ",[22,1427,1428],{},"pi mcp add \u003Cname> -- \u003Ccommand>",", check it with ",[22,1431,517],{},", and Pi saves it to ",[22,1434,521],{},". Older guides that say Pi has no MCP are out of date.",[15,1437,1438,1441,1442,1444],{},[30,1439,1440],{},"What happened to @mariozechner/pi-coding-agent?"," It's deprecated. Pi moved to the ",[22,1443,60],{}," package in May 2026, and the old package stopped at 0.73.1. Uninstall the old one before installing the new one so you're not running two versions.",[15,1446,1447,1450,1451,214],{},[30,1448,1449],{},"Which models can Pi use?"," More than 30 providers, including Anthropic, OpenAI, Google Gemini, OpenRouter, DeepSeek, Groq and xAI, plus subscription logins such as GitHub Copilot and ChatGPT. Local models work through any OpenAI-compatible endpoint in ",[22,1452,1453],{},"models.json",[15,1455,1456,1459],{},[30,1457,1458],{},"Does Pi ask before running commands?"," No. Pi's docs say it \"does not ask for approval before every tool call.\" Add an extension that blocks or confirms risky commands, and run Pi in a container or VM for real isolation.",[15,1461,1462,1465,1466,348,1469,256,1472,256,1475,256,1477,1480,1481,1483],{},[30,1463,1464],{},"Where is the Pi config file?"," Pi keeps everything in ",[22,1467,1468],{},"~/.pi/agent/",[22,1470,1471],{},"settings.json",[22,1473,1474],{},"auth.json",[22,1476,1453],{},[22,1478,1479],{},"mcp.json",", plus extensions, skills, prompts and sessions. Projects can add a ",[22,1482,1038],{}," folder, which loads after you trust it.",[1485,1486,1487],"style",{},"html pre.shiki code .s7eDp, html code.shiki .s7eDp{--shiki-default:#6F42C1}html pre.shiki code .sYu0t, html code.shiki .sYu0t{--shiki-default:#005CC5}html pre.shiki code .sYBdl, html code.shiki .sYBdl{--shiki-default:#032F62}html pre.shiki code .sD7c4, html code.shiki .sD7c4{--shiki-default:#D73A49}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html pre.shiki code .sgsFI, html code.shiki .sgsFI{--shiki-default:#24292E}html pre.shiki code .sqxcx, html code.shiki .sqxcx{--shiki-default:#E36209}",{"title":88,"searchDepth":156,"depth":156,"links":1489},[1490,1491,1492,1498,1499,1502,1503,1504,1505,1506,1507],{"id":40,"depth":156,"text":41},{"id":74,"depth":156,"text":75},{"id":194,"depth":156,"text":195,"children":1493},[1494,1495,1496,1497],{"id":202,"depth":334,"text":203},{"id":220,"depth":334,"text":221},{"id":303,"depth":334,"text":304},{"id":428,"depth":334,"text":429},{"id":463,"depth":156,"text":464},{"id":568,"depth":156,"text":569,"children":1500},[1501],{"id":855,"depth":334,"text":856},{"id":941,"depth":156,"text":942},{"id":1072,"depth":156,"text":1073},{"id":1248,"depth":156,"text":1249},{"id":1366,"depth":156,"text":1367},{"id":1379,"depth":156,"text":1380},{"id":1401,"depth":156,"text":1402},"Guides","2026-10-26","Install Pi 1.4, connect a model with /login or an API key, add MCP servers and extensions, and fix the common errors. Every command tested.","md",false,"/img/blog/pi-coding-agent-setup.jpg",null,{},"/blog/pi-coding-agent-setup","10 min read",{"title":5,"description":1510},"blog/pi-coding-agent-setup",[1521,1522,1523,1524,1525,1526,1527],"pi coding agent","pi coding agent install","pi agent setup","pi coding agent mcp","pi coding agent extensions","pi coding agent models","earendil pi","56OjywTWQyP8lYrvV06IScf2dHP2aHhR0p834dyX9qY",[1530,1539,1548],{"stem":1531,"title":1532,"description":1533,"date":1534,"image":1535,"category":1536,"redirected":1512,"author":1537,"readingTime":1538},"blog/231k-weekly-impressions-two-people-zero-ad-spend","How We Got 231K Weekly Google Impressions With 2 People and $0 Ad Spend","We went from 769 to 1,952 weekly clicks in 10 weeks with no ads. Here's the GSC data, what flopped, and the content formula we'd use if starting over.","2026-07-15","/img/blog/231k-weekly-impressions-two-people-zero-ad-spend.jpg","Strategy",{"name":7,"role":8,"avatar":9,"bio":10},"9 min read",{"stem":1540,"title":1541,"description":1542,"date":1543,"image":1544,"category":1545,"redirected":1512,"author":1546,"readingTime":1547},"blog/agents-md-best-practices","AGENTS.md Best Practices: How Long It Should Be, Template, Examples","How long AGENTS.md should be (under 100 lines), a copy-paste template, examples, how Codex and Claude Code load it, and how to stop rules piling up.","2026-06-11","/img/blog/agents-md-best-practices.jpg","Best Practices",{"name":7,"role":8,"avatar":9,"bio":10},"16 min read",{"stem":1549,"title":1550,"description":1551,"date":1552,"image":1553,"category":1554,"redirected":1512,"author":1555,"readingTime":1556},"blog/ai-agent-frameworks","Best AI Agent Frameworks in 2026: LangGraph, CrewAI, Claude Agent SDK, Google ADK and More","LangGraph, CrewAI, Claude Agent SDK, Pydantic AI, Google ADK and AX, Microsoft Agent Framework: current versions, what each is best at, when to skip code.","2026-05-26","/img/blog/ai-agent-frameworks.jpg","Comparison",{"name":7,"role":8,"avatar":9,"bio":10},"15 min read",1793174216436]