Config reference

The Code Sentinel orchestrator reads its settings from the orchestrator block of .code-analyzer-config.json at the root of your repository. The file is committed, so every machine and every person running the orchestrator on that repository gets the same behaviour.

Every key is optional. With no file at all, the orchestrator detects what it can and uses the defaults below.

Example

{
  "orchestrator": {
    "base": "develop",
    "maxSlots": 5,
    "readyLabel": "cs:ready",
    "specDir": "docs/specs",
    "install": "bun install",
    "checks": ["bun run lint", "bun run test", "bun run build"],
    "mergeMethod": "merge",
    "autoMerge": true,
    "defaultModel": "sonnet",
    "triageSkill": null
  }
}

A smaller setup, squashing into main with at most three workers:

{
  "orchestrator": {
    "base": "main",
    "maxSlots": 3,
    "checks": ["bun run lint", "bun run test", "bun run build"],
    "mergeMethod": "squash"
  }
}

Keys

The orchestrator writes the resolved values at the top of each round board, so you can check what it actually used.

specDir outside the repository

On the plugin's develop branch (plugin #7, not released to main at the time of writing), specDir also accepts:

• a path outside the repository, relative (../acme-docs/specs) or absolute;
• github:<owner>/<repo>[/<subpath>], or the https://github.com/<owner>/<repo> URL of it.

Specs are then read only from the spec repository's origin/<branch> after a fetch, never from a working tree, so an unmerged spec counts as NO SPEC.

mergeApproval

On that branch, with mergeApproval: true, a green pull request waits until an approval newer than its head commit exists. Any one of three sources counts: an approval file under <git-common-dir>/cs-orchestrator/approvals/, a GitHub review from someone other than the author, or the cs:approved label. A fresh "changes requested" review wins over the label. AgentDock's Approve button writes an approval file, but in a format that branch does not accept yet, so approve through GitHub until the two are reconciled.

How AgentDock uses this file

AgentDock reads the file and never writes it. AgentDock does not edit committed files in your repository.

• When you connect a project, the runner's inspection reads the orchestrator block and stores it as the project's config snapshot. An operator can refresh the snapshot through the API with POST /api/projects/<id>/refresh.
• The snapshot feeds the defaults AgentDock shows: the base branch, the ready label and whether merge approval is expected.
• Merge approval mismatch. If merge approval is on in Project → Settings but the file does not set orchestrator.mergeApproval: true, the Approvals page shows Merge approval settings disagree, because the orchestrator would merge on its own. Fix it in the file, not in AgentDock.

Ready label precedence

AgentDock decides which label means "ready" in this order:

1. Ready label override in Project → Settings, if set.
2. orchestrator.readyLabel from the config snapshot.
3. cs:ready.

AgentDock uses that label for the Queue page and when Create issue queues a new issue. The orchestrator itself reads only the file. If you set an override that differs from readyLabel, AgentDock's queue and the orchestrator's queue will disagree, so prefer changing the file.

The same applies to Base branch override: it changes what AgentDock shows, while the orchestrator follows base in the file. When no override is set, AgentDock resolves the base from orchestrator.base, then origin/HEAD, then gh repo view, then main.

Environment for dispatch

A few environment variables in the orchestrator's session affect how workers start:

Next steps