Frank
02883d3ed2
Copy of the legacy ~/.pi/agent/docs tree rebuilt as the command-center knowledge base: concept files promoted to path identity, index listings stripped of frontmatter, all wikilinks/relative links resolved, every checkable claim verified against the live fleet (Dankserver = Ryzen 7 7700X + RTX 3090; Strix Halo is Dankclaw), unverifiable claims tagged. kb-lint exits 0.
241 lines
8.8 KiB
Markdown
241 lines
8.8 KiB
Markdown
---
|
|
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 [packages](../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
|
|
- [packages](../packages/index.md) — Installed package documentation
|
|
- [[skills|skills]] — Installed skill documentation
|