# Auto Build configuration reference

> AutoRouterConfig fields (planModel, buildModel, verifyModel, refineModel, categories, costAware), MetaHarnessPolicy options, and npm verify:auto-router:* regression scripts.

- Repository: Parcha-ai/build
- GitHub: https://github.com/Parcha-ai/build
- Human docs: https://grok-wiki.com/public/docs/parcha-ai-build-bea5702b371b
- Complete Markdown: https://grok-wiki.com/public/docs/parcha-ai-build-bea5702b371b/llms-full.txt

## Source Files

- `src/shared/types/index.ts`
- `src/main/services/auto-router.service.ts`
- `src/main/services/flue-meta-router.service.ts`
- `package.json`
- `scripts/verify-auto-router-meta-harness.ts`
- `scripts/verify-auto-router-goal-orchestration.ts`

---

---
title: "Auto Build configuration reference"
description: "AutoRouterConfig fields (planModel, buildModel, verifyModel, refineModel, categories, costAware), MetaHarnessPolicy options, and npm verify:auto-router:* regression scripts."
---

`autoRouterConfig` lives under `settings` in the `claudette-settings` electron-store. The main-process `autoRouterService` merges saved values with `DEFAULT_CONFIG`, applies tier and custom-category policies, and feeds routing when the session model picker is set to `auto`. Settings are edited in **Settings → Auto Build** and persisted through `autoBuildConfigFromState` in the renderer.

## Where configuration is stored

| Layer | Location | Behavior |
| --- | --- | --- |
| Persistence | `claudette-settings` → `settings.autoRouterConfig` | Survives restarts; merged with code defaults on read |
| UI | Settings dialog, **Auto Build** tab | Writes tier models, policies, custom categories, `costAware` |
| Runtime API | `autoRouterService.getConfig()` / `setConfig(partial)` | Main process; `setConfig` shallow-merges into current effective config |

Auto Build runs when `selectedModel === 'auto'` in `claude.service` (for example after `/goal`, which forces `auto`). The `AutoRouterConfig.enabled` field exists on the type and in `DEFAULT_CONFIG` (`true`), but `auto-router.service` does not gate routing on it today.

## Tier model defaults

`DEFAULT_CONFIG` in `auto-router.service` supplies runtime defaults when fields are missing:

| Field | Default |
| --- | --- |
| `planModel` | `claude-sonnet-4-6` |
| `buildModel` | `codex:gpt-5.5` |
| `verifyModel` | `codex:gpt-5.5` |
| `refineModel` | `cursor:composer-2.5` |
| `fallbackModel` | `claude-sonnet-4-6` |
| `costAware` | `true` |
| `costThresholdPercent` | `80` |

The Settings UI uses the same tier model defaults via `AUTO_BUILD_MODEL_DEFAULTS` (`plan`, `build`, `verify`, `refine`, `fallback`).

### Model string format

Model IDs use an optional harness prefix; bare `claude-*` IDs map to the Claude harness:

| Prefix | Harness |
| --- | --- |
| `codex:` | `codex` |
| `cursor:` | `cursor` |
| `gemini:` | `gemini` |
| `opencode:` | `opencode` |
| `custom:` | `custom` (requires matching `customModels` entry with API key and base URL) |
| (none, `claude-*`) | `claude` |

## AutoRouterConfig field reference

### Tier models (required strings)

<ParamField body="planModel" type="string" required>
Planning tier: architecture, reviews, tradeoffs, risk analysis.
</ParamField>

<ParamField body="buildModel" type="string" required>
Execution tier: implementation, scaffolding, integration.
</ParamField>

<ParamField body="verifyModel" type="string" required>
Verification tier: tests, QA, debugging, root-cause work.
</ParamField>

<ParamField body="refineModel" type="string" required>
Refinement tier: small UI/copy/style edits.
</ParamField>

<ParamField body="fallbackModel" type="string" required>
Used when preferred harness/model is unavailable or on cooldown.
</ParamField>

`getConfig()` also accepts legacy `categories` entries whose `id` is `plan`, `build`, `verify`, `refine`, or `fallback` and copies their `model` into the corresponding `*Model` field.

### Per-tier MetaHarnessPolicy fields

Each tier supports optional policy fields (`plan*`, `build*`, `verify*`, `refine*`, `fallback*`):

| Suffix | Type | UI / runtime notes |
| --- | --- | --- |
| `Effort` | `string` | UI: `''` (default), `low`, `medium`, `high`, `xhigh`, `max`. Normalized for Claude/Codex in `harness-policy.service` |
| `Speed` | `MetaHarnessSpeed` | `auto` \| `standard` \| `fast`; non-`auto` values are persisted |
| `Workflow` | `MetaWorkflowMode` | `auto` \| `single` \| `lead-with-delegates` \| `sequential` \| `dynamic` |
| `BudgetUsd` | `number` | Non-negative USD cap; emitted in mission-control preamble |
| `Verification` | `MetaVerificationMode` | `auto` \| `none` \| `optional` \| `required` |

