Pi Coding Agent

Basis tool

npm install -g @earendil-works/pi-coding-agent

Extensions

# Important!!! Go to your cd ~ if you use pi install !!!
cd ~
pi install npm:pi-subagents
pi install npm:pi-mcp-adapter
pi install npm:@narumitw/pi-lsp
pi install npm:pi-agent-browser-native
pi install npm:pi-web-access
pi install npm:pi-agent-extensions
pi install npm:pi-codex-goal
pi install npm:context-mode
pi install npm:pi-hermes-memory

Claude says:

pi-subagents — Lets Pi delegate work to focused child agents instead of doing everything in one long context. It ships ready-made roles (scout, researcher, worker, reviewer, oracle) that run in isolated sessions, in the foreground or background, and can be steered mid-run. Install it if you want a "second set of eyes" for code review, research, or parallel work without polluting your main conversation.

pi-mcp-adapter — Connects Pi to MCP (Model Context Protocol) servers through a single proxy tool instead of registering every individual tool up front, which normally costs 10,000+ tokens per server. Install it if you want to use MCP servers (browsers, databases, search APIs, etc.) with Pi without burning through your context window.

@narumitw/pi-lsp — Wires real language servers into Pi so it gets actual diagnostics and code actions (not just guesses) across languages like TypeScript, Python, Rust, Go, and more. Install it if you want Pi's edits checked against a genuine compiler/linter instead of relying purely on the model's judgment.

pi-agent-browser-native — Exposes browser automation as a native Pi tool (built on the agent-browser project), so the agent can open pages, click around, and inspect results directly instead of shelling out through bash. Install it if your workflows involve interacting with live web pages or web apps.

pi-web-access — Gives Pi web search, URL fetching, GitHub repo cloning, PDF extraction, and YouTube/video understanding, with support for many search providers (Brave, Tavily, Kagi, self-hosted SearXNG, etc.). Install it if you want Pi to research things on the open web as part of its normal workflow.

pi-agent-extensions — A bundle of 17 smaller extensions and themes in one install: session search, structured question-asking, session hand-offs, a status footer, review tooling, and more. Install it as a convenient "starter pack" instead of hunting down and installing each small quality-of-life extension separately.

pi-codex-goal — Adds Codex-style goal tracking: a /goal command plus tools so Pi can track a long-running objective, verify completion, and resume it correctly after a session is reloaded or forked. Install it for long or multi-step tasks where you want the agent to stay anchored to a single, verifiable objective instead of drifting.

context-mode — A context-window optimizer that sandboxes heavy tool output (bash logs, search results, etc.) to files instead of dumping it all into the conversation, cutting context usage substantially, and also persists session memory and enforces consistent tool-output routing. Install it if your Pi sessions are running out of context quickly due to verbose tool output.

pi-hermes-memory — Gives Pi persistent memory across sessions: it remembers facts, corrections, and past failures, supports full-text search over old conversations ("what did we discuss about auth?"), and scans everything it stores for secrets before saving. Install it if you're tired of Pi forgetting everything each time you start a new session.

In ~/.pi/agent/settings.json I am replacing "npm:pi-agent-extensions", with

{
      "source": "npm:pi-agent-extensions",
      "extensions": [
        "!**/whimsical/**"
      ]
    },

Update extension

pi update --extensions

Academic Cloud

~/.pi/agent/models.json

{
  "providers": {
    "academiccloud": {
      "baseUrl": "https://chat-ai.academiccloud.de/v1",
      "api": "openai-completions",
      "apiKey": "<your-academiccloud-api-key>",
      "models": [
        {
          "id": "qwen3-coder-next",
          "reasoning": false,
          "compat": {
            "thinkingFormat": "qwen"
          },
          "contextWindow": 262144,
          "maxTokens": 262144
        }
      ]
    }
  }
}

tmux

If you want to use tmux as terminal then you need to set

.tmux.conf

set -g mouse on
set -g extended-keys on
set -g extended-keys-format csi-u

Multi-Agent Workflows with pi-subagents

Delegating work to sub-agents keeps your main session clean and scalable. When you delegate a heavy task—such as searching a large codebase, inspecting logs, or analyzing dependencies—the sub-agent executes it in its own isolated context window. Once finished, it returns only the final summary to your main session, keeping all intermediate detail and token bloat out of your primary conversation history.

Note: Sub-agent capabilities require the pi-subagents extension documented earlier on this page. They are not enabled in base Pi by default.

Setting Up Project-Local Sub-Agents

1. Open your project directory and launch Pi.
2. Prompt Pi to generate an AGENTS.md file along with initial agent definitions tailored to your stack.
   • Example prompt: "Analyze this project and generate an AGENTS.md outlining our agent architecture, plus sub-agent definitions for scout, worker, and reviewer roles."
3. Pi will create AGENTS.md in your project root, along with individual sub-agent configuration files in your project's .pi/agents/ directory (e.g., .pi/agents/scout.md, .pi/agents/worker.md).

Agent Configuration & File Locations

Sub-agents use Markdown files with YAML frontmatter to define their prompt instructions, tool permissions, and model parameters:

• Project-Specific Agents: .pi/agents/*.md (scoped to the current repository; checked into Git so the whole team benefits).
• Global Agents: ~/.pi/agents/*.md (available across all projects on your machine).

Best Practices for Session Workflows

• Include AGENTS.md in your opening prompt: Start new sessions with a standard directive like "Read AGENTS.md first to load project context." This instantly grounds Pi in your team's workflow without manual setup each time.
• Persist project knowledge: Instruct Pi to update AGENTS.md whenever core architecture, technology choices, or coding conventions evolve. Treating AGENTS.md as living documentation ensures future agent sessions stay aligned without repeated prompt engineering.