config-guide

name	config-guide
description	Complete reference for Oh My Pi configuration, settings, and config file formats.

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.