Repository config

Every key in .korev/settings.toml and korev.json, and the order Korev reads them in.

For a guide with examples, see Configure your repository.

Which file Korev reads

Korev reads the first of these that exists, from the workspace's own checkout:

.korev/settings.toml, with .korev/settings.local.toml merged on top. The local file wins key by key.
korev.json.
.conductor/settings.toml, with .conductor/settings.local.toml merged on top. Same format as .korev/settings.toml.
The scripts and prompts in Settings → Repositories → your repo.

The branch prefix and the files to copy are read from the main checkout, because Korev needs them before the worktree exists.

Full example

file_include_globs = ".env*\nconfig/*.local.json"
spotlight_testing = true

[scripts]
setup = "pnpm install"
archive = "./scripts/archive.sh"
run_mode = "nonconcurrent"
auto_run_after_setup = true

[scripts.run.web]
command = "pnpm dev --port $KOREV_PORT"
options = { cwd = "apps/web" }
default = true

[[preview_urls]]
name = "Web"
url = "http://localhost:$KOREV_PORT"

[environment_variables]
API_URL = "http://localhost:3000"

[prompts]
general = "Use pnpm, never npm."
create_pr = "Follow .github/pull_request_template.md."

[git]
archive_on_merge = true
delete_branch_on_archive = false
branch_prefix_type = "custom"
branch_prefix = "agent"

Top-level keys

Key	Type	Meaning
`file_include_globs`	string	Glob patterns, one per line, for gitignored files to copy into new workspaces. A `.worktreeinclude` file in the repository root replaces it. Without either, Korev uses Files to copy from the app's repository settings, and then `.env*`.
`spotlight_testing`	bool	Shows the Spotlight button in each workspace's Run tab. See Spotlight testing.

`[scripts]`

Key	Type	Meaning
`setup`	string	Runs in each new or restored workspace.
`archive`	string	Runs before Korev removes an archived worktree. Five-minute limit.
`run`	string or table	One run script as a string, or several as `[scripts.run.<id>]` tables.
`run_mode`	string	`"nonconcurrent"`: starting a run script stops the run scripts in your other workspaces of this repository.
`auto_run_after_setup`	bool	Starts the default run script when setup exits with 0.

All scripts run as $SHELL -lc "<command>" in the worktree.

`[scripts.run.<id>]`

Key	Type	Meaning
`command`	string	The command to run.
`args`	array of strings	Arguments, quoted and added after `command`.
`options.cwd`	string	Folder to run in, relative to the worktree.
`icon`	string	Icon in the Run menu. Default `play`.
`default`	bool	Runs when you press ⌘R. Without a default, the first script runs.
`hide`	bool	`true` skips the script.
`available_in`	string or array	Korev skips the script when this is `"cloud"`, or an array without `"local"`.

`[[preview_urls]]`

Key	Type	Meaning
`name`	string	Label in the Run tab's Open menu.
`url`	string	The URL. Korev expands `$KOREV_PORT`, `${KOREV_PORT}` and `$((KOREV_PORT + N))` for N from 0 to 9.

`[environment_variables]`

String values, added to the environment of scripts, terminals and agents. Values in an [environment_variables.local] table are merged on top.

`[prompts]`

Each key adds instructions to one prompt that Korev sends to the agent.

Key	Added to
`general`	Every workspace chat
`code_review`	The Review button
`create_pr`	The Create PR button
`fix_errors`	The Fix errors button
`resolve_merge_conflicts`	The Resolve conflicts button
`rename_branch`	The prompt that names workspaces

`[git]`

Key	Type	Meaning
`archive_on_merge`	bool	Archive the workspace when its pull request merges.
`delete_branch_on_archive`	bool	Delete the branch when you archive the workspace.
`branch_prefix_type`	string	`"custom"` uses `branch_prefix`. `"none"` uses no prefix.
`branch_prefix`	string	The branch prefix, used with `branch_prefix_type = "custom"`.

Each [git] key overrides the matching option in Settings → Git for this repository.

`korev.json`

A simpler format. It supports only these keys:

{
  "scripts": {
    "setup": "npm install",
    "run": "npm run dev -- --port $KOREV_PORT",
    "archive": "./scripts/archive.sh"
  },
  "runScriptMode": "nonconcurrent"
}

For several run scripts, make run an object. Each entry takes the same keys as a [scripts.run.<id>] table:

{
  "scripts": {
    "run": {
      "web": { "command": "pnpm dev", "options": { "cwd": "apps/web" } },
      "api": { "command": "pnpm api", "default": true }
    }
  }
}

Which file Korev readsCopy Anchor Link

Full exampleCopy Anchor Link

Top-level keysCopy Anchor Link

[scripts]Copy Anchor Link

[scripts.run.<id>]Copy Anchor Link

[[preview_urls]]Copy Anchor Link

[environment_variables]Copy Anchor Link

[prompts]Copy Anchor Link

[git]Copy Anchor Link

korev.jsonCopy Anchor Link

On this page