Pi

https://pi.dev/docs
Admin
Pi is a minimal terminal coding harness that enables developers to build extensible AI coding agents...
Tokens:113,707
Snippets:1,005
Trust Score:7.9
Update:5 days ago
Show doc for...
Tokens:
Raw
### Install the Gondolin extension

Source: https://pi.dev/docs/latest/containerization

Commands to create the extension directory, copy the Gondolin example from the Pi source, and install dependencies.

```bash
mkdir -p ~/.pi/agent/extensions
cp -R packages/coding-agent/examples/extensions/gondolin ~/.pi/agent/extensions/gondolin
cd ~/.pi/agent/extensions/gondolin
npm install --ignore-scripts
```

--------------------------------

### Install a package

Source: https://pi.dev/docs/latest/cli

Installs a package from a specified source.

```bash
pi install npm:@scope/package
```

--------------------------------

### Prompt Request and Response Example

Source: https://pi.dev/docs/latest/rpc

Shows a standard prompt request and its corresponding response indicating that the prompt has been accepted and started.

```json
{"id":"req-2","type":"prompt","message":"Review this repository"}
{"id":"req-2","type":"response","command":"prompt","success":true,"data":{"disposition":"started"}}
```

--------------------------------

### Install Node.js and Git

Source: https://pi.dev/docs/latest/termux

Installs the necessary dependencies for running Pi.

```bash
pkg install nodejs git
```

--------------------------------

### Install Pi via bun

Source: https://pi.dev

Install the Pi coding agent globally using bun.

```bash
bun add -g --ignore-scripts @earendil-works/pi-coding-agent
```

--------------------------------

### Install Pi packages from npm or git

Source: https://pi.dev

Use the pi install command to install packages from npm or git repositories. The command syntax is shown for both sources.

```shell
$ pi install npm:@foo/pi-tools  
$ pi install git:github.com/badlogic/pi-doom
```

--------------------------------

### Verify Pi installation

Source: https://pi.dev/docs/latest/quickstart

Check the installed version of Pi.

```bash
pi --version
```

--------------------------------

### Install Pi via PowerShell

Source: https://pi.dev

Use PowerShell to install Pi on Windows systems.

```powershell
powershell -c "irm https://pi.dev/install.ps1 | iex"
```

--------------------------------

### Install Pi via npm

Source: https://pi.dev

Install the Pi coding agent globally using npm.

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

--------------------------------

### Start Pi

Source: https://pi.dev/docs/latest/termux

Navigates to the working directory and launches the Pi agent.

```bash
cd /path/to/working-folder
pi
```

--------------------------------

### Install Pi via Nix

Source: https://pi.dev/docs/latest/quickstart

Install the latest release from Pi's flake using Nix. This builds Pi from source.

```bash
nix profile add github:earendil-works/pi/stable
```

--------------------------------

### Install Pi via pnpm

Source: https://pi.dev

Install the Pi coding agent globally using pnpm.

```bash
pnpm add -g --ignore-scripts @earendil-works/pi-coding-agent
```

--------------------------------

### Install Pi via curl

Source: https://pi.dev

Use curl to install Pi on Unix-like systems.

```bash
curl -fsSL https://pi.dev/install.sh | sh
```

--------------------------------

### Start Pi in a folder

Source: https://pi.dev/docs/latest/quickstart

Navigate to your working directory and launch the Pi interface.

```bash
cd /path/to/folder
pi
```

--------------------------------

### Install Termux:API package

Source: https://pi.dev/docs/latest/termux

Installs the command-line package required for clipboard integration.

```bash
pkg install termux-api
```

--------------------------------

### SessionHeader Examples

Source: https://pi.dev/docs/latest/session-format

Examples of the SessionHeader entry, which serves as the first line of the file. Includes a standard header and one for sessions with a parent.

```json
{"type":"session","version":3,"id":"uuid","timestamp":"2024-12-03T14:00:00.000Z","cwd":"/path/to/project"}
```

```json
{"type":"session","version":3,"id":"uuid","timestamp":"2024-12-03T14:00:00.000Z","cwd":"/path/to/project","parentSession":"/path/to/original/session.jsonl"}
```

--------------------------------

### Install Pi packages from various sources

Source: https://pi.dev/docs/latest/packages

Use the pi install command to add packages from npm, git repositories, or local file system paths.

```bash
pi install npm:@example/pi-tools@1.0.0
pi install git:github.com/example/pi-tools@v1
pi install ./local-package
```

