Setting Up Pi Agent: A Terminal Coding Agent with Zero Vendor Lock-in

What is Pi Agent?

Pi Agent (yes, that’s the real URL) is an open-source terminal-based AI coding agent by Mario Zechner (libGDX creator). It’s like Claude Code or Codex CLI, but with a key difference: no vendor lock-in. It supports dozens of LLM providers out of the box — Anthropic, OpenAI, Google, Groq, Cerebras, OpenRouter, Mistral, HuggingFace, ZAI, and more — and you can add custom providers via extensions.

With 33k+ GitHub stars, it’s one of the most popular open-source coding agents. The codebase lives in a monorepo at badlogic/pi-mono.

Why Pi Agent?

I already use Hermes Agent as my daily driver and Claude Code / Codex as subagents. So why add another one?

• Free model access via Google Antigravity (Cloud Code Assist) — Claude Opus 4, Claude Sonnet 4, Gemini 3 Flash, all at no cost
• Shared skill ecosystem — Pi skills from badlogic/pi-skills also work with Claude Code and Codex
• Extensions system — write TypeScript extensions for custom tools, providers, and UI widgets
• Zero runtime cost — free providers (Groq, Cerebras, Antigravity) mean I can run agents all day without watching a billing meter

Installation

I use NVM to manage Node.js versions. Gitnexus requires Node 20, so I keep multiple versions around:

1
# Gitnexus uses Node 20
2
nvm use 20
3

4
# Pi Agent needs Node 25
5
nvm use 25
6
npm i -g @mariozechner/pi-coding-agent

Rather than manually switching Node versions every time, I created a wrapper script at ~/.local/bin/pi:

1
#!/usr/bin/env bash
2
set -euo pipefail
3

4
export NVM_DIR="${NVM_DIR:-$HOME/.config/nvm}"
5
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
6

7
NODE_VERSION="25"
8

9
if ! nvm ls "$NODE_VERSION" | grep -q "$NODE_VERSION"; then
10
  echo "Node $NODE_VERSION not found. Installing..." >&2
11
  nvm install "$NODE_VERSION"
12
fi
13

14
nvm exec "$NODE_VERSION" pi "$@"

This is the same pattern I use for Gitnexus (which wraps npx gitnexus@latest with Node 22). Each tool gets its own Node version, no conflicts.

Configuration

Pi stores its config in ~/.pi/agent/:

1
~/.pi/agent/
2
├── settings.json      # Default provider, model, theme
3
├── auth.json          # API keys and OAuth tokens
4
├── models.json        # Custom provider endpoints
5
├── extensions/        # TypeScript extensions
6
├── prompts/           # Prompt templates
7
├── skills/            # Symlinked shared skills
8
└── git/               # Installed packages

1
{
2
  "providers": {
3
    "zai": {
4
      "baseUrl": "https://api.z.ai/api/coding/paas/v4"
5
    }
6
  }
7
}

Extensions

Pi’s extension system is where it really shines. Extensions are TypeScript files that can register tools, hook into events, and add UI widgets. I created four:

1
export default function (pi: any) {
2
  let agentStartMs: number | null = null;
3

4
  pi.on("agent_start", () => { agentStartMs = Date.now(); });
5

6
  pi.on("agent_end", (event: any, ctx: any) => {
7
    if (!ctx.hasUI || agentStartMs === null) return;
8
    const elapsedMs = Date.now() - agentStartMs;
9
    agentStartMs = null;
10
    if (elapsedMs <= 0) return;
11

12
    let output = 0;
13
    for (const message of event.messages) {
14
      if (message.role !== "assistant") continue;
15
      output += message.usage?.output || 0;
16
    }
17
    if (output <= 0) return;
18

19
    const tps = output / (elapsedMs / 1000);
20
    ctx.ui.notify(`TPS ${tps.toFixed(1)} tok/s`, "info");
21
  });
22
}

1
export default function (pi: any) {
2
  const DANGEROUS = [
3
    /\brm\s+(-[rfRF]+\s+|.*--force\b)/,
4
    /\bkubectl\s+delete\b/,
5
    /\bgit\s+push\s+.*--force\b/,
6
    /\bDROP\s+(TABLE|DATABASE|SCHEMA)\b/i,
7
    // ...more patterns
8
  ];
9

10
  pi.on("tool_call", async (event: any, ctx: any) => {
11
    if (event.toolName !== "bash") return;
12
    for (const p of DANGEROUS) {
13
      if (p.test(event.input?.command)) {
14
        const ok = await ctx.ui.confirm("Dangerous command", event.input.command);
15
        if (!ok) return { block: true, reason: "Blocked by permission-gate" };
16
        break;
17
      }
18
    }
19
  });
20
}

Prompt Templates

Prompt templates are markdown files in ~/.pi/agent/prompts/ that you invoke with /command. I set up two:

• /wr — Wraps up a task: stages only changed files, writes a conventional commit message, optionally posts a GitHub comment, and pushes
• /is — Analyzes GitHub issues: reads the full issue + comments, checks bd (beads) for matching tasks, traces code to find the real root cause

These mirror the workflow patterns I already use in Claude Code via Hermes.

Shared Skills

Pi reads skills from ~/.agents/skills/ — a shared directory that Claude Code and Codex also use. I have 34 skills symlinked there, covering everything from Astro blog conventions to Go Fiber patterns to K8s deployment workflows.

On top of that, I installed the pi-skills package which adds:

• brave-search — Web search via Brave API
• browser-tools — Chrome DevTools Protocol automation
• transcribe — Speech-to-text via Groq Whisper
• youtube-transcript — Fetch video transcripts
• Google CLIs — Drive, Gmail, and Calendar CLI tools

1
pi install git:github.com/badlogic/pi-skills

What I Learned

1. NVM --delete-prefix is a thing — If you set a custom npm prefix (e.g., ~/.local/share/npm-global), NVM will complain every time you open a terminal. Pi spawns npm install -g internally, so it needs a prefix it can write to. The wrapper script approach avoids this entirely since nvm exec handles the Node context.

2. Credentials may be redacted — When AI agents read files containing API keys, the values can be truncated by content safety filters. Always verify credential values manually after copying them between files.

3. Pi can’t distinguish plan tiers — It lists every model a provider offers, regardless of what your subscription actually covers. Check your provider’s plan page and note which models work.

4. The extension API is clean — Registering tools, hooking into lifecycle events, and adding UI widgets all follow a consistent pattern via the ExtensionAPI object. The author’s own extensions in the pi-mono repo are great reference material.

5. Pi skills are cross-agent — Skills written for Pi also work with Claude Code and Codex CLI. This means investment in skill development pays off across your entire agent toolkit.

6. Pi doesn’t know which model it’s running on — Pi has no runtime awareness of which provider or model is actually serving its requests. It knows its own agent name (“Pi”) but nothing about the LLM behind it. For accurate attribution in generated content, inject the model name via system prompt or settings.

7. Pi can do deep autonomous debugging — I asked Pi to figure out why the first request after bun run dev took 13 seconds. It systematically eliminated suspects (fonts, content loading, image processing, Vite pre-bundling, Astro SSR), traced the bottleneck to @tailwindcss/vite compiling Tailwind CSS 4 + DaisyUI 5 on first request, wrote a full blog post about it, and even created an SVG hero image — all in a single session using ~159k input / 39k output tokens. The entire process was autonomous: Pi read source files, ran curl benchmarks, analyzed Vite’s transform pipeline, and produced publication-ready output with no hand-holding.

This article was written by Hermes Agent (GLM-5-Turbo | ZAI).