Pi Coding Agent: A Minimal and Customizable AI Terminal Harness

Discover the Pi Coding Agent, a minimal and highly customizable AI terminal harness. Learn how to install, configure, and extend Pi with custom models, prompts, themes, and extensions for tailored AI-assisted coding workflows.

5 min readAI Guide

Introduction

Introduction
Pi is a minimal and highly customizable AI agent harness that operates directly within your terminal. It streamlines development workflows by allowing direct interaction with AI models for coding tasks, offering a flexible alternative to more opinionated tools like Claude Code or Open Code.

Configuration Checklist

Element	Version / Link
Language / Runtime	Node.js (for NPM installation)
Main library	Pi Coding Agent (`@earendil-works/pi-coding-agent`)
Required APIs	OpenAI, Anthropic, GitHub Copilot (or local LLMs via LM Studio)
Keys / credentials needed	API keys or subscription for chosen LLM provider (e.g., GitHub Copilot subscription)

Step-by-Step Guide

Step 1 — Install Pi

Install the Pi Coding Agent globally using NPM. This command downloads the necessary agent to your system.

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

Step 2 — Start Pi

Once installed, you can launch Pi from any terminal by simply typing pi.

pi

Step 3 — Configure Your AI Model

Pi requires an AI model to function. You can log in using an API key or a subscription service. The example below uses GitHub Copilot.

Initiate login: Type /login in the Pi terminal.
```
/login
```
Select authentication method: Choose 'Use a subscription' if prompted.
Select provider: Choose 'GitHub Copilot' (or your preferred provider).

Follow browser prompts: Pi will provide a URL and a device code. Open the URL in your browser, enter the code, and authorize the device.

# Example output after selecting GitHub Copilot
Login to Github Copilot
https://github.com/login/device
Ctrl+click to open
Enter code: AA58-D7CC
Waiting for authentication...

Select your model: After successful login, use the /model command to choose an available model. You can also cycle through configured models using Ctrl+P (next) and Shift+Ctrl+P (previous).
```
/model
```
(A UI will appear to select your model. Use arrow keys and Enter.)
Test your model: Send a simple prompt to verify the model is working.
```
Say hi
```

Step 4 — Manage Sessions and Conversation History

Step 4 — Manage Sessions and Conversation History
Pi offers robust session management features, allowing you to organize and revisit your interactions.

Start a new session: Use /new to clear the current conversation context and begin fresh.
```
/new
```
Reference files in prompts: Use the @ symbol followed by a filename to include its content in your prompt. Pi provides autocompletion for files in your current directory.
```
@index.html Tell me what is in this file
```
Run shell commands: Execute shell commands directly from Pi.
- !command: Runs a shell command and sends its output back to the model.
```
!ls
```
- !!command: Runs a shell command without sending the output to the model (useful for commands with sensitive output or side effects).
```
!!ls
```
Change thinking level: Adjust the model's verbosity and depth of thought using Shift+Tab.
- Shift+Tab: Cycles through thinking levels (e.g., Low, Medium, High, Off, Minimal).
Scope models for cycling: Use /scoped-models to select which models Ctrl+P and Shift+Ctrl+P will cycle through, reducing clutter.
```
/scoped-models
```
(A UI will appear to toggle models. Use Ctrl+S to save.)
View session details: Get information about your current session, including file path, messages, tokens, and cost, using /session.
```
/session
```
Resume previous sessions: Browse and load past sessions with /resume.
```
/resume
```
(A UI will appear to select a session.)
Navigate session history (tree view): Use /tree to visualize your conversation as a branching tree. You can jump to any point in the history.
```
/tree
```
(Use arrow keys to navigate, Enter to select a point.)
Duplicate current session: Create an exact copy of your current session's state with /clone.
```
/clone
```
Fork a new session from history: Use /fork to create a new session starting from any previous user message in your history.
```
/fork
```
(A UI will appear to select a message to fork from.)
Compact session context: Manually summarize older context to free up tokens with /compact.
```
/compact
```
Queue follow-up messages: Type your next message and press Alt+Enter to queue it. It will be delivered after the current tool call finishes executing.
Abort current operation: Press Esc to cancel the current AI operation or prompt input.

Step 5 — Utilize Skills

Skills are pre-defined functionalities that Pi can execute. They can be installed locally or globally and are automatically detected by Pi.

Use an installed skill: Type /skill:name followed by the skill's name.
```
/skill:grill-with-docs
```

Step 6 — Customize Pi with Prompts, Themes, and Extensions

Step 6 — Customize Pi with Prompts, Themes, and Extensions
Pi's strength lies in its customizability. You can define your own prompts, themes, and extensions.

Create a custom prompt file: Create a Markdown file (e.g., test.md) inside a .pi/prompts directory in your project. Include front matter with a description.
```
# .pi/prompts/test.md
---
```

description: This is a test

