# Config Guide

> Complete reference for Oh My Pi configuration, settings, and config file formats.

- Skill: `happyshittake/config-guide` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add happyshittake/config-guide`
- Raw SKILL.md: https://api.skillmd.com/api/skills/happyshittake/config-guide/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: happyshittake (https://skillmd.com/u/happyshittake)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/happyshittake/config-guide

---


# Oh My Pi Configuration Guide

This guide covers every config surface in Oh My Pi: the settings schema, CLI commands, MCP servers, LSP setup, keybindings, and config file hierarchy.

## Config File Hierarchy

Config files are resolved in priority order (highest first). Later values override earlier ones.

**User-level directories:**
1. `~/.omp/agent/` (highest)
2. `~/.claude/`
3. `~/.codex/`
4. `~/.gemini/`

**Project-level directories:**
1. `.omp/` (highest)
2. `.claude/`
3. `.codex/`
4. `.gemini/`

**Important rules:**
- The active config directory is determined by the nearest config dir walking up from `cwd`.
- Project-level configs override user-level configs.
- `.omp` takes precedence over `.claude`, `.codex`, and `.gemini`.
- Settings are stored in `config.yml` (or `config.yaml` / `config.json` with auto-migration from JSON to YAML).

## Settings (config.yml)

Settings are the single source of truth for agent behavior. Use `omp config set <key> <value>` to change values — never edit `config.yml` manually while the agent is running.

Settings are organized by tab:

- **Model** — Model selection, sampling, model roles, cycling: `skill://config-guide/settings-model.md`
- **Context** — Compaction, promotion, branch summaries, TTSR: `skill://config-guide/settings-context.md`
- **Appearance, Interaction, Memory, Editing, Tools, Tasks, Providers** — `skill://config-guide/settings-reference.md`

## CLI Commands

```
omp config list              # List all settings with current values
omp config get <key>         # Get a specific setting value
omp config set <key> <value> # Set a setting value
omp config reset <key>       # Reset a setting to its default
omp config path              # Print the config directory path
omp config init-xdg          # Initialize XDG Base Directory structure
```

**Boolean values:** `true`, `false`, `yes`, `no`, `on`, `off`, `1`, `0`

**Array values:** Pass as JSON array string, e.g., `omp config set extensions '["ext1", "ext2"]'`

**Record values:** Pass as JSON object string.

## MCP Servers, LSP, and Keybindings

See `skill://config-guide/mcp-lsp-keybindings.md` for:
- MCP Servers Config (`.mcp.json`)
- LSP Config (`lsp.json` / `.lsp.json` / `lsp.yml`)
- Keybindings Config (`keybindings.json`)

## Important Constraints

1. **Always use `omp config set`** to modify settings. Editing `config.yml` manually while the agent is running will not take effect and may be overwritten.
2. **YAML format** is preferred for `config.yml`. JSON configs are auto-migrated to YAML on first load.
3. **Config priority:** Project-level configs override user-level. `.omp` overrides `.claude`.
4. **MCP server changes** require a restart to take effect.
5. **LSP server discovery** is automatic based on project markers and available binaries. Explicit config overrides auto-detection.
6. **Keybindings** are loaded once at startup. Use the in-app command to reload without restarting.