Pi Coding Agent: Four Tools Tutorial

Important: Anthropic Limitation

Pi cannot use your paid Claude subscription. It only accepts API tokens, which are more expensive than the subscription. This is the biggest blocker for users who rely on Claude models.

Using OpenRouter

Set your API key and restart the agent:

1
export OPENROUTER_API_KEY="your-api-key"
2
pi

Then select OpenRouter via /model to choose from available models like Google, Meta, Anthropic, and more.

Using Ollama for Local Models

1
# Install Ollama
2
brew install ollama  # macOS
3
curl -fsSL https://ollama.com/install.sh | bash  # Linux
4

5
# Pull a coding model
6
ollama pull qwen2.5-coder:7b
7

8
# Configure Pi (~/.pi/models.json)
9
{
10
  "provider": "ollama",
11
  "model": "qwen2.5-coder:7b",
12
  "url": "http://localhost:11434"
13
}

Read

Reads files and displays their contents. Supports glob patterns:

1
read src/App.tsx
2
read src/**/*.ts

Write

Creates new files or overwrites existing ones. Provide full file content:

1
write src/new-file.ts
2
export function hello() {
3
  return "Hello, Pi!";
4
}

Edit

Surgical text replacement — provide exact string to find and its replacement:

1
edit src/App.tsx
2
// Old: export function App()
3
// New: export default function App()

Bash

Runs terminal commands. Every coding task uses this — installing dependencies, running tests, git operations:

1
bun install
2
git add . && git commit -m "feat: add new feature"
3
bun test run

Key insight: End your command with a period (.) to signal task completion. Without it, Pi keeps working.

Slash Commands

Type / to see available commands:

Settings

Press /settings to customize:

• Hide thinking traces — cleaner output
• Theme — dark/light mode
• Thinking level — control depth of model reasoning

Keyboard Shortcuts

Shift+Tab — cycles through thinking levels. Useful when using reasoning models like o1.

Full Access by Default

Pi runs without permission prompts. Unlike Claude Code’s permission modes (Read/Ask/Auto), Pi gives the model full access. The thinking: users just click “allow” anyway, so why add friction?

Extension API

Extensions have access to:

1. Modify system prompt — systemPromptOptions.append() adds context without replacing defaults

2. Add custom tools — register new tools with descriptions and implementations

3. Intercept tool calls — listen to toolCall, toolResult events before/after execution

4. Customize UI — render custom tool outputs, add TUI components, keyboard shortcuts

5. Permission gates — block dangerous commands or protect paths

6. Replace built-in tools — override Read, Write, Edit, Bash entirely

1
import { Extension, Tool } from "@mariozechner/pi-coding-agent";
2

3
export const myExtension: Extension = {
4
  name: "my-extension",
5

6
  setup({ systemPromptOptions, tools, events, ui, shortcuts }) {
7
    // 1. Modify system prompt
8
    systemPromptOptions.append(`
9
      You are working on a React project.
10
      Prefer functional components with hooks.
11
    `);
12

13
    // 2. Add custom tool
14
    const myTool: Tool = {
15
      name: "my-tool",
16
      description: "Does something useful",
17
      execute: async (args) => {
18
        return "Result";
19
      }
20
    };
21
    tools.register(myTool);
22

23
    // 3. Intercept tool calls
24
    events.onToolCall("bash", async (tool, next) => {
25
      console.log("Running:", tool.args);
26
      return next();
27
    });
28

29
    // 4. Add keyboard shortcut
30
    shortcuts.register("ctrl-r", () => {
31
      ui.reload();
32
    });
33
  }
34
};

Building Extensions

Pi can build its own extensions — it has access to its source code and documentation. Ask Pi to read the extension examples and it can create new ones for you.

1
# Ask Pi to build an extension
2
read ~/.pi/agent/extensions/
3
Create a new extension that adds a custom timer tool

SYSTEM.md — Custom System Prompt

Replaces the default system prompt:

1
You are a Rust expert. Prefer idiomatic Rust code.
2
Use iterators over loops. Handle errors explicitly.

APPEND_SYSTEM.md — Append to Default Prompt

Adds to the default prompt without replacing it:

Useful for team-specific guidelines that persist across updates.

AGENTS.md — Project Context

Pi auto-loads AGENTS.md (and CLAUDE.md) as project context:

1
## Project Context
2
This is a Next.js app with TypeScript.
3

4
## Preferred Patterns
5
- Use server components by default
6
- Prefer App Router over Pages Router
7

8
## Tools Available
9
- pnpm for package management
10
- Vitest for testing

Pi loads these files at startup to understand project conventions.

Settings File

JSON settings for persistent preferences:

1
{
2
  "theme": "dark",
3
  "hideThinking": true,
4
  "thinkingLevel": "low"
5
}

Location priority: .pi/settings.json (project) → ~/.pi/agent/settings.json (global)

models.json — Custom Model Providers

Add custom providers (Ollama, vLLM, LM Studio, proxies):

1
{
2
  "provider": "ollama",
3
  "model": "qwen2.5-coder:7b",
4
  "url": "http://localhost:11434"
5
}

Themes — TUI Customization

JSON files that define terminal colors:

1
{
2
  "name": "my-theme",
3
  "background": "#1e1e2e",
4
  "foreground": "#cdd6f4",
5
  "accent": "#89b4fa"
6
}

Select via /settings or in settings.json.

Prompt Templates

Markdown snippets that expand into full prompts. Type /name in the editor to invoke:

1
---
2
name: refactor
3
description: Refactor code with context
4
---
5

6
Refactor the following code:
7
1. Identify code smells
8
2. Suggest improvements
9
3. Apply changes safely

Stored in ~/.pi/agent/prompts/ and invoked via /refactor.

Skill Locations

Stored in:

• ~/.pi/agent/skills/ — global skills
• .pi/skills/ in your project

Pi scans these directories at startup and includes available skills in the system prompt.

Skill Format

Skills are Markdown files with YAML frontmatter:

1
---
2
name: spec
3
description: Create a specification document
4
---
5

6
# skill: spec
7

8
Create a specification for the task:
9
1. List requirements clearly
10
2. Define acceptance criteria
11
3. Identify edge cases
12
4. Output as Markdown

Using Skills

Invoke with /skill [name]:

1
/skill spec
2
Build a todo app with add, edit, delete, mark complete

Example Skills from the Video

• spec — writing specifications
• review — code review
• build-task — structured building
• coverage — test coverage
• debugging — debugging workflow
• planning — task planning
• refactoring — refactoring guidance

External Skill Repo

Create a repository of skills and reference them in config:

1
{
2
  "skills": [
3
    "~/path/to/pi-skills"
4
  ]
5
}

This keeps skills centralized and version-controlled.