--------------------------------

### Configure Termux environment instructions

Source: https://pi.dev/docs/latest/termux

Example content for the AGENTS.md file to help Pi understand the Termux environment.

```markdown
# Termux environment

- Pi runs in Termux on Android.
- Shared Android storage is under `/storage/emulated/0`.
- Open URLs with `termux-open-url "https://example.com"`.
- Open files with `termux-open <path>`.
- Do not access shared storage unless the task requires it.
```

--------------------------------

### Pi CLI usage syntax

Source: https://pi.dev/docs/latest/cli

Shows the top-level command syntax for Pi, including install, remove, update, list, config, auth, and mcp subcommands. Run 'pi --help' for the exact interface in your installed version.

```text
pi [options] [--] [@files...] [messages...]
pi install <source> [options]
pi remove <source> [options]
pi uninstall <source> [options]
pi update [target] [options]
pi list
pi config [options]
pi auth <check|print-api-key|print-bearer-token> [options]
pi mcp <list|login|logout> [options]
```

--------------------------------

### Task examples for Pi

Source: https://pi.dev/docs/latest/quickstart

Examples of natural language tasks you can provide to Pi.

```text
Summarize @meeting-notes.md and save the action items to action-items.md.
```

```text
Explain how this repository is structured and how to run its checks.
```

```text
Compare @previous.csv with @current.csv and summarize the important changes.
```

--------------------------------

### SKILL.md frontmatter and instructions

Source: https://pi.dev/docs/latest/skills

Start SKILL.md with frontmatter defining the name and description, followed by instructions for the model.

```markdown
---
name: pdf-tools
description: Extract text and tables from PDF files. Use when reading, converting, or inspecting PDFs.
---

# PDF tools

Read `references/formats.md` before converting a document. Run scripts relative to this skill directory.
```

--------------------------------

### Example: Print completed messages

Source: https://pi.dev/docs/latest/json

Example command to print completed messages from a one-shot run using the JSON mode and jq.

```APIDOC
## Example: Print completed messages

### Description
Print completed messages from a one-shot run.

### Command
```bash
pi --mode json "List files" 2>/dev/null | jq -c 'select(.type == "message_end")'
```
```

--------------------------------

### Pi CLI invocation examples

Source: https://pi.dev/docs/latest/cli

Examples of invoking Pi: with no arguments, with '--print' for one-shot text output, piping git diff for review, and using '--mode json' to write JSONL events to a file.

```text
pi
pi --print "Summarize this repository"
git diff | pi --print "Review this change"
pi --mode json "Inspect this repository" > events.jsonl
```

--------------------------------

### Create Dockerfile.pi

Source: https://pi.dev/docs/latest/containerization

Defines the base image, installs necessary dependencies, and sets up the Pi coding agent.

```dockerfile
FROM node:24-bookworm-slim

RUN apt-get update \
  && apt-get install -y --no-install-recommends bash ca-certificates git ripgrep \
  && rm -rf /var/lib/apt/lists/*
RUN npm install -g --ignore-scripts @earendil-works/pi-coding-agent

WORKDIR /workspace
ENTRYPOINT ["pi"]
```

--------------------------------

### Common package management tasks

Source: https://pi.dev/docs/latest/cli

Commands for installing, listing, removing, and configuring packages.

```bash
pi install <source>
pi list
pi remove <source>
pi config
```

--------------------------------

### Start Pi with Gondolin

Source: https://pi.dev/docs/latest/containerization

Command to launch Pi from a specific working folder while enabling the Gondolin extension.

```bash
cd /path/to/working-folder
pi -e ~/.pi/agent/extensions/gondolin
```

--------------------------------

### Update Pi via Nix

Source: https://pi.dev/docs/latest/cli

Example of updating Pi when managed by a package manager like Nix.

```bash
nix profile upgrade pi
```

--------------------------------

### Example recipe command for llama-server

Source: https://pi.dev/docs/latest/nvidia-rtx-llama-cpp

A sample PowerShell command for llama-server.exe using various model and speculative decoding flags.

```powershell
llama-server.exe -hf "unsloth/Qwen3.8-27B-GGUF" `
  -hff "Qwen3.8-27B-UD-Q4_K_M.gguf" `
  -hfrd "z-lab/Qwen3.8-27B-DFlash2-GGUF" `
  --spec-draft-model "Qwen3.8-27B-DFlash2-Q4_K_M.gguf" `
  --no-mmproj `
  --host 127.0.0.1 `
  --port 9931 `
  --batch-size 4096 `
  --ubatch-size 1024 `
  --ctx-size 65536 `
  --parallel 1 `
  -ngl 999 `
  --jinja `
  --chat-template-kwargs '{"preserve_thinking":true}' `
  --spec-type draft-dflash `
  --spec-draft-n-max 7 `
  --spec-draft-backend-sampling
```

