πomp guide
# Settings, demystified This page answers four first questions: where a value comes from, which approval mode to choose, what to put in a first config, and what to add later. *Verified against the release in [`data/version.txt`](https://github.com/HugoLopes45/omp-guide/blob/main/data/version.txt).*
350+
settings
5
resolution layers
3
first decisions

1. Where does a value come from?

Values resolve 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

Three facts people learn the hard way:

  1. Project settings do not walk up ancestors. Only context files (AGENTS.md, RULES.md) do. A .omp/config.yml in a parent directory of where you launched is silently ignored.
  2. Arrays replace wholesale, per layer. They do not merge. If a project .omp/config.yml defines bash.patterns, it deletes every global pattern for that project. If you keep global guardrails in an array, either never define that array at project level, or load the global version as a --config overlay (via 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.
  3. omp config get <key> shows the merged, effective value from wherever your shell runs it, overlays included. When a change seems to have no effect, ask which layer you edited and which layer wins.

Useful commands:

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: read and workspace-write tools stay automatic, while exec-tier actions still require approval.

always-ask

Approve each tool action yourself.

write recommended

Keep reads and workspace writes automatic. Approve exec-tier actions.

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, and allow rules must match the full command while deny and prompt inspect compound-command segments. eval needs its own approval policy: Python and JavaScript cells can spawn exec-tier shells, so use 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?

Cross-session recall

memory.backend ships off. Enable it when you want recall across sessions. Read memory tips first.

Parallel writers

task.isolation.mode ships none. Set it to auto before parallel agents edit. Read isolation guidance.

Rate-limit control

task.maxConcurrency ships 32; providers.maxInFlightRequests is unlimited. Cap both before broad fan-out. Read autonomy traps.

Provider fallback

retry.fallbackChains ships empty. Add it after choosing a real backup provider.

Full reference

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