command-center/omp-docs/core/settings.md

type, title, description, tags, verified, timestamp

type	title	description	tags	verified	timestamp
reference	Pi Settings System (settings.json)	Complete reference for pi's main configuration file — providers, models, packages, subagent overrides, and runtime options.	settings configuration json providers models subagents	2026-08-28	2026-08-28

pi Settings System (settings.json)

settings.json is pi's main configuration file. It determines which models the agent talks to, which packages load, how subagents behave, and general runtime preferences.

Location: /home/dank/.pi/agent/settings.json

Format: JSON.

---

Current Configuration

{
  "lastChangelogVersion": "0.84.3",
  "theme": "dark",
  "defaultProvider": "llamacpp (dankclaw)",
  "defaultModel": "frank-default-large",
  "defaultThinkingLevel": "medium",
  "hideThinkingBlock": false,
  "subagents": {
    "defaultModel": "frank-default-small",
    "defaultThinking": "max",
    "agentOverrides": {
      "scout": { "model": "frank-default-small" },
      "researcher": { "model": "frank-default-small" },
      "planner": { "model": "frank-default-large" },
      "worker": { "model": "frank-default-large" },
      "reviewer": { "model": "frank-default-large" },
      "oracle": { "model": "frank-default-large" },
      "context-builder": { "model": "frank-default-large" }
    },
    "watchdog": { "enabled": true }
  },
  "packages": [
    "npm:@wierdbytes/pi-peon",
    "npm:pi-web-access",
    "npm:@narumitw/pi-worktree",
    "npm:@juicesharp/rpiv-todo",
    "npm:@juicesharp/rpiv-ask-user-question",
    "npm:@ff-labs/pi-fff",
    "npm:pi-intercom",
    "npm:@juicesharp/rpiv-btw",
    "npm:@xynogen/pix-pretty",
    "npm:@xynogen/pix-bash",
    "npm:@xynogen/pix-ssh",
    "npm:@xynogen/pix-write",
    "npm:@xynogen/pix-sudo",
    "npm:@xynogen/pix-read",
    "npm:@xynogen/pix-ls",
    "npm:@xynogen/pix-edit"
  ],
  "enableSkillCommands": true,
  "autocompleteMaxVisible": 10,
  "terminal": { "showTerminalProgress": true },
  "steeringMode": "one-at-a-time",
  "transport": "auto",
  "httpIdleTimeoutMs": 0,
  "retry": {
    "enabled": true,
    "maxRetries": 3,
    "baseDelayMs": 10000
  },
  "markdown": { "mermaid": "streaming" },
  "fullscreenScrollbar": "always",
  "tuiMode": "fullscreen",
  "warnings": { "anthropicExtraUsage": false },
  "treeFilterMode": "default",
  "doubleEscapeAction": "none",
  "enabledModels": [
    "llamacpp (dankserver)/frank-default-small",
    "llamacpp (dankclaw)/frank-default-large",
    "openrouter/~deepseek/deepseek-v4-flash-latest",
    "openrouter/openai/gpt-5.6-luna"
  ],
  "outputPad": 1,
  "editorPaddingX": 0,
  "modelThinkingLevels": {
    "llamacpp (dankclaw)/frank-default-large": "medium",
    "llamacpp (dankserver)/frank-default-small": "medium"
  }
}

---

Top-Level Fields

Field	Type	Required	Description
lastChangelogVersion	string	No	Schema version. Incremented on schema changes. Mismatch triggers a migration prompt.
theme	string	No	UI theme. Values: "dark", "light".
defaultProvider	string	Yes	Provider name from models.json. Pi will not start without a valid provider.
defaultModel	string	Yes	Model ID within the default provider. Must match an id in models.json.
defaultThinkingLevel	string	No	Default reasoning depth: "off", "low", "medium", "high", "max".
hideThinkingBlock	boolean	No	If true, the agent's chain-of-thought is hidden in the TUI.
packages	string[]	No	Installed pi packages. Format: npm:<package-name>.
subagents	object	No	Subagent configuration. Controls model selection per agent role.
enableSkillCommands	boolean	No	Enable skill command triggers.
autocompleteMaxVisible	number	No	Max visible autocomplete suggestions.
terminal	object	No	Terminal display options.
steeringMode	string	No	Agent steering mode (e.g. "one-at-a-time").
transport	string	No	Transport protocol ("auto", etc.).
httpIdleTimeoutMs	number	No	HTTP idle timeout in milliseconds.
retry	object	No	Retry configuration with backoff.
markdown	object	No	Markdown rendering options (e.g. mermaid mode).
fullscreenScrollbar	string	No	Scrollbar visibility mode.
tuiMode	string	No	TUI display mode.
warnings	object	No	Warning suppression settings.
treeFilterMode	string	No	File tree filtering mode.
doubleEscapeAction	string	No	Double-escape key action.
enabledModels	string[]	No	List of all available model IDs for switching.
outputPad	number	No	Output padding.
editorPaddingX	number	No	Editor X padding.
modelThinkingLevels	object	No	Per-model thinking level overrides.

