Good defaults for Pi: ten changes to make on day one

This is the highest-leverage change and it costs nothing. Pi has two instruction channels, and the distinction matters:

• AGENTS.md — project context, loaded at startup from ~/.pi/agent/, then parent directories walking up, then the current directory, all concatenated.
• APPEND_SYSTEM.md — appended directly to the system prompt, which gives these rules higher authority than anything in AGENTS.md. SYSTEM.md replaces the default prompt entirely; APPEND_SYSTEM.md adds to it, which is what you want.

The rules people converge on are behavioural, not stack-specific. A serviceable starting set, adapted from published configs:

- Read relevant local files first when the answer is in the codebase.
  Research online only when it is not. Before making a big change based
  on online findings, confirm with me first.
- Explain risky file edits and destructive commands before executing.
- Write simply. Avoid AI-slop language – no flowery adjectives,
  unnecessary adverbs, or overly formal phrasing.
- Run the project's check/lint command after code changes.
- Do not run production migrations locally.

Keep the global AGENTS.md thin — a note about which stacks you usually work in, plus an explicit instruction to ask when the current project doesn't match any of them. That last clause prevents the agent from imposing a framework on a plain HTML folder.

Why first: every other item on this list is a tool. This one is the only change that shapes how the model behaves in every session regardless of tooling, and it survives reinstalls, version bumps, and package churn.

Pi normalises across providers at the API layer — Anthropic, OpenAI, Google, Azure, Bedrock, Mistral, Groq, Cerebras, xAI, Hugging Face, Kimi, MiniMax, NVIDIA, OpenRouter, Ollama and more — and lets you switch mid-session. The consensus practice is not "pick the best model" but "scope three or four and move between them by keystroke."

The shortcuts that make this workable:

A representative lineup from a practitioner running Pi daily: a strong reasoning model at high thinking level as the default, a cheap fast model for bulk or repetitive work such as scraping and file operations, and a third as a fallback for rate limits or second opinions. The specific models churn every few months; the shape of the lineup does not.

If you already pay for a subscription, check whether Pi can use it directly before buying API credits — that is one of the recurring reasons people cite for adopting it. For anything OpenAI-compatible, including a local Ollama instance, add it in ~/.pi/agent/models.json:

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [{ "id": "qwen2.5-coder:7b" }]
    }
  }
}

This is the single most commonly installed capability, and the first thing you will miss. A coding agent that cannot read the docs for the library it is using will confidently hallucinate an API that was renamed two releases ago.

There is agreement on the need and disagreement on the package — enough that at least one practitioner has written a whole post comparing the options. Two of the widely used choices:

# Search, page fetch, YouTube transcripts, GitHub repo exploration
pi install npm:pi-web-access

# Alternative: search + page fetching
pi install npm:pi-tinyfish

pi-web-access works out of the box with Exa and no API key, with optional keys for Perplexity, Exa, or Gemini. It reads config from ~/.pi/web-search.json:

{
  "provider": "exa",
  "allowBrowserCookies": false,
  "summaryModel": "deepseek/deepseek-v4-flash",
  "workflow": "none",
  "curatorTimeoutSeconds": 20
}

Note the summaryModel field — pointing summarisation at a cheap fast model rather than your expensive default is a small optimisation that pays back constantly, since search results get summarised on nearly every lookup.

Pair this with the APPEND_SYSTEM.md rule from item 1 that tells the agent to check local files before reaching for the network. Without that instruction, a search tool becomes a reflex rather than a fallback.

Not an install. A workflow change, and the one that most consistently gets named as Pi's standout feature.

Sessions auto-save to ~/.pi/agent/sessions/, organised by working directory, as plain JSONL on local disk. Branching, forking, and resuming are first-class rather than bolted on — which matters more than it sounds, because it changes what you are willing to attempt. If a risky refactor can be abandoned by jumping back up the tree, you try the risky refactor.

Compaction runs automatically as you approach the context limit, and is itself customisable via extensions — topic-based compaction, code-aware summaries, or a different model doing the summarising.

Also learn the steering distinction, which trips up everyone for the first week. While Pi is working, Enter sends a steering message that is delivered after the current tool completes and interrupts the remaining ones — use it to correct course mid-task. Alt+Enter queues a follow-up delivered after the work finishes.

One more, if you work in the open: Pi's maintainer asks people doing open-source work to publish their sessions, because real workflow data improves models, prompts, and evaluations. badlogic/pi-share-hf handles publishing to Hugging Face.

Ranked fifth by how many people do it, but arguably it belongs at two by how much it matters. Pi has no permission system. There is no popup between the model and rm -rf. If you need real boundaries, the project's own guidance is to containerise or sandbox, and the repo documents three patterns in packages/coding-agent/docs/containerization.md:

• Gondolin extension — keeps Pi and your provider credentials on the host while routing built-in tools and ! commands into a local Linux micro-VM. The credential-isolation property is the interesting part.
• OpenShell — runs the entire Pi process inside a policy-controlled sandbox.
• A third pattern documented alongside these in the same file.

A lighter middle ground that circulates in community configs is a bash-guard extension that blocks dangerous commands outright — available in the pi-config collection. It is not a sandbox and should not be mistaken for one, but it catches the obvious footguns. Chapter two, item 11 covers the mode-based permission packages that have since become the standard middle ground.

