Frank
62a70caebb
`[[page|Label]]` is Obsidian syntax, not OKF. `kb-lint` resolves it Obsidian-style — by filename, anywhere in the bundle — so it has never tripped the link gate, while every other consumer of the bundle (an OKF renderer, a Gitea wiki export, `grep` for reachability) sees bracketed text where a link should be. That is how two generated pages ended up with no inbound link at all and nobody noticed: the my-first link census of the bundle reported them as orphans because their only inbound edges were wikilinks. Mechanical conversion, 52 links across 17 pages, each resolved against the same page set `kb-lint` uses: an explicit `|Label` is kept verbatim, an unlabelled link takes the target's frontmatter `title`. Targets are emitted bundle-absolute (`/tools/niri/tips.md`), the form the spec recommends and the form 99 existing links in this bundle already use. Two links were `[[index]]`, which resolves by filename to 21 pages — the ambiguity that filename-resolution invites. Both meant their own directory's index, so both are now written out in full: `/tools/gitea/index.md`, `/tools/niri/index.md`. The linter still tolerates wikilinks; whether it should reject them outright is an open question on #64, because that would replace the two tests pinning today's tolerance. Refs #64
241 lines
8.9 KiB
Markdown
241 lines
8.9 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](/pi/models.md) 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](/pi/models.md) — Provider and model definitions
|
|
- [Pi Packages](/pi/packages/index.md) — Installed package documentation
|
|
- [skills](/pi/skills.md) — Installed skill documentation
|