Customization

Pi uses JSON settings files with project settings overriding global settings. Edit directly or use /settings for common options.

Settings Files

Global Settings
Project Settings

Location: ~/.pi/agent/settings.jsonApplies to all projects and sessions.

{
  "defaultProvider": "anthropic",
  "defaultModel": "claude-sonnet-4-20250514",
  "theme": "dark",
  "packages": ["pi-skills"]
}

Location: .pi/settings.jsonApplies to the current project. Overrides global settings.

{
  "defaultModel": "gpt-4o",
  "theme": "light",
  "extensions": ["./extensions/deploy.ts"]
}

Merging Behavior

Project settings override global settings. Nested objects are merged:

// Global: ~/.pi/agent/settings.json
{
  "theme": "dark",
  "compaction": { "enabled": true, "reserveTokens": 16384 }
}

// Project: .pi/settings.json
{
  "compaction": { "reserveTokens": 8192 }
}

// Result
{
  "theme": "dark",
  "compaction": { "enabled": true, "reserveTokens": 8192 }
}

Model & Thinking

string

Default provider (e.g., "anthropic", "openai")

string

Default model ID

string

Default thinking level: "off", "minimal", "low", "medium", "high", "xhigh"

boolean

default:"false"

Hide thinking blocks in output

object

Custom token budgets per thinking level

{
  "thinkingBudgets": {
    "minimal": 1024,
    "low": 4096,
    "medium": 10240,
    "high": 32768
  }
}

UI & Display

string

default:"dark"

Theme name ("dark", "light", or custom theme)

boolean

default:"false"

Hide startup header

boolean

default:"false"

Show condensed changelog after updates

string

default:"tree"

Action for double-escape: "tree", "fork", or "none"

number

default:"0"

Horizontal padding for input editor (0-3)

number

default:"5"

Max visible items in autocomplete dropdown (3-20)

boolean

default:"false"

Show terminal hardware cursor

Compaction

boolean

default:"true"

Enable automatic compaction

number

default:"16384"

Tokens reserved for LLM response

number

default:"20000"

Recent tokens to keep (not summarized)

Example:

{
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  }
}

Branch Summary

number

default:"16384"

Tokens reserved for branch summarization when switching branches via /tree

Retry

boolean

default:"true"

Enable automatic retry on transient errors

number

default:"3"

Maximum retry attempts

number

default:"2000"

Base delay for exponential backoff (2s, 4s, 8s)

number

default:"60000"

Max server-requested delay before failing (60s)When a provider requests a retry delay longer than this (e.g., “quota resets in 5 hours”), the request fails immediately with an informative error. Set to 0 to disable the cap.

Example:

{
  "retry": {
    "enabled": true,
    "maxRetries": 3,
    "baseDelayMs": 2000,
    "maxDelayMs": 60000
  }
}

Message Delivery

string

default:"one-at-a-time"

How steering messages are sent: "all" or "one-at-a-time"

string

default:"one-at-a-time"

How follow-up messages are sent: "all" or "one-at-a-time"

string

default:"sse"

Preferred transport: "sse", "websocket", or "auto"For providers that support multiple transports.

Terminal & Images

boolean

default:"true"

Show images in terminal (if supported)

boolean

default:"false"

Clear empty rows when content shrinks (can cause flicker)

boolean

default:"true"

Resize images to 2000x2000 max before sending

boolean

default:"false"

Block all images from being sent to LLM

Shell

string

Custom shell path (e.g., for Cygwin on Windows)

string

Prefix for every bash command (e.g., "shopt -s expand_aliases")Useful for loading shell configuration:

{
  "shellCommandPrefix": "source ~/.bashrc"
}

Model Cycling

string[]

Model patterns for Ctrl+P cycling (same format as --models CLI flag)

{
  "enabledModels": ["claude-*", "gpt-4o", "gemini-2*"]
}

Use wildcards to match multiple models. Ctrl+P cycles through matched models.

Markdown

string

default:" "

Indentation for code blocks (default: two spaces)

Resources

These settings define where to load extensions, skills, prompts, and themes.

Path Resolution

Paths in ~/.pi/agent/settings.json resolve relative to ~/.pi/agent
Paths in .pi/settings.json resolve relative to .pi
Absolute paths and ~ are supported

Packages

array

default:"[]"

npm/git packages to load resources fromString form (loads all resources):

{
  "packages": ["pi-skills", "@org/my-extension"]
}

Object form (filters resources):

{
  "packages": [
    {
      "source": "pi-skills",
      "skills": ["brave-search", "transcribe"],
      "extensions": []
    }
  ]
}

Extensions

string[]

default:"[]"

Local extension file paths or directories

{
  "extensions": [
    "./extensions",
    "../shared/extensions/deploy.ts",
    "~/common-extensions"
  ]
}

Skills

string[]

default:"[]"

Local skill file paths or directories

{
  "skills": [
    "./skills",
    "~/.claude/skills"
  ]
}

boolean

default:"true"

Prompts

