Defaults reference

These are the built-in defaults. ~/.orch/config.yaml overrides them per key; see Configuration for what each key means.

Default agent: claude

Agents

claude

Command: claude

agents:
  claude:
    command: claude
    args:
      - -p
      - --output-format
      - json
      - --
      - "{prompt}"
    output: claude-json
    summaryArgs:
      - -c
      - -p
      - --
      - "{prompt}"
    modelArgs:
      - --model
      - "{model}"
    effortArgs:
      - --effort
      - "{effort}"
    writeArgs:
      - --permission-mode
      - acceptEdits
    limitPatterns:
      - rate.?limit
      - usage limit
      - quota
      - too many requests
      - limit reached
      - overloaded
    authPatterns:
      - failed to authenticate
      - oauth session expired
      - not logged in
      - please run /login
      - invalid api key
      - could not be refreshed
      - sign in again
    defaultCooldownSec: 3600

codex

Command: codex

agents:
  codex:
    command: codex
    args:
      - exec
      - --json
      - --
      - "{prompt}"
    output: codex-jsonl
    summaryArgs:
      - exec
      - resume
      - --last
      - --
      - "{prompt}"
    modelArgs:
      - -m
      - "{model}"
    effortArgs:
      - -c
      - model_reasoning_effort="{effort}"
    writeArgs:
      - -s
      - workspace-write
    limitPatterns:
      - rate.?limit
      - usage limit
      - quota
      - too many requests
      - limit reached
      - overloaded
    authPatterns:
      - failed to authenticate
      - oauth session expired
      - not logged in
      - please run /login
      - invalid api key
      - could not be refreshed
      - sign in again
    defaultCooldownSec: 3600

Context presets

Extra flags per agent that shrink the fixed context of every call. Select one with context: in a rule, orch run --context NAME, or the MCP context parameter. Presets are off unless selected.

contexts:
  lean:
    claude:
      - --setting-sources
      - project
      - --disable-slash-commands
    codex:
      - --disable
      - hooks
      - --disable
      - plugins
      - --disable
      - apps
  minimal:
    claude:
      - --safe-mode
    codex:
      - --disable
      - hooks
      - --disable
      - plugins
      - --disable
      - apps
      - --disable
      - multi_agent
      - --disable
      - goals
      - --disable
      - image_generation

Roles

Built-in roles and teams. Select a role with --role, a team with --team, or a list with --roles; a role is one ordinary run with its own prompt, agent, model and context.

roles:
  developer:
    prompt: You are the developer. Implement the task below with the smallest change
      that satisfies it. Edit the project files directly, follow the project's
      existing conventions, and do not add unrelated changes.
    needs: []
    writes: true
    agentArgs:
      claude:
        - --permission-mode
        - acceptEdits
      codex:
        - -s
        - workspace-write
  tester:
    prompt: You are the tester. Add or update automated tests for the task below and
      for the changes already made in the working tree. Change test files only,
      never application code. Run the tests only if the project already has them
      set up.
    needs: []
    writes: true
    agentArgs:
      claude:
        - --permission-mode
        - acceptEdits
      codex:
        - -s
        - workspace-write
  architecture:
    prompt: You are the software architect. Analyse the task below and the
      repository. Describe the design, the module boundaries it touches and the
      main risks. When a picture helps, include a Mermaid diagram in a fenced
      code block. Do not modify any files.
    context: lean
    needs: []
    writes: false
  designer:
    prompt: You are a UX/UI designer. Create mockup or diagram images for the task
      below. Save image files only into the assets directory named at the end of
      this prompt, and do not change any project files. Reply with the file
      paths and a short description of each image.
    agent: codex
    needs:
      - image
    writes: false
    agentArgs:
      codex:
        - -s
        - workspace-write
  security:
    prompt: You are a security reviewer. Review the working-tree changes (use git
      status and git diff) against the task below for security problems such as
      injection, broken authorization, exposed secrets, unsafe dependencies and
      data exposure. Report the most serious first, with file and line. Do not
      modify any files.
    context: lean
    needs: []
    writes: false
  reviewer:
    prompt: You are a code reviewer. Review the working-tree changes (use git status
      and git diff) against the task below. Report bugs, risky behavior and
      missing tests, most serious first, with file and line. Do not modify any
      files.
    context: lean
    needs: []
    writes: false
teams:
  quick:
    - developer
  standard:
    - developer
    - tester
    - reviewer
  full:
    - architecture
    - designer
    - developer
    - tester
    - reviewer
    - security
pipeline:
  handoffChars: 4000
  parallel: true
  maxParallel: 2
auto:
  enabled: false
  maxRoles: 3

Routing rules

First matching rule wins; no match uses the default agent.

rules:
  - match: refactor|architecture|migrate|redesign
    agent: claude
  - match: typo|rename|quick|small fix|one-liner
    agent: codex

Environment variables

• ORCH_HOME: state directory (default ~/.orch)
• ORCH_CONFIG: path of the config file (default $ORCH_HOME/config.yaml)
• ORCH_DEPTH: set by orch on the agents it starts; a value of 1 or more makes orch refuse to run (recursion guard)