---

Subagent Configuration

The subagents block controls which models subagents use and how they reason.

Fields

Field	Type	Description
defaultModel	string	Fallback model for subagents without an explicit override.
defaultThinking	string	Default reasoning depth for subagents.
agentOverrides	object	Per-role model assignments. Keys are agent roles.
watchdog.enabled	boolean	Enable the watchdog system that monitors subagent health.

Agent Roles and Model Assignments

Role	Model	Purpose
scout	frank-default-small	Quick exploration tasks
researcher	frank-default-small	Web research and information gathering
planner	frank-default-large	Task planning and decomposition
worker	frank-default-large	Heavy implementation work
reviewer	frank-default-large	Code and document review
oracle	frank-default-large	Complex reasoning and analysis
context-builder	frank-default-large	Building context for other agents

---

Retry

Automatic agent-level retries use exponential backoff. The current configuration allows three retries with delays of 10 seconds, 20 seconds, and 40 seconds.

{
  "retry": {
    "enabled": true,
    "maxRetries": 3,
    "baseDelayMs": 10000
  }
}

---

Provider Configuration

Location: ~/.pi/agent/models.json

Providers define where pi gets its LLM. The default provider is specified in settings.json and the provider definitions live in models.json.

Currently configured providers:

Provider	Base URL	Model	GPU
llamacpp (dankserver)	http://192.168.0.235:7770/v1	frank-default-small (Qwen3.6-35B-A3B FP8, moe-cache 2048)	RTX 3090
llamacpp (dankclaw)	http://192.168.0.143:7770/v1	frank-default-large (Qwen3.8-Flash-Next Q4_0 ROCmFP4 Strix)	RTX 4070 Max-Q

See models for the complete models.json reference.

---

Package Configuration

Location: ~/.pi/agent/settings.json (via packages array) + ~/.pi/agent/npm/ (on-disk)

Each package entry is a specifier string. The format is npm:<package-name>. When pi starts, it:

1. Reads the packages array from settings.json
2. Checks ~/.pi/agent/npm/node_modules/<name>/ for each package
3. Loads extensions, skills, prompts, and themes from each package

Currently installed:

Package	Version	Description
@wierdbytes/pi-peon	0.1.1	CESP/OpenPeon sound-pack player for pi lifecycle events
pi-web-access	0.22.0	Web search, URL fetching, GitHub cloning, PDF extraction, YouTube understanding
@narumitw/pi-worktree	0.51.6	Worktree management for git-based parallel development
@juicesharp/rpiv-todo	2.7.1	Todo/task management package
@juicesharp/rpiv-ask-user-question	2.7.1	Interactive user question prompts
@ff-labs/pi-fff	0.10.5	File/flow functions
pi-intercom	0.12.0	Inter-process communication
@juicesharp/rpiv-btw	2.7.1	Between-task utilities
@xynogen/pix-pretty	1.18.1	Code formatting
@xynogen/pix-bash	0.2.1	Bash shell utilities
@xynogen/pix-ssh	0.2.6	SSH management
@xynogen/pix-write	0.2.1	File writing utilities
@xynogen/pix-sudo	0.3.20	Privileged operations
@xynogen/pix-read	0.2.1	File reading utilities
@xynogen/pix-ls	0.2.1	Directory listing
@xynogen/pix-edit	0.2.1	File editing utilities

See packages for full package documentation.

---

Migration

When lastChangelogVersion is behind pi's internal version, pi prompts for migration. The migration updates the JSON structure while preserving values. Back up before migrating.

---

See Also

• pi — Pi configuration overview
• models — Provider and model definitions
• packages — Installed package documentation
• skills — Installed skill documentation