Pi Coding Agent

From Master of Neuroscience Wiki

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.

Pi Coding Agent Error : 500 unexpected message role developer

If you see this

Error: 500: {"message":"unexpected message role \"developer\"","type":"api_error","param":null,"code":null}

you need to add "supportsDeveloperRole": false to /root/.pi/agent/models.json : 

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "compat": {
        "supportsDeveloperRole": false
      },
      "models": [
        {
          "id": "qwen3-coder-next:latest",
          "reasoning": false,
          "compat": {
            "thinkingFormat": "qwen"
          },
          "contextWindow": 262144,
          "maxTokens": 262144
        },
        {
          "id": "qwen3.8:latest",
          "reasoning": true,
          "compat": {
            "thinkingFormat": "qwen"
          },
          "contextWindow": 262144,
          "maxTokens": 262144,
          "options": {
            "reasoning_effort": "xhigh"
          }
        }
      ]
    }
  }
}

Running Qwen 3.8 locally

ollama: smtek/Qwen3.8-27B:IQ2_M-256k on 24GB RTX3090

Quants from Q2 up to Q5 from Unsloth K_M and UD_K_XL and builds for 12, 16 and 24 GB: https://ollama.com/smtek/Qwen3.8-27B


[models.json] obviously you want to change your baseUrl!

{
  "providers": {
    "ollama": {
      "baseUrl": "http://gate2.neuro.uni-bremen.de:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "compat": {
        "supportsDeveloperRole": false
      },
      "models": [
        {
          "id": "smtek/Qwen3.8-27B:IQ2_M-256k",
          "reasoning": true,
          "compat": {
            "thinkingFormat": "qwen"
          },
          "contextWindow": 196608,
          "maxTokens": 16384
        }
      ]
    }
  }
}

[settings.json]

{
  "packages": [
    "npm:pi-subagents",
    "npm:pi-mcp-adapter",
    "npm:@narumitw/pi-lsp",
    "npm:pi-agent-browser-native",
    "npm:pi-web-access",
    {
      "source": "npm:pi-agent-extensions",
      "extensions": [
        "!**/whimsical/**"
      ]
    },
    "npm:pi-codex-goal",
    "npm:context-mode",
    "npm:pi-hermes-memory"
  ],
  "lastChangelogVersion": "0.84.2",
  "theme": "dark",
  "defaultProvider": "ollama",
  "defaultModel": "smtek/Qwen3.8-27B:IQ2_M-256k",
  "retry": {
    "enabled": true,
    "maxRetries": 5,
    "baseDelayMs": 5000,
    "provider": {
      "timeoutMs": 3600000,
      "maxRetries": 0,
      "maxRetryDelayMs": 60000
    }
  },
  "httpIdleTimeoutMs": 1800000
}

[hermes-memory-config.json]

{
  "llmModelOverride": "smtek/Qwen3.8-27B:IQ2_M-256k",
  "llmThinkingOverride": "off",
  "consolidationTimeoutMs": 600000,
  "temperature": 0.1
}

Installing Ollama:

as root:

curl -fsSL https://ollama.com/install.sh | sh
mkdir /etc/systemd/system/ollama.service.d

Optional:

Setting the model directory (i.e. on a SSD) and making OLLAMA via port 11434 available for other computers

[/etc/systemd/system/ollama.service.d/override.conf]

[Service]
Environment="OLLAMA_MODELS=/ollama"
Environment="OLLAMA_HOST=0.0.0.0:11434"

still as root:

mkdir -p /ollama
chown -R ollama:ollama /ollama
chmod -R u+rwX /ollama

END OPTIONAL still as root

systemctl enable ollama
systemctl start ollama
systemctl status ollama

as normal user (or root):

ollama pull smtek/Qwen3.8-27B:IQ2_M-256k

Now it should run. For testing:

ollama run smtek/Qwen3.8-27B:IQ2_M-256k

Qwen 3.8 Flash Next on CPU

dual 2014-era Haswell CPU with 512GB (UD-Q4_K_XL)

"predicted_per_token_ms":481.13217460317463

"predicted_per_second":2.0784309443133253

services:
  llama-cpp:
    image: ghcr.io/ggml-org/llama.cpp:full
    container_name: llama-cpp-qwen3-flash
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - /hf/models:/root/.cache/llama.cpp   # caches the downloaded GGUF here
    cap_add:
      - SYS_NICE      
    entrypoint: ["/app/tools.sh"]
    # UD-IQ4_XS
    command: >
      --server
      -hf unsloth/Qwen3.8-Flash-Next-GGUF:UD-Q4_K_XL 
      -c 8192
      -t 16
      --numa distribute
      --host 0.0.0.0
      --port 8080
    environment:
      - LLAMA_CACHE=/root/.cache/llama.cpp

2019-era AMD EPYC 7282 with 256GB (UD-IQ4_XS)

"predicted_per_token_ms":150.5311304347826

"predicted_per_second":6.643144159694255

services:
  llama-cpp:
    image: ghcr.io/ggml-org/llama.cpp:full
    container_name: llama-cpp-qwen3-flash
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - /hf/models:/root/.cache/llama.cpp
    cap_add:
      - SYS_NICE
    entrypoint: ["/app/tools.sh"]
    command: >
      --server
      -hf unsloth/Qwen3.8-Flash-Next-GGUF:UD-IQ4_XS
      -c 8192
      -t 16
      --numa distribute
      --host 0.0.0.0
      --port 8080
    environment:
      - LLAMA_CACHE=/root/.cache/llama.cpp

Tested with

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Hello! Write a brief 2-sentence greeting."}
    ],
    "max_tokens": 64
  }'
Retrieved from "https://mscneuro.neuro.uni-bremen.de/index.php?title=Pi_Coding_Agent&oldid=1014"
Powered by MediaWiki