The auditability angle is worth noting for anyone in a regulated environment: sessions are plain JSONL on local disk, which makes it straightforward to show an assessor exactly what an AI tool did inside a codebase. Combined with a self-hosted inference endpoint, prompts need never traverse a public model API.

Consider also using --ignore-scripts during dependency installs, which disables lifecycle scripts — a defensible default given that the whole extension ecosystem runs as you.

Pi's footer shows working directory, git branch, current model, thinking level, and context usage. Most people end up modifying it, in one of two directions.

The install route:

pi install npm:@juanibiapina/pi-powerbar

The Pi-native route is more in keeping with the tool's philosophy, and is the clearest small example of the "ask Pi to build it" pattern actually working. One practitioner described the footer they wanted — current folder, git branch with a dirty marker, model name, thinking level, active goal, and a compact context bar — and Pi wrote the TypeScript extension. It lives at ~/.pi/agent/extensions/minimal-footer.ts and loads on every startup.

If you have never written a Pi extension, this is the right first one. It is visible, low-stakes, and teaches you the extension API in an afternoon. The same author's whimsical.ts — rotating status phrases while the agent thinks, adapted from an original by Armin Ronacher — is an even smaller starting point.

pi install npm:pi-codex-goal

Adds three tools — get_goal, create_goal, update_goal — so a task spanning many prompts holds its objective without you restating context each turn.

The case for it is empirical rather than theoretical. One documented run: 285,000 URLs scraped from a website, roughly 1.5 hours, about a dollar in API cost on a cheap fast model, with goal tracking keeping the task coherent as the session grew long. That is the class of work this exists for — anything where the session outlives your attention span.

If your work is mostly short interactive edits, skip it. The value scales with task duration, and for a fifteen-minute session it is overhead. For the smaller, more frequently useful sibling — a visible checklist rather than a durable objective — see chapter two, item 14.

These are the two features Pi most conspicuously omits, and the omission is deliberate. Both are available:

pi install npm:pi-subagents    # isolated parallel work
pi install npm:pi-plan          # read-only planning, approval-gated

The narumiruna extension monorepo also publishes a Codex-like read-only /plan collaboration mode and a delegation extension supporting single, parallel, or chained execution — installable individually under the @narumitw scope, so you take only what you need.

Armin Ronacher's mitsupi package takes a different angle on the same problem with /discuss, a planning interviewer mode: it inspects the project first, asks focused questions in short rounds, and stops once the plan is clear enough to implement. That is planning as conversation rather than as a mode switch, and it is worth trying before you install a formal plan mode.

I have ranked this eighth rather than excluded it because the disagreement is real. Some people find sub-agents essential for decomposable work; others find the coordination overhead exceeds the parallelism gain and note that Pi's own design bet is that you rarely need them. Try the tool without them first, so you can tell whether you are solving a problem or importing a habit from another agent.

pi install npm:pi-mcp-adapter

Pi has no built-in MCP client. The adapter connects it to any MCP-compatible server — GitHub, Playwright, Postgres, whatever you already have running.

Ranked low deliberately. MCP is the mechanism Pi's philosophy explicitly pushes back against: the argument is that the most powerful architecture is a minimal agent that extends itself by writing code, rather than one accumulating downloaded integrations. For a service you genuinely already run and whose MCP server is maintained, the adapter is the pragmatic choice. For anything else, asking Pi to write a thirty-line extension calling the API directly is usually faster to get working and far easier to debug than a protocol layer in between.

Two related capabilities in the same tier. A browser extension gives Pi real page interaction — screenshots, clicking, form filling, QA checks — which complements search rather than replacing it:

pi install npm:pi-agent-browser-native

And if your chosen model lacks vision, a proxy routes images to one that has it, batching multiple images and caching repeated screenshots via perceptual hashing:

pi install npm:pi-vision-proxy

Write the corresponding APPEND_SYSTEM.md rule capability-first rather than naming a provider — "if the current model lacks vision, use the proxy" survives you switching models next month.

Last, and last for a reason.

Memory. pi install npm:pi-hermes-memory carries project conventions, preferences, and past decisions across sessions. The argument for it is that Pi otherwise starts fresh every time. The counter-argument is that AGENTS.md plus the session tree already covers most of what people want from memory, with the advantage of being inspectable text you wrote deliberately rather than accumulated inferences you did not.

Bulk installers. npx @robzolkos/lazypi installs Pi if absent and adds 60-plus skills, 76 themes, MCP support, sub-agents, and memory in one command, with an interactive picker. The luongnv89/pi-extensions repo offers a similar one-command install. Both are legitimate ways to survey the ecosystem quickly. Both are also the opposite of what Pi is for, and the more experienced advice runs the other direction:

I tried more packages but kept only what I actually use. The simpler the setup, the better.

If you use one, treat it as a research tool: install everything, use it for a fortnight, then uninstall what you did not touch. Everything installed lives under ~/.pi/agent/ and works independently, so removal is clean.

Themes. Drop them in ~/.pi/agent/themes/ or .pi/themes/, or ship them in a package. Purely cosmetic, genuinely nice, correctly ranked last.