--------------------------------

### Run pi with specific tools

Source: https://pi.dev/docs/latest/cli

Example of using the --tools flag to specify an allowlist of tools for a single invocation.

```bash
pi --tools read,grep,find,ls --print "Review this project"
```

--------------------------------

### ModelChangeEntry Example

Source: https://pi.dev/docs/latest/session-format

Example of a model change entry emitted when a user switches models mid-session.

```json
{"type":"model_change","id":"d4e5f6g7","parentId":"c3d4e5f6","timestamp":"2024-12-03T14:05:00.000Z","provider":"openai","modelId":"gpt-4o"}
```

--------------------------------

### SessionMessageEntry Conversation Examples

Source: https://pi.dev/docs/latest/session-format

Examples of user, assistant, and tool result messages within a session.

```json
{"type":"message","id":"a1b2c3d4","parentId":"prev1234","timestamp":"2024-12-03T14:00:01.000Z","message":{"role":"user","content":"Hello","timestamp":1733234401000}}
{"type":"message","id":"b2c3d4e5","parentId":"a1b2c3d4","timestamp":"2024-12-03T14:00:02.000Z","message":{"role":"assistant","content":[{"type":"text","text":"Hi!"}],"api":"anthropic-messages","provider":"anthropic","model":"claude-sonnet-4-5","usage":{...},"stopReason":"stop","timestamp":1733234402000}}
{"type":"message","id":"c3d4e5f6","parentId":"b2c3d4e5","timestamp":"2024-12-03T14:00:03.000Z","message":{"role":"toolResult","toolCallId":"call_123","toolName":"bash","content":[{"type":"text","text":"output"}],"isError":false,"timestamp":1733234403000}}
```

--------------------------------

### ThinkingLevelChangeEntry Example

Source: https://pi.dev/docs/latest/session-format

Example of a thinking level change entry emitted when the user updates the reasoning level.

```json
{"type":"thinking_level_change","id":"e5f6g7h8","parentId":"d4e5f6g7","timestamp":"2024-12-03T14:06:00.000Z","thinkingLevel":"high"}
```

--------------------------------

### SessionMessageEntry System Message Examples

Source: https://pi.dev/docs/latest/session-format

Examples of system messages used to patch prompt sections and tool configurations.

```json
{"type":"message","id":"a0b1c2d3","parentId":null,"timestamp":"2024-12-03T14:00:00.000Z","message":{"role":"system","content":"","sections":{"preamble":"You are an expert coding assistant...","tools":"<tools>\n- read: ...\n</tools>","cwd":"/project"},"toolsAdded":[{"name":"read","description":"...","parameters":{}}],"timestamp":1733234400000}}
{"type":"message","id":"d4e5f6g7","parentId":"c3d4e5f6","timestamp":"2024-12-03T14:04:00.000Z","message":{"role":"system","content":"","sections":{"skills":"<skills>...</skills>"},"toolsRemoved":[{"name":"write"}],"timestamp":1733234640000}}
```

--------------------------------

### Create an OpenShell sandbox

Source: https://pi.dev/docs/latest/containerization

Initialize a new sandbox named pi-sandbox using the pi image.

```bash
openshell sandbox create --name pi-sandbox --from pi -- pi
```

--------------------------------

### get_entries

Source: https://pi.dev/docs/latest/rpc-commands

Get all session entries in append order (excluding the session header). Supports a cursor parameter `since` to get entries strictly after a given entry id.

```APIDOC
## get_entries

### Description
Get all session entries in append order (excluding the session header). The session is an append-only tree of entries with stable ids, so an entry id works as a durable cursor: pass the last entry id you have seen as `since` to get only entries strictly after it, even across client restarts. Unlike `get_messages`, this includes pre-compaction history and abandoned branches.

### Request
```json
{"type": "get_entries"}
```

With a cursor:
```json
{"type": "get_entries", "since": "abc123"}
```

### Response
```json
{
  "type": "response",
  "command": "get_entries",
  "success": true,
  "data": {
    "entries": [
      {"type": "message", "id": "def456", "parentId": "abc123", "timestamp": "...", "message": {"role": "user", "...": "..."}}
    ],
    "leafId": "def456"
  }
}
```

### Notes
- `leafId` is the id of the current leaf entry (`null` for an empty session), so a client can tell in one round trip whether the active branch moved.
- If `since` does not match any entry id, the response is `success: false`.
```

