Settings & Configuration

✓ Fresh · 2026-02-24

Pi uses a layered configuration system. Project-level settings override global settings, and context files are concatenated from multiple locations.

Configuration Files

File	Location	Scope
~/.pi/agent/settings.json	Home directory	Global (all projects)
.pi/settings.json	Project root	Project-specific (overrides global)

Edit settings via:

• /settings command (interactive UI)
• Direct JSON file editing

Context Files (AGENTS.md)

Pi loads context files at startup to provide the agent with project-specific instructions. It recognizes both AGENTS.md and CLAUDE.md filenames.

Loading Order

Pi searches for context files in this order and concatenates all matches:

1. ~/.pi/agent/AGENTS.md (global context)
2. Parent directories walking up from the current working directory
3. Current working directory

Example AGENTS.md

# Project Rules

- Use TypeScript for all new files
- Follow the existing code style
- Run tests before committing
- Never modify files in the vendor/ directory

## Architecture

This project uses a layered architecture:
- src/api/ — HTTP handlers
- src/services/ — Business logic
- src/db/ — Database access

All matching AGENTS.md and CLAUDE.md files are merged together, so you can have:

• Global coding standards in ~/.pi/agent/AGENTS.md
• Monorepo-wide rules in the repo root AGENTS.md
• Package-specific rules in each package's AGENTS.md

System Prompt

Replacing the System Prompt

To completely replace Pi's default system prompt:

File	Scope
.pi/SYSTEM.md	Project-level replacement
~/.pi/agent/SYSTEM.md	Global replacement

Appending to the System Prompt

To add to (not replace) the default system prompt:

File	Scope
.pi/APPEND_SYSTEM.md	Project-level append
~/.pi/agent/APPEND_SYSTEM.md	Global append

TIP

Use APPEND_SYSTEM.md when you want to add rules without losing Pi's built-in behaviors. Use SYSTEM.md only when you need full control over the system prompt.

Key Settings

Thinking Level

Controls how much "thinking" the model does before responding:

{
  "thinkingLevel": "medium"
}

Cycle through levels interactively with Shift+Tab.

Message Delivery

{
  "steeringMode": "one-at-a-time",
  "followUpMode": "one-at-a-time",
  "transport": "auto"
}

See Message Queue for details on these settings.

Theme

{
  "theme": "dark"
}

Built-in options: "dark", "light". Custom themes can be installed. See Themes.

Auto-Compaction

{
  "autoCompact": true
}

When enabled (default), Pi automatically compacts context when approaching the model's limit.

Full Directory Structure

~/.pi/
├── agent/
│   ├── settings.json       # Global settings
│   ├── AGENTS.md            # Global context file
│   ├── SYSTEM.md            # Global system prompt override
│   ├── APPEND_SYSTEM.md     # Global system prompt append
│   ├── keybindings.json     # Custom keybindings
│   ├── extensions/          # Global extensions
│   ├── skills/              # Global skills
│   ├── prompts/             # Global prompt templates
│   ├── themes/              # Global themes
│   ├── npm/                 # Globally installed npm packages
│   └── git/                 # Globally installed git packages
└── sessions/                # Session JSONL files

.pi/                         # Project-level (in project root)
├── settings.json            # Project settings
├── SYSTEM.md                # Project system prompt
├── APPEND_SYSTEM.md         # Project system prompt append
├── extensions/              # Project extensions
├── skills/                  # Project skills
├── prompts/                 # Project prompts
├── themes/                  # Project themes
├── npm/                     # Project-local npm packages
└── git/                     # Project-local git packages