# Settings

## Oh My Pi host settings

Use `<project>/.omp/config.yml`. POM creates a recommended file during project bootstrap and ships the same template at `config/config.yml`.

Important host controls:

| Key | POM purpose |
|---|---|
| `theme.dark/light` | Select POM Nocturne/Parchment after `/pom theme install` |
| `statusLine.showHookStatus` | Display POM stage, gate, Hive, retry, and approval segments |
| `terminal.showImages` | Show visual references and generated images in capable terminals |
| `tools.intentTracing` | Expose semantic tool intent in the live experience |
| artifact spill settings | Keep large tool output out of the conversation surface |
| `task.batch` / concurrency | Support bounded specialist waves |
| `compaction.strategy: snapcompact` | Preserve long-running production context |
| one-at-a-time steering/follow-up | Keep autopilot continuation ordered |

## POM settings

Precedence:

```text
built-in defaults
→ ~/.omp/agent/pom.json
→ <project>/.omp/pom.json
→ persisted project state for mutable experience fields
```

| Setting | Values | Purpose |
|---|---|---|
| `autoToolProfiles` | boolean | Route OMP active tools by stage |
| `autoModelRouting` | boolean | Resolve and activate the stage model role |
| `dashboardWidget` | boolean | Enable the persistent HUD |
| `stopGuard` | boolean | Continue an active stage briefly, then force explicit blocking |
| `defaultMode` | `autopilot`, `collaborative`, `strict-autopilot` | Select prompt personality |
| `defaultView` | `cinematic`, `rich`, `compact`, `minimal` | Select terminal information density |
| `defaultMotion` | `off`, `subtle`, `full` | Select activity animation intensity |
| `defaultToolProfile` | `auto`, `creative`, `research`, `draft`, `audit`, `delivery` | Initial active-tool policy |
| `maxStudioAgents` | 1–12 | Bound a Hive task batch |
| `projectRootMode` | `child`, `cwd` | Create a child project or use the current directory |
| `destructiveProjectCommands` | `block`, `allow` | Guard recursive destructive commands |
| `gitMode` | `off`, `checkpoint`, `branch-per-stage` | Control production checkpoints |
| `hudPlacement` | `aboveEditor`, `belowEditor` | Place the production HUD |
| `showThinkingLane` | boolean | Annotate visible thinking with stage/execution lane |

`/pom settings` persists view/motion in project state and HUD/thinking options in `.omp/pom.json`.

## Compatibility and verification state

| Requirement | Window | Source |
|---|---|---|
| `@oh-my-pi/pi-coding-agent` | `>=16.4.6 <17` | `peerDependencies` |
| `@oh-my-pi/pi-tui` | `>=16.4.6 <17` | `peerDependencies` |
| `@oh-my-pi/pi-utils` | `>=16.4.6 <17` | `peerDependencies` |
| Bun | `>=1.3.14` | `engines.bun` |
| Node.js + npm | Node 22 or newer | Local scripts and the `node:test` suite |

Verification state: `npm run verify` exits 0 from a clean `npm install`. Seven evidence-backed gates PASS, `npm audit` on the full development tree FAILS on 16 dev-only transitive advisories under the `@oh-my-pi/*` peer SDK (production audit reports 0, so nothing reaches the published tarball), and two host-dependent gates (`npm run doctor`, interactive TUI smoke) remain NOT RUN. See the README section Verification status.