⚙️ Settings

Where a setting value comes from, which approval mode to pick, and what to put in a first config (350+ settings, 5 resolution layers).

1. Where does a value come from?

Lowest to highest priority:

1. Schema default
2. Global config, ~/.omp/agent/config.yml
3. Project config, <cwd>/.omp/config.yml
4. Ordered --config overlays, including PI_CONFIG_FILES
5. CLI and runtime overrides

Learned the hard way:

• Project settings do not walk up ancestors — only context files (AGENTS.md, RULES.md) do. A .omp/config.yml in a parent of your launch dir is silently ignored.
• Arrays replace wholesale, per layer; they never merge. A project bash.patterns deletes every global pattern for that project.
  • Fix: never define that array at project level, or load the global version as a --config overlay (PI_CONFIG_FILES in your shell profile) so it resolves after project config.
  • Caveat: GUI-spawned omp (ACP, launchd) never sources your shell profile, so an env-based overlay does not reach it.
• omp config get <key> shows the merged effective value from wherever your shell runs it, overlays included. No effect from a change? Ask which layer you edited and which layer wins.

omp config list --json   # every key with its effective value
omp config get <key>
omp config set <key> <value>
omp config path          # which directory the global config lives in
/settings                # same thing with a UI

2. Which approval mode should I choose?

Fresh installs default to yolo. Start with write.

Mode	Behavior
always-ask	Approve each tool action yourself.
write (recommended)	Reads and workspace writes automatic; exec-tier actions need approval.
yolo	Auto-approve reads, writes, and shell commands.

The mode is the baseline: tools.approval overrides it per tool, and the first matching bash.patterns rule overrides the bash policy.

tools:
  approvalMode: write
  approval:
    bash: prompt
bash:
  patterns:
    - { match: "git status*", approval: allow }
    - { match: "rm -r*", approval: deny }

• Under yolo, only deny and prompt rules change bash behavior.
• deny blocks, prompt asks.
• Allow rules must match the full command; deny/prompt inspect compound-command segments.
• eval needs its own policy — Python/JavaScript cells can spawn exec-tier shells, so set tools.approval.eval when that boundary matters.

3. What belongs in my first config?

Key	Shipped default	Start here because
tools.approvalMode	yolo	write keeps routine reads and workspace writes fast while asking before exec-tier actions.
defaultThinkingLevel	high	auto chooses a level per turn instead of fixing every task at high.
secrets.enabled	false	true redacts credential-shaped tokens before they reach providers.

defaultThinkingLevel: auto
secrets:
  enabled: true
tools:
  approvalMode: write

4. What should I add later?

Key	Shipped default	Add when
memory.backend	off	You want recall across sessions — see [[guide/tips
task.isolation.mode	none	Before parallel agents edit; set auto — see [[guide/multi-agent
task.maxConcurrency	32	Cap before broad fan-out — see [[guide/traps
providers.maxInFlightRequests	unlimited	Cap before broad fan-out — see [[guide/traps
retry.fallbackChains	empty	After choosing a real backup provider.

Full reference

Full key catalog, types, and defaults: data/settings.json. Run omp config list --json for your effective values, or open /settings for the same lookup in the UI.

Condensed from the omp guide by Hugo Lopes (MIT). Verify against your install: omp config list.