Interactive Mode

Interactive mode is Pi’s default interface, providing a full terminal UI with an editor, commands, keyboard shortcuts, and visual feedback.

Interface Layout

The interface from top to bottom:

Startup Header

Shows shortcuts (/hotkeys for all), loaded AGENTS.md files, prompt templates, skills, and extensions

Messages

Your messages, assistant responses, tool calls and results, notifications, errors, and extension UI

Editor

Where you type; border color indicates thinking level

Footer

Working directory, session name, total token/cache usage, cost, context usage, current model

The editor can be temporarily replaced by other UI, like built-in /settings or custom UI from extensions. Extensions can also add:

Widgets above/below the editor
Status lines in the footer
Custom overlays
Custom headers

Editor Features

File References

Type @ to fuzzy-search project files:

@src/main.ts
@components/Button

The autocomplete shows matching files as you type. Selected files are included in your message context.

Path Completion

Press Tab to complete file and directory paths:

./src/[Tab] → ./src/components/

Multi-line Input

Shift+Enter - New line (Ctrl+Enter on Windows Terminal)
Enter - Submit message

Images

Paste from clipboard:

Ctrl+V to paste (Alt+V on Windows)
Supports PNG, JPEG, BMP formats
Automatic conversion to supported formats

Drag and drop:

Drag image files onto the terminal window
Works in terminals that support file drag-and-drop

Bash Commands

Run shell commands directly from the editor:

! prefix
!! prefix

!git status

Runs command and sends output to LLM

!!npm install

Runs command without sending output to LLM

Use !! for commands that produce large output or when you just want to run something without context pollution.

Standard Editing

Supports standard keybindings:

Ctrl+W - Delete word
Ctrl+U - Delete to start of line
Ctrl+K - Delete to end of line
Ctrl+A - Move to start of line
Ctrl+E - Move to end of line
Alt+Left/Right - Move by word
Ctrl+Z (in input) - Undo
Ctrl+Y - Redo

See the full list in the source at packages/tui/src/components/editor.ts.

Commands

Type / in the editor to trigger commands. Autocomplete shows available commands with descriptions.

Built-in Commands

Command	Description
`/login`	OAuth authentication with provider
`/logout`	Logout from OAuth provider

Command	Description
`/model`	Switch models (opens selector UI)
`/scoped-models`	Enable/disable models for Ctrl+P cycling

Command	Description
`/settings`	Thinking level, theme, message delivery, transport
`/hotkeys`	Show all keyboard shortcuts
`/changelog`	Display version history

Command	Description
`/resume`	Pick from previous sessions
`/new`	Start a new session
`/name <name>`	Set session display name
`/session`	Show session info (path, tokens, cost)

Command	Description
`/tree`	Jump to any point in session and continue from there
`/fork`	Create a new session from the current branch

Command	Description
`/compact [prompt]`	Manually compact context, optional custom instructions
`/reload`	Reload extensions, skills, prompts, context files

Command	Description
`/copy`	Copy last assistant message to clipboard
`/export [file]`	Export session to HTML file
`/share`	Upload as private GitHub gist with shareable HTML link
`/quit`, `/exit`	Quit pi

Extension Commands

Extensions can register custom commands:

pi.registerCommand("deploy", {
  description: "Deploy to environment",
  handler: async (args, ctx) => {
    // Command implementation
  }
});

Extension commands appear in autocomplete alongside built-in commands.

Skill Commands

Skills register as /skill:name commands:

/skill:brave-search
/skill:pdf-tools extract

Toggle skill commands in /settings or settings.json:

{
  "enableSkillCommands": true
}

Prompt Templates

Prompt templates expand when you type /templatename:

# ~/.pi/agent/prompts/review.md
---
description: Review staged git changes
---
Review the staged changes (`git diff --cached`). Focus on:
- Bugs and logic errors
- Security issues
- Error handling gaps

Usage:

/review

Templates support arguments:

/component Button "click handler"

Keyboard Shortcuts

Press /hotkeys to see all shortcuts. Customize via ~/.pi/agent/keybindings.json.

Essential Shortcuts

Editor Control
Agent Control
Model Control
Display
System

Key	Action
Enter	Submit message
Shift+Enter	New line (Ctrl+Enter on Windows)
Ctrl+C	Clear editor
Ctrl+C (twice)	Quit
Ctrl+G	Open external editor (respects `$VISUAL` or `$EDITOR`)

Key	Action
Escape	Cancel/abort current operation
Escape (twice)	Open `/tree`
Alt+Enter	Queue follow-up message
Alt+Up	Retrieve queued messages

Key	Action
Ctrl+L	Open model selector
Ctrl+P	Cycle scoped models forward
Shift+Ctrl+P	Cycle scoped models backward
Shift+Tab	Cycle thinking level

Key	Action
Ctrl+O	Collapse/expand tool output
Ctrl+T	Collapse/expand thinking blocks

Key	Action
Ctrl+D	Quit
Ctrl+Z	Suspend (returns to shell)

Custom Keybindings

Create ~/.pi/agent/keybindings.json to customize:

{
  "clear": "ctrl+l",
  "cycleModelForward": "ctrl+m",
  "selectModel": "ctrl+shift+m"
}

