Configuration

Use this guide when you need to answer two questions quickly:

1. Which config file owns a setting?
2. Which CLI command should I use to inspect or change it?

For the deep file-by-file reference, see:

• File Locations
• .oat Directory Structure
• Sync Config (.oat/sync/config.json)

The four config surfaces

The main split is:

• .oat/config.json for shared repo behavior
• .oat/config.local.json for local developer state
• ~/.oat/config.json for user-scope fallback state
• .oat/sync/config.json for provider sync only

The fastest way to inspect config

Use oat config as the primary discovery surface:

oat config list
oat config get projects.root
oat config describe
oat config describe archive.s3Uri
oat config describe sync.providers.github.enabled

What each command is for:

• oat config list shows the currently resolved command-surface values for shared and repo-local keys.
• oat config get <key> reads one supported key value.
• oat config set <key> <value> updates supported shared or repo-local keys.
• oat config describe shows the supported config catalog across shared repo, repo-local, user, and sync/provider surfaces.
• oat config describe <key> shows file, scope, default, mutability, owning command, and description for one key.

Source labels

oat config get --json and oat config list emit a source field identifying which config surface a resolved value came from. The current labels are:

These labels match what oat config dump emits, so tooling that consumes either command can rely on the same vocabulary.

:::note Upgrade note Earlier CLI versions returned config.json / config.local.json / env / default as the source strings. External scripts that previously matched on "source":"config.json" or "source":"config.local.json" should update to match the new shared / local labels. This change was made to align the oat config get / oat config list output with oat config dump and to avoid confusing users about which file was consulted. :::

Shared repo config you will touch most often

Common keys in .oat/config.json:

• projects.root — where tracked projects live
• worktrees.root — where OAT-managed worktrees live
• git.defaultBranch — base branch fallback for PR workflows
• documentation.root, documentation.tooling, documentation.config — docs-surface ownership
• documentation.requireForProjectCompletion — whether docs sync is a completion gate
• archive.s3Uri — base S3 archive prefix
• archive.s3SyncOnComplete — upload archived projects to S3 during completion
• archive.summaryExportPath — export summary.md into a durable tracked directory during completion
• tools.<pack> — whether a bundled tool pack is currently installed in the repo or user scopes after lifecycle reconciliation

Tool-pack state example:

oat config get tools.project-management
oat config set tools.project-management true

The tools.* keys are primarily maintained by oat tools install, oat tools update, and oat tools remove, but they are intentionally visible through oat config so workflows and operators can inspect or override pack-state signals when needed.

Archive example:

oat config set archive.s3Uri s3://example-bucket/oat-archive
oat config set archive.s3SyncOnComplete true
oat config set archive.summaryExportPath .oat/repo/reference/project-summaries

With those values configured:

• oat-project-complete still archives locally into .oat/projects/archived/<project>/
• completion also attempts an S3 upload when AWS CLI is available and configured, storing dated snapshots such as <archive.s3Uri>/<repo-slug>/projects/20260401-my-project/
• completion also copies summary.md into <archive.summaryExportPath>/20260401-my-project.md
• oat project archive sync can later pull archive data back down from S3 and materialize the latest snapshot into the local bare archive path .oat/projects/archived/<project>/

Repo-local and user state

Use .oat/config.local.json for checkout-specific workflow state:

• activeProject
• lastPausedProject
• repo-scoped activeIdea

Use ~/.oat/config.json for user fallback state when no repo-local value is set:

• activeIdea

In practice, you usually inspect these via:

oat config get activeProject
oat config get lastPausedProject
oat config describe activeIdea

Workflow preferences (workflow.*)

Workflow preferences let power users answer repetitive confirmation prompts once and have OAT workflow skills respect those answers automatically. They are the highest-value escape hatch from interactive friction when you always make the same choices.

Preference keys

All six workflow preference keys live under the workflow.* namespace:

• workflow.hillCheckpointDefault — every or final. Default HiLL checkpoint behavior in oat-project-implement: pause after every phase or only after the last phase. When unset, the skill prompts.
• workflow.archiveOnComplete — boolean. Skip the "Archive after completion?" prompt in oat-project-complete. When unset, the skill prompts.
• workflow.createPrOnComplete — boolean. Skip the "Open a PR?" prompt in oat-project-complete; when true, completion auto-triggers PR creation. When unset, the skill prompts.
• workflow.postImplementSequence — wait, summary, pr, or docs-pr. Controls what oat-project-implement chains after final review passes. wait stops without auto-chaining, summary runs only oat-project-summary, pr runs oat-project-pr-final (which auto-generates summary), docs-pr runs oat-project-document then oat-project-pr-final. When unset, the skill prompts.
• workflow.reviewExecutionModel — subagent, inline, or fresh-session. Default final-review execution model in oat-project-implement. subagent and inline run automatically. fresh-session is a soft preference: the skill prints guidance to run the review in another session but still offers escape hatches to subagent or inline if you change your mind. When unset, the skill prompts.
• workflow.autoNarrowReReviewScope — boolean. Auto-narrow re-review scope to fix-task commits only in oat-project-review-provide. When unset, the skill prompts.