`cleanPolicy()` strips `auto` speed/workflow/verification so they do not affect routing output. Tier policy is merged with any matched custom category via `resolveRoutePolicy()`.

### Categories

<ParamField body="categories" type="AutoRouterCategoryConfig[]">
Optional array of category overrides. Fixed tier IDs (`plan`, `build`, `verify`, `refine`, `fallback`) migrate to `*Model` fields. Custom categories (non-fixed `id`, or `custom-{timestamp}` IDs) participate in keyword/domain matching and Flue controller input when credentials exist.
</ParamField>

`AutoRouterCategoryConfig` extends `MetaHarnessPolicy` with:

| Field | Purpose |
| --- | --- |
| `id` | Unique key; fixed tier IDs are legacy aliases for `*Model` |
| `label`, `description` | Display and tier inference |
| `model` | Harness-prefixed model string |
| `tier` | Explicit `TaskTier` or `fallback` |
| `keywords` | Comma-separated or array; used for message matching |
| `domains` | Optional `TaskDomain[]` filter |

Custom categories are included in `config.categories` only when `isCurrentCustomAutoRouterCategory()` is true (has tier, description, keywords, or `custom-\d{10,}` id).

### Cost controls

<ParamField body="costAware" type="boolean" required>
When `true`, plan-tier routing downgrades `claude-opus*` to `claude-sonnet-4-6` unless the user explicitly set `planModel` (via `planModel` or `categories` id `plan`). Also affects candidate ordering in `metaCandidateModelsForTier`.
</ParamField>

<ParamField body="costThresholdPercent" type="number" required>
Default `80`. Loaded from store into `getConfig()` but not referenced elsewhere in `auto-router.service` today.
</ParamField>

<ParamField body="enabled" type="boolean" required>
Present on `AutoRouterConfig` and defaulted to `true`; not read by current routing code.
</ParamField>

## MetaHarnessPolicy

Shared policy shape used by tiers, categories, `OrchestrationStage`, and `RoutingDecision`:

```typescript
interface MetaHarnessPolicy {
  effort?: string;
  speed?: MetaHarnessSpeed;      // 'auto' | 'standard' | 'fast'
  workflow?: MetaWorkflowMode;   // 'auto' | 'single' | 'lead-with-delegates' | 'sequential' | 'dynamic'
  budgetUsd?: number;
  verification?: MetaVerificationMode; // 'auto' | 'none' | 'optional' | 'required'
}
```

### How policy reaches harnesses

`translateHarnessPolicy()` in `harness-policy.service` maps policy to harness-specific SDK options and environment variables (`BUILD_META_EFFORT`, `BUILD_META_SPEED`, `BUILD_META_WORKFLOW`, `BUILD_META_BUDGET_USD`, `BUILD_META_VERIFICATION`). It also builds a `<mission_control_policy>` preamble prepended to prompts (preserving `/goal` lines when present).

Effort aliases from legacy thinking modes are normalized: `off`→`low`, `thinking`→`medium`, `ultrathink`→`high`, `ultracode`→`max`.

### Mission control overlay

`MetaMissionControlPolicy` extends `MetaHarnessPolicy` with controller metadata (`controllerHarness: 'meta'`, `requestedTier`, `leadTier`, `leadHarness`, `leadModel`, optional `categoryId` / `categoryLabel`). This appears on `RoutingDecision.missionControl` when the Flue meta controller or heuristics produce a lead decision.

## Configuration flow

```mermaid
flowchart LR
  subgraph UI["Renderer"]
    SD["SettingsDialog Auto Build tab"]
    ABS["autoBuildConfigFromState"]
  end
  subgraph Store["Persistence"]
    ES["claudette-settings.settings.autoRouterConfig"]
  end
  subgraph Main["Main process"]
    ARS["autoRouterService.getConfig"]
    RT["classifyAndRoute"]
    HPS["harness-policy.service"]
    FLUE["flue-meta-router.service"]
  end
  SD --> ABS --> ES
  ES --> ARS
  ARS --> RT
  RT --> FLUE
  RT --> HPS
```

Flue controller routing requires a Cerebras API key: `settings.cerebrasApiKey`, embedded key, or `CEREBRAS_API_KEY`. Timeout defaults to 9s (`FLUE_META_ROUTER_TIMEOUT_MS` env override).

## Programmatic updates

```typescript
// Main process only
autoRouterService.setConfig({
  planModel: 'claude-opus-4-8',
  costAware: false,
  buildEffort: 'high',
});
```

`setConfig` merges partial updates, writes back to `claudette-settings`, and refreshes a short-lived settings cache (2s TTL).

## Regression scripts (`verify:auto-router:*`)

Scripts are offline TypeScript verifiers run with `npx ts-node` unless noted. They mock `electron-store` and often stub Flue/analytics modules.

### Individual npm scripts

