Configuration

Synthex reads project settings from .synthex/config.yaml. Anything you don't specify falls back to the plugin's documented default, so the file only needs to contain the values you actually want to override.

#File location and resolution

/synthex:init/synthex:init creates .synthex/config.yaml at your project root as a copy of the plugin defaults, with inline comments documenting every section. Settings can live in four files. They resolve in this order, with later values winning:

Within a command, per-command overrides (the review_loops: block under a specific command's section) beat the global block, and per-invocation parameters passed to the command itself beat everything.

For when to use each layer, with worked examples, see Workspaces & config layers.

Project settings beat user settings, matching Claude Code's settings precedence, so a repo can pin behavior for everyone who works in it. Only include the keys you want to change at each layer; the rest fall through. You can delete any section you don't want to override; missing keys and missing files do not error.

A project that still keeps settings in the old .synthex-plus/config.yaml keeps working for one major version: it is read just below .synthex/config.yaml, with a deprecation warning when a value only resolves there. Move those keys into .synthex/config.yaml.

/synthex:init/synthex:init also writes .synthex/facts.md, a cache of detected project facts (commit convention, test runner, frontend framework, and a spec index). Agents read it first and fall back to detecting a fact themselves when it is missing or stale. It is gitignored, because the recorded commit SHAs and file times differ per clone.

#Keys that break the order

Two narrow groups of multi-model review keys resolve differently, because they are not the repo's call:

• User-owned: multi_model_review.per_reviewer.*. Which external models are installed on a machine, and what they are called, depends on the machine, not the repo. Your user layer is consulted first, so a repo asking for qwen2.5-coder:32b cannot override the model you actually pulled.
• Restrictive-wins: multi_model_review.enabled and any multi_model_review.*.enabled. false in any hand-written layer disables it, the way Claude Code unions permission deny rules instead of replacing them. A repo cannot turn on sending your code to an external CLI after you have turned it off. Plugin defaults don't count here, so the shipped false is still just a default.

To turn external review off everywhere, whatever a repo asks for:

# ~/.config/synthex/config.yaml
multi_model_review:
  enabled: false

User-level config never makes Synthex treat an unrelated repo as initialized. Hooks still check only the project's own .synthex/ files.

#Global review loops

review_loops:
  max_cycles: 2
  min_severity_to_address: high

Most commands inherit this block. Individual commands can override it under their own section (implementation_plan.review_loops, code_review.review_loops, and so on).

#Model profiles

Pick how much model each spawned agent gets, project-wide or per agent.

models:
  profile: balanced # economy | balanced | premium
  agents:
    code-reviewer:
      model: opus
      effort: high

The tiers only change the agents where it matters; every other agent keeps its shipped settings under any profile:

Commands that spawn agents (/synthex:next-priority/synthex:next-priority,

/synthex:review-code/synthex:review-code, /synthex:performance-audit/synthex:performance-audit, /synthex:refine-requirements/synthex:refine-requirements, /synthex:write-implementation-plan/synthex:write-implementation-plan, /synthex:write-rfc/synthex:write-rfc) accept --profile economy|balanced|premium for one run.

Each agent's model and effort resolve in this order, first match wins:

1. The --profile flag
2. models.agents.<name>
3. The models.profile tier
4. The agent's own shipped settings

On Claude Code the result is applied to each spawned agent directly. Other harnesses treat these keys as advisory: they apply them where the harness supports choosing a model per sub-agent, and otherwise run every sub-agent on the session's model. models.hosts maps each tier to a harness's own model names for that case. A running standing review pool keeps the models it started with; a profile change reaches only newly spawned agents.

#Implementation plan

Used by /synthex:write-implementation-plan/synthex:write-implementation-plan.

implementation_plan:
  reviewers:
    - agent: architect
      enabled: true
      focus: "Technical architecture, feasibility, NFR coverage, missing technical tasks"
    - agent: design-system-agent
      enabled: true
      focus: "Design tasks, UX impact, visual/interaction design clarity"
    - agent: tech-lead
      enabled: true
      focus: "Task clarity, acceptance criteria, parallelizability, dependency accuracy"
  concurrent_tasks: 3
  review_loops:
    max_cycles: 3

To add a project-specific reviewer, append to the list:

implementation_plan:
  reviewers:
    - agent: compliance-reviewer
      enabled: true
      focus: "Regulatory compliance, audit trail requirements"

To disable a default reviewer, set enabled: false on its entry.

Older configs may still list agent: designer. There is no agent by that name; Synthex reads it as design-system-agent here and as lead-frontend-engineer in the refine requirements roster, so existing configs keep working.

#Refine requirements

Used by /synthex:refine-requirements/synthex:refine-requirements.

refine_requirements:
  reviewers:
    - agent: product-manager
      enabled: true
      focus: "Requirement clarity, acceptance criteria, scope boundaries, success metrics"
    - agent: tech-lead
      enabled: true
      focus: "Technical clarity, implicit assumptions, NFR targets, missing requirements"
    - agent: lead-frontend-engineer
      enabled: true
      focus: "UX clarity, interaction patterns, accessibility, user flow completeness"

The roster mirrors the plan reviewers but with PRD-focused prompts. The Product Manager always leads the interview; reviewers join the clarity loop afterward.

#Code review

Used by /synthex:review-code/synthex:review-code.

code_review:
  reviewers:
    - code-reviewer
    - security-reviewer
  max_diff_lines: 300
  convention_sources:
    - CLAUDE.md
    - .eslintrc
    - .prettierrc
  spec_paths:
    - docs/specs

For performance-critical code, add the optional performance-engineer reviewer:

code_review:
  reviewers:
    - code-reviewer
    - security-reviewer
    - performance-engineer

Specialist reviewers (compliance, accessibility, domain experts) attach via the specialists: block in the same section.

#Verification pass

code_review:
  verification: prose # prose | off

With prose, the Code Reviewer, Security Reviewer, and Performance Engineer each check their own top five critical and high findings before reporting them. They use a language-server tool when the session has one, otherwise they grep for the symbol's references. Each checked finding gets a Verification: line: CONFIRMED (lsp), CONFIRMED (grep), or PLAUSIBLE (none) when it couldn't be checked. Verification never blocks the review.

It is off by default because it adds tool calls and changes the report. The review engine has its own, heavier check, refute_pass, which is a separate key.

#Prompt-file reviewers

Any reviewers entry can point at a markdown prompt file in your project instead of naming a Synthex agent. A review prompt you already maintain — a CI guardian prompt, a house checklist, a domain rule set — then runs as part of a Synthex review without being rewritten as a plugin agent. Its findings are deduped, severity-ranked, and attributed alongside every other reviewer's rather than landing in a section of their own.

Accepted in every reviewer block: code_review.reviewers, implementation_plan.reviewers, and refine_requirements.reviewers. - prompt: and - agent: entries mix freely in one list.

code_review:
  reviewers:
    - code-reviewer
    - security-reviewer
    - prompt: .github/scripts/pr-guardian/prompt.md
      id: pr-guardian # optional; here it would default to `pr-guardian` anyway
      enabled: true # optional; defaults to true

In blocks that support focus: (implementation_plan, refine_requirements), a focus: on a prompt: entry is appended to the borrowed prompt the same way.

Frontmatter. The file may carry YAML frontmatter; only name is read (as the id fallback). Every other field is ignored rather than rejected, so a prompt written for another runner stays valid. A file with no frontmatter is fine — the whole file is the prompt.

Output contract. Synthex appends the host command's reviewer output format to the prompt. Where the borrowed prompt specifies its own output format, the appended contract wins.

Read-only by convention. Borrowed CI prompts often post comments or call gh. The appended contract tells the reviewer to apply the review criteria but ignore any instruction to post, write, or otherwise act. This is a convention, not a sandbox — review prompt files the way you review any code that runs in your repo.

Failure modes degrade, never abort. A missing, unreadable, empty, absolute, or project-escaping path skips that one reviewer with a warning; the rest of the review continues. A prompt reviewer that returns nothing is reported as FAIL (no response), the same as a named reviewer. A review left with no usable reviewers at all reports FAIL rather than an empty PASS.

Standing pools. When /synthex:review-code/synthex:review-code routes a review to a standing review pool, the pool's report is the review and prompt-file reviewers do not run. A reviewer list made up entirely of prompt files skips pool routing.

#Quality / testing

Used by /synthex:test-coverage-analysis/synthex:test-coverage-analysis.

quality:
  coverage_thresholds:
    line: 80
    branch: 70
    function: 80
  test_runner: vitest
  priority_modules: []

#Architecture

Used by /synthex:write-adr/synthex:write-adr and /synthex:write-rfc/synthex:write-rfc.

architecture:
  decisions_path: docs/specs/decisions
  rfcs_path: docs/specs/rfcs

#Design system

Used by /synthex:design-system-audit/synthex:design-system-audit.

design_system:
  spec_path: docs/specs/design-system.md
  scan_paths:
    - src/

Add framework-specific specialists (Storybook expert, Figma expert) via the specialists: block.

#Reliability

Used by /synthex:reliability-review/synthex:reliability-review.

reliability:
  slo_document: docs/specs/slos.md
  runbooks_path: docs/runbooks

#Performance audit

Used by /synthex:performance-audit/synthex:performance-audit.

performance_audit:
  review_loops:
    max_cycles: 2

The performance audit only carries a per-command review_loops override; everything else inherits global defaults.

#Retrospective

Used by /synthex:retrospective/synthex:retrospective.

retrospective:
  output_path: docs/retros
  format: start-stop-continue
  max_improvement_items: 3

#Next priority

Used by /synthex:next-priority/synthex:next-priority.

next_priority:
  concurrent_tasks: 3
  execution_environment: local # local | cloud | workspace

Override concurrent_tasks per invocation by passing concurrent_tasks=N to the command. execution_environment is overridden per call by --in-cloud / --in-workspace / --local (flag beats key beats local; --local wins any conflict, and --in-cloud with --in-workspace is refused). cloud is Cursor-only: each worker gets its own VM and branch. workspace runs each worker in an Orca or Herdr child workspace. When a mode isn't available, Synthex prints a one-line notice and falls back to local worktrees. See Cloud agents and Host workspaces.

#Workflow engines

Two keys opt pieces of Synthex into Workflow scripts on Claude Code. Both ship as prose.

code_review:
  engine: prose # prose | workflow
  refute_pass: off # on | off

native_looping:
  engine: prose # prose | workflow

workflow only takes effect when a Workflow tool is in the session's tool list (and, for the loop engine, without --loop-isolated). Everywhere else, including every other harness, the command runs prose. Headless runs need a Workflow(synthex:review-code-engine) or Workflow(synthex:loop-engine) permission allow rule. See Workflow engines for what each engine does and when to turn it on.

#Worktrees

Used by /synthex:next-priority/synthex:next-priority for parallel task execution.

worktrees:
  base_path: .claude/worktrees
  branch_prefix: "feature/"

Use an absolute path (e.g., /tmp/synthex-worktrees) if you want worktrees outside the repo. On Claude Code, the default base_path lets Synthex use the Agent tool's built-in isolation: "worktree". Claude Code always creates those worktrees under .claude/worktrees, so a custom base_path switches back to Synthex's own git worktree add. branch_prefix applies either way. Host workspaces (execution_environment: workspace) ignore base_path, because the workspace manager decides where checkouts live.

#Commit convention

Synthex agents write their own commit messages in your project's convention.

git:
  commit_convention: auto # conventional | issue-key | gitmoji | plain | auto

/synthex:init/synthex:init samples up to your last 50 commits on every run and writes the majority pattern here, printing Detected commit convention: <value> (from <N> commits). Set it by hand to override.

When the value is exactly conventional, a commit-lint hook checks each git commit -m subject the agent runs (on Claude Code and Codex) and blocks one that doesn't match, with a hint so the agent can fix it. Every other value, including auto, is never linted.

The hook also checks a message piped to git commit -F - when the message is written out in the same command: a heredoc on the commit (git commit -F - <<'MSG'), cat <<EOF | git commit -F -, or a single literal piped from printf or echo. It lints the first non-empty, non-comment line, and finds the commit inside an && chain. This is how the Tech Lead, the Lead Frontend Engineer, and /synthex:next-priority/synthex:next-priority write their commits, so Synthex's own commits are now checked too.

The hook fails open whenever it can't be sure what the message is: no Node.js, no config, -F <file>, a message built from variables or command substitution, an unquoted heredoc that contains $, a here-string, more than one heredoc or more than one git commit in the command, an amend that keeps the message, or a merge in progress all pass through.

#Multi-model review

The multi_model_review block turns on review by external model CLIs alongside Synthex's own reviewers. It is off by default; /synthex:configure-multi-model/synthex:configure-multi-model writes it for you. Synthex calls each CLI with your own login; it holds no API keys. Two groups of its keys resolve differently from everything else — see Keys that break the order. For how the fan-out and consolidation work, see Multi-model review.

multi_model_review:
  enabled: false
  reviewers: [] # e.g. codex-review-prompter, gemini-review-prompter, ollama-review-prompter
  per_reviewer:
    codex-review-prompter:
      model: gpt-5
      family: openai
      allow_api_key_billing: false
  per_command:
    review_code:
      enabled: false
    write_implementation_plan:
      enabled: false

#Top-level keys

Codex billing. per_reviewer.codex-review-prompter.allow_api_key_billing defaults to false: Synthex unsets CODEX_API_KEY and OPENAI_API_KEY for Codex calls so they use your stored codex login. Set it to true to allow per-token API-key billing.

#context

The context bundle every proposer receives, assembled once per review.

#aggregator

#per_command

#Consolidation, demotion, and audit

#external_permission_mode

How much each external CLI may do. read-only runs the CLI in its read-only or sandbox mode. parent-mediated proxies its tool approvals back to your session. sandbox-yolo gives it full permissions inside an OS sandbox and asks you to confirm at spawn.

Any other key in this block is ignored. Adapter binary names are fixed in each adapter, never read from config.

#Standing pools

The standing_pools block controls standing review pools: long-lived reviewer teams that

/synthex:review-code/synthex:review-code and /synthex:performance-audit/synthex:performance-audit route to when one is running. It is off by default; /synthex:configure-teams/synthex:configure-teams writes it for you. Pools need Claude Code's Agent Teams tools. See Standing pools.

Standing-pool settings used to live in synthex-plus's .synthex-plus/config.yaml. Since Synthex 2.0 they belong in .synthex/config.yaml; the legacy file is still read for one major version, with a deprecation warning when a value only resolves there.

/synthex:configure-teams/synthex:configure-teams writes only .synthex/config.yaml.

#Lifecycle

lifecycle:
  submission_timeout_seconds: 300

This is a top-level block, not nested under standing_pools, because it governs the submitting command, not the pool.

#Hooks

The TaskCompleted and TeammateIdle hooks only act when standing_pools.enabled is true; otherwise they do nothing.

See Hooks for every hook Synthex installs.

#Document paths

Default locations for project documents. Commands consult these unless overridden by their own parameters.

documents:
  requirements: docs/reqs/main.md
  implementation_plan: docs/plans/main.md
  specs: docs/specs
  decisions: docs/specs/decisions
  rfcs: docs/specs/rfcs
  runbooks: docs/runbooks
  retros: docs/retros

Most commands accept an explicit path parameter, so changing these is rarely necessary.

#A minimal override file

If your project follows the defaults closely, your .synthex/config.yaml can be very short:

next_priority:
  concurrent_tasks: 6

code_review:
  reviewers:
    - code-reviewer
    - security-reviewer
    - performance-engineer

Everything else inherits from the plugin defaults. /synthex:init/synthex:init will scaffold a fully-commented file when you want every setting visible at once.

#Next

• The lifecycle — how each command fits into the five-phase loop
• Parallel execution — how concurrent_tasks and worktree settings interact
• Workspaces & config layers — when to use each config layer
• Getting started — install Synthex and run your first command