--------------------------------

### Start the router with the preset

Source: https://pi.dev/docs/latest/nvidia-rtx-llama-cpp

Command to launch the llama-server router using the newly created model preset file.

```powershell
.\llama-server.exe --models-preset qwen3.8-27b.ini --host 127.0.0.1 --port 8080
```

--------------------------------

### get_entries request (default and with cursor)

Source: https://pi.dev/docs/latest/rpc-commands

Get all session entries in append order. The cursor variant uses since to get entries strictly after the given entry id.

```json
{"type": "get_entries"}
```

```json
{"type": "get_entries", "since": "abc123"}
```

--------------------------------

### Run pi with MCP tool filtering

Source: https://pi.dev/docs/latest/cli

Example of using the --tools flag to filter MCP tools by matching a specific server pattern.

```bash
pi --tools read,bash,codemode,'mcp__radius__*'
```

--------------------------------

### ctx.sessionManager.getBranch

Source: https://pi.dev/docs/latest/extensions

Gets the current branch of the session.

```APIDOC
## ctx.sessionManager.getBranch

### Description
Gets the current branch of the session.

### Method
getBranch

### Signature
ctx.sessionManager.getBranch()

### Returns
- **branch** (string) - The current branch identifier.
```

--------------------------------

### get_fork_messages

Source: https://pi.dev/docs/latest/rpc-commands

Get user messages available for forking.

```APIDOC
## get_fork_messages

### Description
Get user messages available for forking.

### Request
```json
{"type": "get_fork_messages"}
```

### Response
```json
{
  "type": "response",
  "command": "get_fork_messages",
  "success": true,
  "data": {
    "messages": [
      {"entryId": "abc123", "text": "First prompt..."},
      {"entryId": "def456", "text": "Second prompt..."}
    ]
  }
}
```
```

--------------------------------

### Create a prompt template file

Source: https://pi.dev/docs/latest/prompt-templates

Create a Markdown file in the ~/.pi/agent/prompts/ directory. The filename serves as the command name, and the YAML front matter defines the description and argument hint.

```markdown
---
description: Review staged git changes
argument-hint: "[focus]"
---
Review the staged changes. Focus on ${1:-correctness, security, and error handling}.
```

--------------------------------

### Start the Pi container

Source: https://pi.dev/docs/latest/containerization

Runs the Pi container with the current working directory mounted and the API key passed as an environment variable.

```bash
docker run --rm -it \
  -e ANTHROPIC_API_KEY \
  -v "$PWD:/workspace" \
  -v pi-agent-home:/root/.pi/agent \
  pi-sandbox
```

--------------------------------

### get_fork_messages request

Source: https://pi.dev/docs/latest/rpc-commands

Get user messages available for forking.

```json
{"type": "get_fork_messages"}
```

--------------------------------

### get_messages request

Source: https://pi.dev/docs/latest/rpc-commands

Send this request to get all messages in the conversation.

```json
{"type": "get_messages"}
```

--------------------------------

### get_messages

Source: https://pi.dev/docs/latest/rpc-commands

Gets all messages in the conversation. Returns an array of AgentMessage objects.

```APIDOC
## get_messages

### Description
Get all messages in the conversation.

### Request
{"type": "get_messages"}

### Response
{
  "type": "response",
  "command": "get_messages",
  "success": true,
  "data": {"messages": [...]}
}
```

--------------------------------

### get_state request

Source: https://pi.dev/docs/latest/rpc-commands

Send this request to get the current session state.

```json
{"type": "get_state"}
```

--------------------------------

### Add a local stdio MCP server

Source: https://pi.dev/docs/latest/mcp

Adds a local stdio server, verifies the connection, and starts the Pi session.

```bash
pi mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem .
pi mcp list
pi
```

--------------------------------

### Create ~/.bash_aliases with aliases

Source: https://pi.dev/docs/latest/shell-aliases

Store aliases needed by Pi in a Bash-compatible file. This example creates ~/.bash_aliases with aliases for ll and gs. Aliases must use Bash-compatible syntax; do not source an arbitrary .zshrc into Bash.

```bash
alias ll='ls -la'
alias gs='git status --short'
```
Tokens:
Raw