5  Using Pi

5.1 Interactive Mode

The Pi interactive interface has four main areas:

1. Startup header — Shortcuts, loaded context files, prompt templates, skills, and extensions
2. Messages — User messages, assistant responses, tool calls, tool results, notifications, errors, and extension UI
3. Editor — Where you type; border color indicates the current thinking level
4. Footer — Working directory, session name, token/cache usage, cost, context usage, and current model

The editor can be replaced temporarily by built-in UI such as /settings or by custom extension UI components.

5.2 Editor Features

Feature	How
File reference	Type @ to fuzzy-search project files
Path completion	Press Tab to complete paths
Multi-line input	Shift+Enter, or Ctrl+Enter on Windows Terminal
Copy response	Ctrl+X copies the last assistant message; in /tree, it copies the selected message
Images	Paste with Ctrl+V (Alt+V on Windows), or drag into the terminal
Shell command	!command runs and sends output to the model
Hidden shell command	!!command runs without sending output to the model
External editor	Ctrl+G opens externalEditor, $VISUAL, $EDITOR, Notepad on Windows, or nano elsewhere

Tip

See the Keybindings chapter for all shortcuts and customization options.

5.3 Slash Commands

Type / in the editor to open command completion. Extensions can register custom commands, skills are available as /skill:name, and prompt templates expand via /templatename.

Command	Description
/login, /logout	Manage OAuth or API-key credentials
/llama	Download, load, and unload llama.cpp router models
/model	Switch models
/scoped-models	Enable/disable models for Ctrl+P cycling
/settings	Thinking level, theme, message delivery, transport
/resume	Pick from previous sessions
/new	Start a new session
/name <name>	Set session display name
/session	Show session file, ID, messages, tokens, and cost
/tree	Jump to any point in the session and continue from there
/trust	Save project trust decision for future sessions
/fork	Create a new session from a previous user message
/clone	Duplicate the current active branch into a new session
/compact [prompt]	Manually compact context, optionally with custom instructions
/copy	Copy last assistant message to clipboard
/export [file]	Export session to HTML or JSONL
/import <file>	Import and resume a session from a JSONL file
/share	Upload as private GitHub gist with shareable HTML link
/reload	Reload keybindings, extensions, skills, prompts, themes, and context files
/hotkeys	Show all keyboard shortcuts
/changelog	Display version history
/quit	Quit Pi

5.4 Message Queue

You can submit messages while the agent is still working:

• Enter queues a steering message, delivered after the current assistant turn finishes executing its tool calls
• Alt+Enter queues a follow-up message, delivered after the agent finishes all work
• Escape aborts and restores queued messages to the editor
• Alt+Up retrieves queued messages back to the editor

Note

On Windows Terminal, Alt+Enter is fullscreen by default. Remap it as described in Terminal setup if you want Pi to receive the shortcut.

Configure delivery in Settings with steeringMode and followUpMode.

5.5 Session Management

Sessions are saved automatically to ~/.pi/agent/sessions/, organized by working directory.

pi -c                  # Continue most recent session
pi -r                  # Browse and select a session
pi --no-session        # Ephemeral mode; do not save
pi --name "my task"    # Set session display name at startup
pi --session <path|id> # Use a specific session file or session ID
pi --fork <path|id>    # Fork a session into a new session file

Useful session commands inside Pi:

• /session shows the current session file and ID
• /tree navigates the in-file session tree and can summarize abandoned branches
• /fork creates a new session from an earlier user message
• /clone duplicates the current active branch into a new session file
• /compact summarizes older messages to free context

5.6 Context Files

Pi loads AGENTS.md or CLAUDE.md at startup from:

• ~/.pi/agent/AGENTS.md for global instructions
• Parent directories, walking up from the current working directory
• The current directory

Use context files for project conventions, commands, safety rules, and preferences. Disable loading with --no-context-files or -nc.

5.6.1 System Prompt Files

Replace the default system prompt with:

• .pi/SYSTEM.md for a project
• ~/.pi/agent/SYSTEM.md globally

Append to the default prompt without replacing it with APPEND_SYSTEM.md in either location.

5.7 Project Trust

On interactive startup, Pi asks before trusting a project folder that contains project-local settings, resources, or project .agents/skills and has no saved decision for the folder or a parent folder in ~/.pi/agent/trust.json.

Trusting a project allows Pi to load:

• .pi/settings.json
• Pi resources (extensions, skills, prompt templates, themes, system prompt files)
• Missing project packages configured through project settings
• Project-local extensions and project package-managed extensions

Warning

Declining trust skips protected resources. AGENTS.md and CLAUDE.md context files are loaded regardless of project trust unless context loading is disabled.

Non-interactive modes (-p, --mode json, --mode rpc) do not show a trust prompt. Without a saved trust decision, they use defaultProjectTrust from global settings. Pass --approve/-a or --no-approve/-na to override.

5.8 Exporting and Sharing Sessions

• /export [file] writes a session to HTML
• /share uploads a private GitHub gist with a shareable HTML link
• For publishing sessions to Hugging Face datasets, see badlogic/pi-share-hf

5.9 CLI Reference

pi [options] [@files...] [messages...]

5.9.1 Package Commands

pi install <source> [-l]     # Install package, -l for project-local
pi remove <source> [-l]      # Remove package
pi update [source|self|pi]   # Update pi only, or one package source
pi update --all              # Update pi and packages
pi update --extensions       # Update packages only
pi update --models           # Refresh model catalogs only
pi list                      # List installed packages
pi config                    # Enable/disable package resources

5.9.2 Modes

Flag	Description
default	Interactive mode
-p, --print	Print response and exit
--mode json	Output all events as JSON lines
--mode rpc	RPC mode over stdin/stdout
--export <in> [out]	Export a session to HTML

5.9.3 Model Options

Option	Description
--provider <name>	Provider (anthropic, openai, google, etc.)
--model <pattern>	Model pattern or ID; supports provider/id and :thinking
--api-key <key>	API key, overriding environment variables
--thinking <level>	off, minimal, low, medium, high, xhigh, max
--models <patterns>	Comma-separated patterns for Ctrl+P cycling
--list-models [search]	List available models

5.9.4 Session Options

Option	Description
-c, --continue	Continue the most recent session
-r, --resume	Browse and select a session
--session <path|id>	Use a specific session file or partial UUID
--fork <path|id>	Fork into a new session
--session-dir <dir>	Custom session storage directory
--no-session	Ephemeral mode; do not save
--name <name>, -n <name>	Set session display name

5.9.5 Tool Options

Option	Description
--tools <list>, -t <list>	Allowlist specific tools
--exclude-tools <list>, -xt <list>	Disable specific tools
--no-builtin-tools, -nbt	Disable built-in tools
--no-tools, -nt	Disable all tools

Built-in tools: read, bash, edit, write, grep, find, ls.

5.9.6 Resource Options

Option	Description
-e, --extension <source>	Load an extension
--no-extensions	Disable extension discovery
--skill <path>	Load a skill
--no-skills	Disable skill discovery
--prompt-template <path>	Load a prompt template
--no-context-files, -nc	Disable context file discovery

5.9.7 Other Options

Option	Description
--system-prompt <text>	Replace default prompt
--append-system-prompt <text>	Append to system prompt
--alt	Use alternate-screen TUI
--verbose	Force verbose startup
-a, --approve	Trust project-local files
-na, --no-approve	Ignore project-local files
-h, --help	Show help
-v, --version	Show version

5.10 Design Principles

Pi keeps the core small and pushes workflow-specific behavior into extensions, skills, prompt templates, and packages. It intentionally does not include built-in MCP, sub-agents, permission popups, plan mode, to-dos, or background bash. You can build or install those workflows as extensions or packages, or use external tools such as containers and tmux.