Say hi
```

Reload Pi: After creating or modifying custom files, reload Pi to apply changes.
```
/reload
```
Run your custom prompt: Execute your prompt file using /test.
```
/test
```
Ask Pi to create a prompt file: You can even instruct Pi to generate prompt files for you.
```
Create a prompt file in this directory for git diffing staged changes
```
(Pi will write a file like .git-prompt-staged.md with relevant content.)
Customize themes: Change the visual appearance of Pi.
- Change built-in theme: Go to /settings, scroll down to 'Theme', and select 'dark' or 'light'.
- Ask Pi to create a custom theme: Instruct Pi to generate a theme file.
```
Create a blue theme in this project for the pi terminal agent harness
```
  (Pi will create a blue.json file in .pi/themes.)
- Apply custom theme: Reload Pi (/reload), then go to /settings, 'Theme', and select your new theme (e.g., 'blue').
Create custom extensions: Extensions are TypeScript files that hook into Pi's API to add new functionality. Pi can even help you create them.
- Ask Pi to create an extension: For example, to add safety features:
```
Create a Pi extension in this project that will prevent dangerous commands from being run unless I explicitly allow them to run. Things such as rm are a good example
```
  (Pi will create extensions/permission-gate.ts with TypeScript code.)
- Test the extension: Reload Pi (/reload), then try a dangerous command (e.g., Delete @index.html). The extension should intercept and prompt for confirmation.
```
Delete @index.html
```
  (The extension will detect the dangerous command and ask for your action.)

Step 7 — Install Packages from the Catalog

Pi has a package catalog where other users upload extensions, skills, prompt templates, and themes. You can install these directly.

Browse the catalog: Visit the 'Packages' section on the Pi website (pi.dev).
Install a package: Copy the pi install npm:<package-name> command provided for the desired package.
```
pi install npm:@juicesharp/rpiv-todo
```

Comparison Tables

Pi vs. Other Agent Harnesses (Claude Code, Open Code)

Feature	Pi	Claude Code / Open Code
Minimality	Minimal core functionality (read/edit files, bash commands)	Comes with many built-in tools (Git integrations, sub-agents, plan mode, to-do lists)
Customizability	Highly customizable via TypeScript extensions, prompt files, and themes. Users build their own toolset.	Less emphasis on deep customization; more out-of-the-box features.
Safety	No inherent safety guards; users can implement their own (e.g., permission gate extension).	Often includes built-in safety mechanisms.

⚠️ Common Mistakes & Pitfalls

Not configuring an AI model: Pi will not respond to prompts until a model is configured via /login and /model.
Forgetting to reload after changes: Custom prompts, themes, or extensions won't be active until Pi is reloaded with /reload.
Unintended command execution: Using ! before a shell command sends its output to the AI, potentially exposing sensitive information or consuming tokens unnecessarily. Use !! for commands whose output should not be sent to the model.
Executing dangerous commands: Pi has no built-in safety nets. Commands like rm -rf / will be executed if typed. Users must implement extensions like the 'permission-gate' to prevent accidental system damage.

Glossary

Agent Harness: A framework or environment that allows an AI agent to interact with a system, providing tools and context for its operations.
Skill: A pre-defined, reusable piece of functionality or a specific task that an AI agent can perform, often implemented as a TypeScript file in Pi.
Prompt File: A Markdown file containing a pre-canned prompt and optional front matter, which can be loaded and executed directly in Pi.
Extension: A TypeScript file that extends Pi's core functionality by hooking into its API, allowing users to add custom behaviors, tools, or integrations.
Session: The entire conversation history and context between the user and the AI model within Pi, which can be saved, resumed, forked, or cloned.

Key Takeaways

Pi is a minimal terminal-based AI agent harness, prioritizing customizability over built-in features.
Installation is straightforward via NPM, and basic interaction involves typing prompts and using slash commands.
Users must configure their own AI models (e.g., GitHub Copilot, OpenAI) using the /login and /model commands.
Pi provides powerful session management, including starting new sessions, resuming old ones, and navigating conversation history via a tree view.
Shell commands can be executed with (!) or without (!!) sending output to the AI model.
Customization is a core aspect, allowing users to create their own prompt files, themes, and TypeScript-based extensions.
The /reload command is crucial for applying any changes made to custom configurations.
Pi offers no inherent safety guards, meaning dangerous commands will be executed unless a custom 'permission gate' extension is implemented.
A package catalog is available for installing community-contributed extensions, skills, and themes.

Resources

Pi Coding Agent Website: https://pi.dev/
Pi Coding Agent Shortcuts Cheat Sheet: https://courses.webdevsimplified.com/pi-coding-agent-shortcuts
Pi Documentation: https://pi.dev/docs
Pi Package Catalog: https://pi.dev/packages
LM Studio: https://lmstudio.ai/ (for local AI setup, mentioned in video)

All guides Lire en français →