Pi coding agent

Minimal, customizable, open source terminal coding harness.

Alternative to Claude Code, Gemini CLI and OpenCode.

TL;DR
Using skills
Further readings
1. Sources

TL;DR

Meant to adapt to one's workflow.
Extensible with TypeScript extensions, skills, prompt templates, and themes.

Usable in interactive, print/JSON, RPC, and SDK mode.

Leverages any inference engine and model as a service.
Authenticates via API keys or OAuth if needed.

Executes in YOLO mode by default.

Add custom providers and models via models.json or extensions.

Stores sessions as trees.
All branches live in a single file. Filter by message type, label entries as bookmarks.

Comes with a minimal 200 tokens system prompt.
Allows control of what goes into the context window and how it's managed.

Setup

Use AGENTS.md for project instructions, conventions, common commands. All matching files are concatenated.
Loads it (fallbacks to CLAUDE.md) at startup from:

~/.pi/agent/AGENTS.md (global)
Parent directories (walking up from cwd)
Current directory

Replace the default system prompt with .pi/SYSTEM.md (in project) or ~/.pi/agent/SYSTEM.md (global).
Append without replacing via APPEND_SYSTEM.md at the same locations.

Packages install to ~/.pi/agent/git/ (for git-based ones) or global npm.
Use -l for project-local installations (.pi/git/, .pi/npm/ in project).

# Install.
npm install -g '@mariozechner/pi-coding-agent'

Usage

Command	Hot key	Action
`/model`	`Ctrl+L`	Switch models mid-session
`/tree`		Navigate to previous sessions' points
`/export`		Export sessions to HTML
`/share`		Upload a session to a GitHub gist and get a shareable URL that renders it
	`Ctrl+P`	Cycle through favorites
	`Enter`	Send a steering message (delivered after the current tool, interrupts remaining tools)
	`Alt+Enter`	Send a follow-up (waits until the agent finishes)
`/skill:name`		Invoke a skill

# Run interactively.
pi
pi "Some initial prompt"
pi --provider openai --model gpt-4o "Help me refactor"

# Run in read-only mode
pi --tools 'read,grep,find,ls' -p "Review the code"

# High thinking level
pi --thinking 'high' "Solve this complex problem"

# Run headless.
pi -p "query"

# Output all events as JSON lines to allow for event streams.
pi --mode 'json'

# List packages.
pi list

# Install packages.
pi install npm:@foo/pi-tools
pi install npm:@foo/pi-tools@1.2.3            # pinned version
pi install git:github.com/user/repo
pi install git:github.com/user/repo@v1        # tag or commit
pi install git:git@github.com:user/repo
pi install git:git@github.com:user/repo@v1    # tag or commit
pi install https://github.com/user/repo
pi install https://github.com/user/repo@v1    # tag or commit
pi install ssh://git@github.com/user/repo
pi install ssh://git@github.com/user/repo@v1  # tag or commit

# Update packages.
# Skips pinned ones.
pi update

# Enable or disable packages.
pi config

# Test packages without installing them.
pi -e 'git:github.com/user/repo'

# Remove packages.
pi remove 'npm:@foo/pi-tools'

Using skills

Skills shall follow the Agent Skills standard.

Place skills in ~/.pi/agent/skills/, ~/.agents/skills/, .pi/skills/, or .agents/skills/ (from cwd up through parent directories), or in a pi package to share with others.

Invoke them via /skill:name, or let the agent load them automatically.

5.1 KiB Raw Blame History

Pi coding agent

TL;DR

Using skills

Further readings

Sources

5.1 KiB

Raw Blame History