| Script | Command | Focus |
| --- | --- | --- |
| `verify:auto-router:attachments` | `npm run verify:auto-router:attachments` | Attachment-aware routing with tier categories |
| `verify:auto-router:controller-confidence` | `npm run verify:auto-router:controller-confidence` | Controller confidence threshold (`META_MIN_CONFIDENCE` 0.55) |
| `verify:auto-router:flue-auth-cooldown` | `npm run verify:auto-router:flue-auth-cooldown` | Flue auth failure cooldown (10 min) |
| `verify:auto-router:flue-fallback` | `npm run verify:auto-router:flue-fallback` | Heuristic fallback when Flue fails |
| `verify:auto-router:flue-sandbox` | `npm run verify:auto-router:flue-sandbox` | Flue sandbox session wiring |
| `verify:auto-router:flue-timeout` | `npm run verify:auto-router:flue-timeout` | Flue prompt timeout / abort |
| `verify:auto-router:fixed-settings` | `npm run verify:auto-router:fixed-settings` | Legacy `categories` + tier `*Model` merge and custom category policy |
| `verify:auto-router:goal-orchestration` | `npm run verify:auto-router:goal-orchestration` | `/goal`, meta-goal continuations, `GoalOrchestration` types |
| `verify:auto-router:indistinguishable` | `npm run verify:auto-router:indistinguishable` | Streamed output must not expose Auto Build branding |
| `verify:auto-router:meta-harness` | `npm run verify:auto-router:meta-harness` | **Full quality gate** (orchestrates most scripts below) |
| `verify:auto-router:meta-eval` | `npm run verify:auto-router:meta-eval` | Tier/harness eval cases with mocked Flue |
| `verify:auto-router:meta-eval:live` | `npm run verify:auto-router:meta-eval:live` | Same eval with `--live --require-live` (needs Flue runtime + `CEREBRAS_API_KEY`) |
| `verify:auto-router:no-legacy-llm-after-controller` | `npm run verify:auto-router:no-legacy-llm-after-controller` | No direct fetch classifier after controller |
| `verify:auto-router:plan-mode` | `npm run verify:auto-router:plan-mode` | Plan-tier forces lead `plan` permission mode |
| `verify:auto-router:workflow-metadata` | `npm run verify:auto-router:workflow-metadata` | Workflow metadata on assistant messages |

<Note>
`npm run verify:auto-router:meta-harness` runs `scripts/verify-auto-router-meta-harness.ts`, the umbrella quality gate. It sequentially runs meta-eval, indistinguishable, Flue sandbox/timeout/auth/fallback, fixed-settings, goal-orchestration, handoff-context, attachments, plan-mode, harness-policy translation, transcript precedence, focused ESLint on router files, and `git diff --check`.
</Note>

### Recommended verification order

<Steps>
<Step title="Fast config merge check">
Run `npm run verify:auto-router:fixed-settings` after changing `getConfig()` or category migration.
</Step>
<Step title="Goal and permission paths">
Run `npm run verify:auto-router:goal-orchestration` and `npm run verify:auto-router:plan-mode` when touching `/goal` or permission modes.
</Step>
<Step title="Full gate before merge">
Run `npm run verify:auto-router:meta-harness` for the complete Auto Build regression suite.
</Step>
</Steps>

<Warning>
`verify:auto-router:meta-eval:live` calls the real Flue stack. Set `FLUE_RUNTIME_NODE_MODULES` to a directory containing `@flue/runtime` and provide `CEREBRAS_API_KEY` (or `CLAUDETTE_CEREBRAS_API_KEY`).
</Warning>

## Example saved config

```json
{
  "planModel": "claude-sonnet-4-6",
  "buildModel": "codex:gpt-5.5",
  "verifyModel": "codex:gpt-5.5",
  "refineModel": "cursor:composer-2.5",
  "fallbackModel": "claude-sonnet-4-6",
  "buildEffort": "high",
  "buildSpeed": "fast",
  "buildWorkflow": "lead-with-delegates",
  "buildBudgetUsd": 25,
  "buildVerification": "required",
  "costAware": true,
  "categories": [
    {
      "id": "custom-docs",
      "label": "Documentation",
      "model": "claude-sonnet-4-6",
      "tier": "refine",
      "keywords": ["readme", "changelog", "docs"],
      "verification": "optional"
    }
  ]
}
```

## Related pages

<CardGroup>
<Card title="Auto Build routing" href="/auto-build-routing">
Plan/build/verify/refine heuristics, Flue controller, orchestration, and `CLAUDE_AUTO_ROUTE_DECISION` events.
</Card>
<Card title="Settings reference" href="/settings-reference">
Full `AppSettings` and `claudette-settings` keys, including where `autoRouterConfig` fits.
</Card>
<Card title="npm scripts reference" href="/npm-scripts-reference">
All `package.json` scripts and when to use `./scripts/dev.sh` vs `npm run start`.
</Card>
<Card title="Shared types reference" href="/shared-types-reference">
`RoutingDecision`, `OrchestrationPlan`, `TaskTier`, and related interfaces.
</Card>
</CardGroup>