help

name	help
description	Show this user guide for Pi coding agent. Use when: user asks how to use pi, pi configuration, available skills, extensions, commands, or needs help getting started.

Pi User Guide

Getting Started

Install:

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

Authenticate:

export ANTHROPIC_API_KEY=sk-ant-...
pi

Key Commands (type / in editor)

Command	Description
/login	OAuth authentication
/model	Switch models
/settings	Configure settings
/session	Show session info
/tree	Navigate session history
/fork	Create session from history point
/compact	Compact (summarize) session history
/export	Export session to HTML
/reload	Reload extensions, skills, prompts
/quit	Exit

Keyboard Shortcuts

• Ctrl+C — Clear editor (x2 to quit)
• Escape — Cancel/abort
• Ctrl+L — Model selector
• Ctrl+P — Cycle models
• Shift+Tab — Cycle thinking level
• Ctrl+O — Collapse tool output
• Ctrl+T — Collapse thinking blocks
• Enter — Queue steering message
• Alt+Enter — Queue follow-up message

Configuration

Settings

• Global: ~/.pi/agent/settings.json
• Project: .pi/settings.json

Context Files

Load AGENTS.md (or CLAUDE.md) from:

• ~/.pi/agent/AGENTS.md (global)
• Current directory or parents

System Prompt

Replace with ~/.pi/agent/SYSTEM.md or append via APPEND_SYSTEM.md.

Skills

Skills are on-demand capabilities loaded automatically or via /skill:name.

Installed skills:

• caveman — Ultra-compressed communication
• br — Beads issue tracker
• bv — Beads viewer TUI
• jj — Jujutsu (git alternative)
• exa-cli — Semantic web search
• firecrawl-cli — Web scraping
• context7-cli — Library docs
• sequentialthinking-cli — Complex reasoning
• foreman — Multi-agent orchestration
• obsidian — Session logging to vault
• create-prd — Product Requirements Docs
• create-trd — Technical Requirements Docs
• implement-trd — TRD implementation with TDD
• semantic-web-research — Broad web research
• crush-mail — Email action items to tasks
• detect-hung-sessions — Agent recovery

Extensions

Local extensions in ~/.pi/agent/extensions/:

• ask-user — Interactive user questions
• auto-commit-on-exit — Auto-commits on exit
• bookmark — Session bookmarks
• confirm-destructive — Confirm destructive actions
• dirty-repo-guard — Guard on uncommitted repos
• git-checkpoint — Git stash per turn
• handoff — Context transfer to new session
• model-status — Model status bar
• notify — Terminal notifications
• preset — Named model/tool presets
• progressive-context — Smart context disclosure
• subagent — Spawn pi subagents
• todo — TODO management
• tokens-per-second — Speed stats
• nvim — Neovim integration

NPM Packages

Installed via pi install npm:...:

• pi-powerline-footer — Powerline status bar
• pi-goal-x — Durable goal lifecycle
• pi-yaml-hooks — YAML session/tool hooks
• pi-context — Context management
• pi-plan-mode — Plan mode
• pi-interactive-shell — Interactive shell overlay
• pi-custom-compaction — Custom compaction rules
• pi-tools — Additional tools
• pi-poly-notify — Polyfill notifications

Providers

Built-in: Anthropic, OpenAI, Google, Azure, Groq, xAI, OpenRouter, Vercel, Mistral, and many more.

Custom models via ~/.pi/agent/models.json.

Philosophy

• No MCP — Build CLI tools or extensions
• No sub-agents — Use extensions or spawn instances
• No permission popups — Use containers or extensions
• No plan mode — Use extensions or files
• No built-in TODOs — Use files or extensions

Everything is extensible.