Available actions:

App actions: interrupt, clear, exit, suspend, cycleThinkingLevel, cycleModelForward, cycleModelBackward, selectModel, expandTools, toggleThinking, externalEditor, followUp, dequeue, pasteImage, newSession, tree, fork, resume
Editor actions: See packages/tui documentation

Message Queue

Submit messages while the agent is working:

Steering Messages (Enter)

Delivered after current tool execution. Interrupts remaining tools.Use when you want to redirect the agent immediately:

> Agent is running 5 tools...
> [Press Enter] "Focus on error handling"
> Current tool finishes, remaining tools skipped

Follow-up Messages (Alt+Enter)

Delivered only after agent finishes all work.Use when you want to add something for later:

> Agent is running 5 tools...
> [Press Alt+Enter] "Then add tests"
> All 5 tools complete
> Follow-up message delivered

Abort (Escape)

Cancels current operation and restores queued messages to editor.

Retrieve (Alt+Up)

Pulls queued messages back into the editor for editing.

Delivery Modes

Configure in /settings or settings.json:

{
  "steeringMode": "one-at-a-time",    // or "all"
  "followUpMode": "one-at-a-time",   // or "all"
  "transport": "sse"                 // or "websocket", "auto"
}

Modes:

"one-at-a-time" (default) - Waits for response after each message
"all" - Delivers all queued messages at once

Transport:

"sse" - Server-Sent Events (default, more reliable)
"websocket" - WebSocket (lower latency when available)
"auto" - Let provider choose

Context Files

Pi automatically loads AGENTS.md (or CLAUDE.md) from:

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

All matching files are concatenated and included in the system prompt. Example AGENTS.md:

# Project Guidelines

- Use TypeScript strict mode
- Test all functions with vitest
- Follow existing code style

# Common Commands

- `npm run check` - Type check and lint
- `npm test` - Run tests

Custom System Prompt

Replace the default system prompt:

Global: ~/.pi/agent/SYSTEM.md
Project: .pi/SYSTEM.md

Append without replacing:

Global: ~/.pi/agent/APPEND_SYSTEM.md
Project: .pi/APPEND_SYSTEM.md

Terminal Setup

For best results: Recommended terminals:

iTerm2 (macOS)
Kitty (Linux/macOS)
WezTerm (cross-platform)
Windows Terminal (Windows)
VS Code integrated terminal

Enable 24-bit color:

# Check truecolor support
echo $COLORTERM  # Should output "truecolor" or "24bit"

# VS Code: Set minimum contrast ratio to 1
"terminal.integrated.minimumContrastRatio": 1

Font recommendations:

Use a font with good Unicode support
Enable ligatures for better code display
Monospace fonts with clear distinction between characters

Shell Aliases

Useful aliases to add to your .bashrc or .zshrc:

# Quick pi invocations
alias p='pi'
alias pc='pi -c'          # Continue
alias pr='pi -r'          # Resume
alias pp='pi -p'          # Print mode

# Common tasks
alias preview='pi -p @README.md "Review and suggest improvements"'
alias review='pi "/review"'

Platform Notes

Windows

See docs/windows.md in the coding-agent package for Windows-specific setup.

Termux (Android)

See docs/termux.md in the coding-agent package for Android/Termux setup.

Next Steps

Sessions

Learn about branching, compaction, and tree navigation

Customization

Configure settings, keybindings, and appearance

Get Started

Core Concepts

Coding Agent

LLM API

Agent Core

UI Libraries

Additional Tools

Guides

Interactive Mode

Interface Layout

Editor Features

File References

Path Completion

Multi-line Input

Images

Bash Commands

Standard Editing

Commands

Built-in Commands

Extension Commands

Skill Commands

Prompt Templates

Keyboard Shortcuts

Essential Shortcuts

Custom Keybindings

Message Queue

Delivery Modes

Context Files

Custom System Prompt

Terminal Setup

Shell Aliases

Platform Notes

Windows

Termux (Android)

Next Steps

Sessions

Customization

Build docs developers (and LLMs) love

Get Started

Core Concepts

Coding Agent

LLM API

Agent Core

UI Libraries

Additional Tools

Guides

Documentation Index

​Interface Layout

​Editor Features

​File References

​Path Completion

​Multi-line Input

​Images

​Bash Commands

​Standard Editing

​Commands

​Built-in Commands

​Extension Commands

​Skill Commands

​Prompt Templates

​Keyboard Shortcuts

​Essential Shortcuts

​Custom Keybindings

​Message Queue

​Delivery Modes

​Context Files

​Custom System Prompt

​Terminal Setup

​Shell Aliases

​Platform Notes

​Windows

​Termux (Android)

​Next Steps

Sessions

Customization

Build docs developers (and LLMs) love

Interface Layout

Editor Features

File References

Path Completion

Multi-line Input

Images

Bash Commands

Standard Editing

Commands

Built-in Commands

Extension Commands

Skill Commands

Prompt Templates

Keyboard Shortcuts

Essential Shortcuts

Custom Keybindings

Message Queue

Delivery Modes

Context Files

Custom System Prompt

Terminal Setup

Shell Aliases

Platform Notes

Windows

Termux (Android)

Next Steps