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

```json
{
  "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**.

```json
{
  "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|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 [Pi Packages](/pi/packages/index.md) 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/index.md) — Pi configuration overview
- [[models|models]] — Provider and model definitions
- [Pi Packages](/pi/packages/index.md) — Installed package documentation
- [[skills|skills]] — Installed skill documentation