dank/command-center
1
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
fix/42-deploy-generated
command-center/omp-docs/core/settings.md
T
Frank 99b9a6a17c docs(pi): unify split package trees; move live OMP pages to core 
Two directories documented one concept (pi npm packages): top-level
packages/ (browser-use, permission-system) and pi/packages/ (peon,
web-access, subagents). Merged into pi/packages/ — one row per package
in a single index, detail pages kept as archive records. The root
index's 'OMP packages and skills' section was doubly wrong (packages/
was pi, not OMP); it becomes a Skills tooling section pointing at the
consolidated /skills/ tree.

Moved the two LIVE omp pages out of the retired-harness banner:
pi/statusline.md -> core/statusline.md, pi/subagent-limits.md ->
core/subagent-limits.md (both document omp behavior against
agent/config.yml + the installed bundle; pi/index.md itself admitted
the mis-shelf). Retargeted every inbound link (core/index, system/
dankserver, log x2, pi/index, settings x2, moved files' own xrefs).

Refs #29
2026-10-19 03:32:07 -07:00

241 lines
8.8 KiB
Markdown
Raw Permalink Blame History

---
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
Reference in New Issue View Git Blame Copy Permalink