Config Options

Complete reference for Candid configuration.

Schema

{
  "tone": "harsh" | "constructive",
  "focus": "security" | "performance" | "architecture" | "edge-case",
  "mergeTargetBranches": ["branch1", "branch2"],
  "exclude": ["pattern1", "pattern2"],
  "commit": boolean,
  "decisionRegister": {
    "enabled": boolean,
    "path": "string",
    "mode": "lookup" | "load"
  },
  "ship": {
    "installCommand": "string",
    "buildCommand": "string",
    "testCommand": "string",
    "targetBranch": "string",
    "autoMerge": boolean,
    "additionalPrompt": "string",
    "postMergeCommand": "string",
    "issueTracker": {
      "provider": "linear",
      "enabled": boolean,
      "teamPrefixes": ["string"],
      "state": "string",
      "prompt": "string"
    }
  },
  "fastShip": {
    "review": boolean,
    "install": boolean,
    "build": boolean,
    "tests": boolean,
    "issueTracker": boolean,
    "autoMerge": boolean,
    "postMergeCommand": boolean,
    "targetBranch": "string"
  }
}

Options

tone

Review tone.

focus

Review focus mode.

mergeTargetBranches

Array of branches to compare against. First existing branch is used.

Default: ["main", "stable", "master"]

exclude

Array of glob patterns for files to skip.

Example: ["*.generated.ts", "vendor/*"]

commit

Whether to auto-commit applied fixes.

Default: false

decisionRegister

Configuration for tracking questions and decisions during reviews.

Example:

{
  "decisionRegister": {
    "enabled": true,
    "path": ".candid/register",
    "mode": "lookup"
  }
}

See Decision Register for full documentation.

ship

Configuration for the /candid-ship shipping workflow. All sub-fields are optional; if absent, candid-ship uses defaults or skips the corresponding step.

Example (minimal):

{
  "ship": {
    "targetBranch": "main"
  }
}

Example (full pipeline):

{
  "ship": {
    "installCommand": "pnpm install",
    "buildCommand": "pnpm build",
    "testCommand": "pnpm test",
    "targetBranch": "stable",
    "autoMerge": true,
    "additionalPrompt": "Ensure error handling covers all async operations",
    "postMergeCommand": "curl -X POST https://deploy.example.com/trigger"
  }
}

See Candid Ship for full documentation.

ship.issueTracker

Optional auto-update of an external issue tracker after the PR is created. Currently provider: "linear" is the only supported provider; this field can be safely left unset, in which case the issue-tracker step is skipped silently and the rest of the ship runs unchanged.

Default prompt:

Update issue {issueId}: set its state to "{state}". Update only this one issue and only its state — do not modify any other issues, fields, or properties. If the issue is already in "{state}", report success without action. If the issue is missing or inaccessible, report the error and stop.

This default encodes four safety invariants so a verbose MCP can’t accidentally fan out:

1. Single issue — only {issueId} is touched.
2. Single field — only the state field changes (assignees, labels, priority, etc. are untouched).
3. Idempotent — already in {state}? Succeed without action.
4. No fallback search — missing or inaccessible? Stop. Don’t look for “similar” issues.

candid-init writes this default into .candid/config.json so it’s discoverable and easy to edit. Custom prompts must preserve invariants 1 and 4.

Example:

{
  "ship": {
    "issueTracker": {
      "provider": "linear",
      "enabled": true,
      "teamPrefixes": ["DIS", "ENG"],
      "state": "In Review"
    }
  }
}

Behavior when not configured or disabled:

• issueTracker field absent → step skipped silently
• enabled: false → step skipped silently
• branch name has no matching team prefix → step skipped silently (branches without an issue ID just ship normally)
• provider’s MCP is not installed → warning shown, step skipped, ship continues
• provider is unsupported (anything other than "linear") → warning with link to issue tracker, step skipped, ship continues

See Candid Ship — Issue Tracker Integration for full setup and usage.

fastShip

Configuration for the /candid-fast-ship minimal shipping workflow. All steps are opt-in — nothing runs by default except PR creation. Command values are inherited from the ship block.

Example (install + build check + auto-merge, no review):

{
  "ship": {
    "installCommand": "pnpm install",
    "buildCommand": "pnpm build",
    "targetBranch": "stable"
  },
  "fastShip": {
    "install": true,
    "build": true,
    "autoMerge": true
  }
}

See Candid Fast Ship for full documentation.

Config Precedence

1. CLI flags
2. Project config (.candid/config.json)
3. User config (~/.candid/config.json)
4. Interactive prompt