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

defaultProvider

string

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

defaultModel

string

Default model ID

defaultThinkingLevel

string

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

hideThinkingBlock

boolean

default:"false"

Hide thinking blocks in output

thinkingBudgets

object

Custom token budgets per thinking level

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

UI & Display

theme

string

default:"dark"

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

quietStartup

boolean

default:"false"

Hide startup header

collapseChangelog

boolean

default:"false"

Show condensed changelog after updates

doubleEscapeAction

string

default:"tree"

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

editorPaddingX

number

default:"0"

Horizontal padding for input editor (0-3)

autocompleteMaxVisible

number

default:"5"

Max visible items in autocomplete dropdown (3-20)

showHardwareCursor

boolean

default:"false"

Show terminal hardware cursor

Compaction

compaction.enabled

boolean

default:"true"

Enable automatic compaction

compaction.reserveTokens

number

default:"16384"

Tokens reserved for LLM response

compaction.keepRecentTokens

number

default:"20000"

Recent tokens to keep (not summarized)

Example:

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

Branch Summary

branchSummary.reserveTokens

number

default:"16384"

Tokens reserved for branch summarization when switching branches via /tree

Retry

retry.enabled

boolean

default:"true"

Enable automatic retry on transient errors

retry.maxRetries

number

default:"3"

Maximum retry attempts

retry.baseDelayMs

number

default:"2000"

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

retry.maxDelayMs

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

steeringMode

string

default:"one-at-a-time"

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

followUpMode

string

default:"one-at-a-time"

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

transport

string

default:"sse"

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

Terminal & Images

terminal.showImages

boolean

default:"true"

Show images in terminal (if supported)

terminal.clearOnShrink

boolean

default:"false"

Clear empty rows when content shrinks (can cause flicker)

images.autoResize

boolean

default:"true"

Resize images to 2000x2000 max before sending

images.blockImages

boolean

default:"false"

Block all images from being sent to LLM

Shell

shellPath

string

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

shellCommandPrefix

string

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

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

Model Cycling

enabledModels

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

markdown.codeBlockIndent

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

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

extensions

string[]

default:"[]"

Local extension file paths or directories

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

Skills

skills

string[]

default:"[]"

Local skill file paths or directories

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

enableSkillCommands

boolean

default:"true"

Prompts

prompts

string[]

default:"[]"

Local prompt template paths or directories

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

Themes

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

Documentation Index

​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

Build docs developers (and LLMs) love

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