string[]

default:"[]"

Local prompt template paths or directories

{
  "prompts": ["./prompts", "../shared/prompts"]
}

Themes

string[]

default:"[]"

Local theme file paths or directories

{
  "themes": ["./themes", "~/my-themes"]
}

Glob Patterns

Arrays support glob patterns and exclusions:

{
  "extensions": [
    "extensions/*.ts",
    "!extensions/disabled.ts",
    "+extensions/legacy.ts",
    "-extensions/broken.ts"
  ]
}

pattern - Glob match
!pattern - Exclude matches
+path - Force-include exact path
-path - Force-exclude exact path

Complete Example

{
  "$schema": "https://raw.githubusercontent.com/badlogic/pi-mono/main/packages/coding-agent/src/core/settings-schema.json",
  
  "defaultProvider": "anthropic",
  "defaultModel": "claude-sonnet-4-20250514",
  "defaultThinkingLevel": "medium",
  
  "theme": "dark",
  "quietStartup": false,
  "editorPaddingX": 1,
  
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  },
  
  "retry": {
    "enabled": true,
    "maxRetries": 3,
    "baseDelayMs": 2000,
    "maxDelayMs": 60000
  },
  
  "steeringMode": "one-at-a-time",
  "followUpMode": "one-at-a-time",
  "transport": "sse",
  
  "enabledModels": ["claude-*", "gpt-4o"],
  
  "packages": ["pi-skills"],
  "extensions": ["./extensions"],
  "skills": ["./skills"],
  "prompts": ["./prompts"],
  "themes": ["./themes"]
}

The $schema field enables editor auto-completion and validation.

Interactive Settings

Use /settings to modify common options in interactive mode:

/settings

This opens a TUI settings menu where you can:

Change thinking level
Switch themes
Configure message delivery
Set transport preference
Toggle compaction
And more…

Changes are saved to the appropriate settings file based on scope.

Keybindings

Customize keyboard shortcuts via ~/.pi/agent/keybindings.json:

{
  "clear": "ctrl+l",
  "cycleModelForward": "ctrl+m",
  "cycleModelBackward": "ctrl+shift+m",
  "selectModel": "ctrl+p",
  "expandTools": "ctrl+e",
  "toggleThinking": "ctrl+t"
}

Available actions: App actions:

interrupt, clear, exit, suspend
cycleThinkingLevel
cycleModelForward, cycleModelBackward, selectModel
expandTools, toggleThinking
externalEditor
followUp, dequeue
pasteImage
newSession, tree, fork, resume

Editor actions:

Standard text editing actions (see packages/tui documentation)

See all available actions in packages/coding-agent/src/core/keybindings.ts.

Environment Variables

Variable	Description
`PI_CODING_AGENT_DIR`	Override config directory (default: `~/.pi/agent`)
`PI_PACKAGE_DIR`	Override package directory
`PI_SKIP_VERSION_CHECK`	Skip version check at startup
`PI_CACHE_RETENTION`	Set to `long` for extended prompt cache (Anthropic: 1h, OpenAI: 24h)
`VISUAL`, `EDITOR`	External editor for Ctrl+G

Example:

export PI_CODING_AGENT_DIR=~/my-pi-config
export PI_CACHE_RETENTION=long
export EDITOR=vim

Next Steps

Extensions

Build TypeScript extensions

Skills

Create Agent Skills

Prompt Templates

Make reusable prompts

Themes

Customize colors

Pi Packages

Share via npm/git

CLI Reference

All CLI flags

Get Started

Core Concepts

Coding Agent

LLM API

Agent Core

UI Libraries

Additional Tools

Guides

Customization

Settings Files

Merging Behavior

Model & Thinking

UI & Display

Compaction

Branch Summary

Retry

Message Delivery

Terminal & Images

Shell

Model Cycling

Markdown

Resources

Path Resolution

Packages

Extensions

Skills

Prompts

Themes

Glob Patterns

Complete Example

Interactive Settings

Keybindings

Environment Variables

Next Steps

Extensions

Skills

Prompt Templates

Themes

Pi Packages

CLI Reference

​Settings Files

​Merging Behavior

​Model & Thinking

​UI & Display

​Compaction

​Branch Summary

​Retry

​Message Delivery

​Terminal & Images

​Shell

​Model Cycling

​Markdown

​Resources

​Path Resolution

​Packages

​Extensions

​Skills

​Prompts

​Themes

​Glob Patterns

​Complete Example

​Interactive Settings

​Keybindings

​Environment Variables

​Next Steps

Extensions

Skills

Prompt Templates

Themes

Pi Packages

CLI Reference

Settings Files

Merging Behavior

Model & Thinking

UI & Display

Compaction

Branch Summary

Retry

Message Delivery

Terminal & Images

Shell

Model Cycling

Markdown

Resources

Path Resolution

Packages

Extensions

Skills

Prompts

Themes

Glob Patterns

Complete Example

Interactive Settings

Keybindings

Environment Variables

Next Steps