docs/configuration.md

Configuration

Reference for `.roark/config.json`, precedence, supported keys, defaults, and examples.

Last updated 2026-07-13T00:00:00Z

Edit on GitHub View Markdown

#Precedence

For most options, Roark uses this order:

CLI flag
.roark/config.json
inferred value or built-in default

CLI-only values such as model and thinking are intentionally not supported in config v1.

Unknown keys fail fast so misspellings do not silently change behavior.

#Generated Config

Run:

roark init

roark init writes:

.roark/config.json
.roark/.gitignore

It infers:

repo from Git remote when possible
a verification command from common package metadata or Makefile
package-manager install hooks when a known lockfile is present

workspace.copyToWorktree is not emitted by default. Add it manually only when the repository needs ignored local files copied into managed workspaces.

#Example

{
  "repo": "owner/repo",
  "baseBranch": "main",
  "verify": "bun run check",
  "readyLabel": "ready-for-agent",
  "inProgressLabel": "agent-in-progress",
  "successLabel": "agent-pr-opened",
  "failureLabel": "agent-failed",
  "skipLabels": [
    "needs-triage",
    "blocked",
    "needs-human",
    "triage-rejected",
    "wont-fix",
    "agent-in-progress",
    "agent-failed",
    "agent-pr-opened"
  ],
  "maxFixPasses": 3,
  "workspace": {
    "root": "~/.roark/workspaces",
    "strategy": "clone",
    "cloneRemote": "origin",
    "clone": {
      "filter": "blob:none",
      "depth": null
    },
    "copyToWorktree": [".secrets/env"]
  },
  "hooks": {
    "beforeRun": "bun install --frozen-lockfile",
    "beforeVerify": "bun install --frozen-lockfile",
    "timeoutMs": 600000
  },
  "sandbox": { "provider": "host" },
  "notifications": { "onExit": true }
}

#Top-Level Keys

Key	Type	Default	CLI equivalent	Notes
`repo`	string	inferred when possible	`--repo`	GitHub repository as `owner/repo`.
`baseBranch`	string	`main`	`--base-branch`	Base branch for issue branches and PRs.
`verify`	string	inferred for some repos	`--verify`	Shell command run by the verification gate through `sh -c`.
`readyLabel`	string	`ready-for-agent`	`--label`	Label that opts an issue into autorun eligibility.
`inProgressLabel`	string	`agent-in-progress`	`--in-progress-label`	Label applied when Roark claims an issue.
`successLabel`	string	`agent-pr-opened`	`--success-label`	Label applied after PR creation.
`failureLabel`	string	`agent-failed`	`--failure-label`	Label applied when readiness or verification fails.
`skipLabels`	string[]	default skip set	`--skip-label`, `--skip-labels`	Labels that prevent autorun selection.
`maxFixPasses`	number	`3`	`--max-fix-passes`	Maximum shared fix/review cycles, including review-driven fixes and verification repair.
`workspace`	object	clone strategy defaults	none	Managed workspace configuration.
`hooks`	object	no commands, default timeout	none	Lifecycle hook configuration.
`sandbox`	object	`{ "provider": "host" }`	none	Currently host execution only.
`notifications`	object	exit notifications disabled	none	Opt-in macOS exit notification configuration.

#Exit Notifications

Set notifications.onExit to true to request one silent macOS system notification when a Roark invocation finishes successfully or with a caught top-level error:

{
  "notifications": {
    "onExit": true
  }
}

notifications.onExit defaults to false and must be a boolean when set. Unknown keys under notifications fail validation. The opt-in applies to every command, including quick commands such as status and workspace operations, with no minimum duration.

Delivery uses the system-provided /usr/bin/osascript and is macOS-only and best-effort. Non-macOS hosts silently do nothing. Notifications contain only the command, normalized issue or PR number when available, and repository directory name; they do not include raw errors or arbitrary arguments. Roark waits at most two seconds for delivery. A launch failure, timeout, or nonzero notifier exit writes one warning but does not change the command's result.

Roark can use this opt-in only after locating and parsing a valid repository .roark/config.json. It does not notify outside a Git repository, without config, or when config is invalid. Abrupt termination—including SIGINT, SIGTERM, SIGKILL, runtime crashes, and power loss—is not covered.

#Workspace Keys

Key	Type	Default	Notes
`root`	string	`~/.roark/workspaces`	Parent directory for managed clone workspaces.
`strategy`	string	`clone`	Managed workspace strategy.
`cloneRemote`	string	`origin`	Remote used for clone and fetch behavior.
`clone.filter`	string or null	`blob:none`	Partial clone filter.
`clone.depth`	number or null	`null`	Clone depth. `null` means full history.
`copyToWorktree`	string[]	`[]`	Ignored local paths copied from the control checkout into managed workspaces, including PR review and revision workspaces.

Use copyToWorktree for path names only, not secret values:

{
  "workspace": {
    "copyToWorktree": [".secrets/env"]
  }
}

See Managed workspaces.

#Hook Keys

Key	Type	Failure behavior	Notes
`afterCreate`	string	fails run	Runs after a new workspace is cloned and checked out.
`beforeRun`	string	fails run	Runs before agent workflow execution.
`beforeVerify`	string	fails run	Runs immediately before verification.
`afterRun`	string	warning	Runs after workflow completion.
`beforeRemove`	string	warning	Runs before workspace removal.
`timeoutMs`	number	n/a	Hook timeout. Defaults to `600000`.

Hooks must be non-interactive. See Lifecycle hooks. When roark init detects a supported package-manager lockfile, it assigns the inferred install command to beforeRun and beforeVerify. It does not also assign it to afterCreate, because a newly created workspace proceeds directly to beforeRun without changing dependency inputs.

#Label Configuration

Roark always appends configured lifecycle labels plus required workflow states such as needs-triage, blocked, needs-human, triage-rejected, and wont-fix to the effective skip set. This prevents issues in non-ready states from being selected again.

Read Label semantics before changing label names on a live repository.

#Verification Configuration

For auto and continue, Roark requires a verification command. It uses CLI flag, config, then inference. Failed verification consumes the same maxFixPasses budget as reviewer-requested fixes.

review-pr and revise-pr use CLI --verify, then the configured verify command, then bun run typecheck. Both use the configured managed workspace and lifecycle hooks. The verification command runs against the PR checkout, so invoke these commands only for PR code you trust to execute in that environment.

Good examples:

{ "verify": "bun run check" }

{ "verify": "make test" }

See Verification.

#Next Steps

Use Quickstart to validate a new config.
Use Operations runbook before scheduling.
Use Troubleshooting for common config failures.