Three-layer resolution

Workflow preferences resolve through three config surfaces, with env > local > shared > user > default precedence per key. This is the same generic resolution used by oat config dump:

• User-level (~/.oat/config.json): personal defaults that apply to every repo. This is where most power users should start — set preferences once, never worry about them again.
• Shared repo (.oat/config.json): team decisions for this repo. Overrides user defaults when present.
• Repo-local (.oat/config.local.json): personal override for this specific repo. Highest precedence per key.

Setting preferences

oat config set supports mutually exclusive surface flags for workflow keys:

# User-level: applies to all repos on this machine
oat config set workflow.hillCheckpointDefault final --user
oat config set workflow.archiveOnComplete true --user
oat config set workflow.createPrOnComplete true --user
oat config set workflow.postImplementSequence pr --user
oat config set workflow.reviewExecutionModel subagent --user
oat config set workflow.autoNarrowReReviewScope true --user

# Shared repo: team decision for this repo
oat config set workflow.createPrOnComplete false --shared

# Repo-local: personal override for this repo (default when no flag)
oat config set workflow.hillCheckpointDefault every

Default (no flag) targets .oat/config.local.json for workflow keys. Pass at most one of --user, --shared, or --local. Structural keys (projects.root, worktrees.root, git.*, documentation.*, archive.*, tools.*) are still shared-only regardless of flag.

Choosing the right surface (personal vs per-repo)

Not every workflow preference belongs at user level, even though "set once, applies everywhere" is tempting. The guiding principle:

If a workflow preference's correctness depends on other repo-level settings, it belongs at shared (per-repo) level, not user level.

Some preferences are genuinely personal — their correct value is the same for you regardless of which repo you're in. These are safe to set at --user:

• workflow.hillCheckpointDefault — your personal tolerance for mid-implementation interruption
• workflow.reviewExecutionModel — depends on your provider environment (Claude Code, Cursor, Codex), not the repo
• workflow.autoNarrowReReviewScope — pure personal workflow preference, no per-repo interaction

Other preferences depend on per-repo configuration to be safe. These should be set at --shared (in each repo where they apply), not --user:

• workflow.archiveOnComplete — correctness depends on the repo's archive.s3Uri / archive.s3SyncOnComplete being configured. A user-level true would try to archive in repos that aren't set up for it.
• workflow.postImplementSequence — correctness depends on documentation.requireForProjectCompletion. Setting pr at user level would foot-gun you in any repo that requires docs, because completion would later block on the docs gate while the PR is already open.
• workflow.createPrOnComplete — this key is almost always redundant with postImplementSequence-driven flows. When it's meaningful, its correctness depends on the same per-repo docs and PR gates. Prefer shared scope, or omit it entirely and rely on postImplementSequence: pr or docs-pr to handle PR creation at the end of implement.

Cross-repo foot-gun example: If you set workflow.createPrOnComplete: true --user, it applies to every repo you work on. In a repo with documentation.requireForProjectCompletion: true and postImplementSequence: pr (no docs step), running oat-project-complete would try to auto-create a PR, then immediately hit the docs gate and block you — leaving you with an open PR and a stuck completion. Your user-level preference silently asserted something that only holds in a specific shared-config shape.

Recommended split for most users:

# Personal defaults (apply everywhere)
oat config set workflow.hillCheckpointDefault final --user
oat config set workflow.reviewExecutionModel subagent --user
oat config set workflow.autoNarrowReReviewScope true --user

# Per-repo team decisions (set in each repo where they apply)
oat config set workflow.archiveOnComplete true --shared
oat config set workflow.postImplementSequence docs-pr --shared  # or "pr" if docs aren't required

If you want to override a shared team decision for this specific checkout, use --local:

oat config set workflow.archiveOnComplete false --local  # "I don't want to archive on this specific branch checkout"

Relationship to autoReviewAtCheckpoints

The existing autoReviewAtCheckpoints key (top-level in .oat/config.json) was not migrated under the workflow.* namespace to preserve backward compatibility. It remains shared-scope-only and controls whether oat-project-implement auto-triggers code reviews at plan phase checkpoints. That is a separate behavioral toggle from the workflow preferences above — it affects when reviews happen, not which prompt-skipping defaults apply.

If you enable both, you get a near-uninterrupted lifecycle: auto-review runs at checkpoints, fix tasks are converted automatically, and the workflow preferences skip every remaining confirmation prompt.

Provider sync config is different

Provider sync settings are intentionally documented in the same discovery flow, but they are not owned by oat config set.

Examples:

oat config describe sync.defaultStrategy
oat config describe sync.providers.<name>.enabled
oat providers set --scope project --enabled claude,codex

Use:

• oat config describe ... to understand sync keys
• oat providers set ... to mutate sync/provider settings

For the provider-sync schema details, use Sync Config (.oat/sync/config.json).

Recommended workflow

When you are unsure where a setting lives:

1. Run oat config describe.
2. Run oat config describe <key> for the key you care about.
3. Use the owning command shown there.

That keeps config discovery centralized without forcing you to remember which settings belong to workflow state versus provider sync.