Configuration reference

.claudrunner/config.yml, written by init and safe to edit by hand.

version: 1

project:
  name: acme-api
  base_branch: main          # what pull requests target; never pushed to directly
  host: github               # github | gitlab | bitbucket | azure-repos
  code_dir: .                # for a monorepo, the directory this crew owns

stack:
  pack: node                 # or python, dotnet, java, go, php, rust, generic
  commands:
    test: "npm test"
    test_filter: "npm test -- {filter}"
    lint: "npm run lint"
    format: "npm run format"
    build: "npm run build"
    setup: ""                # optional: prepares a bare checkout (dependencies, a database)
    setup_parts: []          # optional: parts the setup can install alone, e.g. [backend, frontend]

verify:
  mode: auto                 # auto | here | ci — how the crew tests its changes

schedule:
  runs_on: routine           # routine | github-actions | cron | systemd | manual
  commit_files: true         # false: local only — every claudrunner file stays out of git
  routines:                  # written by init: the routines it created, so it updates them later
    triage: ""
    sweep: ""

executor:
  mode: direct               # direct | container
  container:                 # only read when mode is container
    compose_file: docker-compose.test.yml
    service: test

board:
  adapter: github-issues     # or trello, jira, linear, none
  via: api                   # api: shell adapters + credentials | connector: the claude.ai connector
  connector:
    board: ""                # connector only: the board's URL
  queues:
    ready: "claudrunner:ready"
    claimed: "claudrunner:running"
    review: "claudrunner:in-review"
    parked: "claudrunner:needs-input"
    filed: "claudrunner:finding"
    done: ""                 # optional: with policy.merge auto, merged items move here

  # Adapter-specific settings. Only the keys your adapter needs.
  #   trello        settings.lists.<role> (list ids), settings.claim_label_id
  #   linear        settings.states.<role> (workflow state ids)
  #   jira          settings.project or settings.jql, settings.transitions.<role>
  #   azure-boards  settings.organization, settings.project, settings.area_path
  #   gitlab-issues settings.project (path or id)
  #   shortcut      settings.states.<role> (workflow state ids)
  #   asana         settings.sections.<role> (section gids)
  #   clickup       settings.list_id
  #   monday        settings.board_id, settings.status_column (the column id)
  #   notion        settings.database_id, settings.status_property
  settings: {}

loops:
  fast:
    enabled: true
    every: 10m
    max_items: 3
  slow:
    enabled: true
    schedule: nightly        # nightly | weekly
    scopes: [correctness, security, scale, tests]
    max_new_cards: 15

policy:
  autonomy: pr-only          # suggest | pr-only | push
  push_branch: null          # required only when autonomy is push
  merge: review              # review: a person merges | auto: the host merges when CI passes
  hold_paths: []             # merge auto: file patterns that always wait for a person
  allow_new_dependencies: false
  max_changed_lines: 600
  edit_ci: false             # may the crew change workflow files

limits:
  run_timeout_minutes: 55
  max_turns: 150

authorship:
  author: user               # user: commits and pull requests are yours | claudrunner: signed by claudrunner
  name: ""                   # user, on a machine with no git identity (CI): your git name
  email: ""                  #   and email

review:
  second_vendor:
    enabled: false
    command: null            # a read-only CLI from another model vendor

dashboard:
  where: local               # local | branch | github-pages | server | none
  domain: ""                 # github-pages: your own domain, e.g. crew.example.com
  show_titles: true          # github-pages defaults to false: public pages show task numbers only
  branch: claudrunner-status # github-pages: the branch Pages serves
  server:
    webroot: ""              # server, same machine: the folder your web server serves
    ssh_target: ""           # server, from CI: user@host:/path/ — key in CLAUDRUNNER_DASHBOARD_SSH_KEY

Fields worth thinking about

base_branch — not necessarily the repository’s default branch. Many projects integrate on a branch that is not what GitHub shows as default. Set it explicitly; the crew never resolves it from HEAD.

project.host — where the branch is pushed and the change proposed. Independent of your board: code on GitHub with work items in Jira is a normal combination.

schedule.runs_on — routine runs in Anthropic’s cloud on your Claude subscription: no API key, no server, no CI minutes, and the shortest interval is one hour. init creates the routines and installs the crew into the repository’s .claude/, because a routine cannot install plugins. github-actions needs an ANTHROPIC_API_KEY secret and is billed by the API.

schedule.commit_files — on your own computer (manual, or cron on this machine) the installed plugin gives the crew everything, so init can keep all of .claudrunner/ in .gitignore and your repository does not change. A routine, GitHub Actions or a server starts from a fresh copy of the repository and only sees what is pushed, so there the crew’s files are committed. A routine or GitHub Actions with commit_files: false fails validation.

authorship.author — whose name is on the crew’s work. user: every commit and pull request is yours, under your own git identity. claudrunner: commits are authored by claudrunner, so your history shows which work the crew did. In both cases Claude, Anthropic and other AI models are never named as author or co-author, and init turns off the tool’s own attribution lines.

policy.merge — who merges the crew’s pull requests. review (the default): a person reads and merges each one. auto: the host merges a pull request once CI passes on its last commit. The crew itself never runs a merge. On GitHub, init installs .github/workflows/claudrunner-automerge.yml, which merges only claudrunner/ pull requests and skips one that has the claudrunner:hold label, changes a workflow, matches policy.hold_paths, or conflicts. GitLab uses merge-when-pipeline-succeeds and Azure Repos auto-complete; Bitbucket is not supported. With auto, CI is the only gate before the base branch: choose it for a project without users, or a base branch that deploys to a test environment. Set review to stop every automatic merge at once.

board.via — connector lets the agent use the board’s claude.ai connector: the natural choice in a routine, with no keys to store. The trade-off is stated plainly: with api the shell holds the board credential and the agent never sees it; with connector the agent itself can reach the board. It is still told to touch only the cards it claimed.

verify.mode — auto lets the crew decide per change: no setup for text and docs, and only the changed part of the project for code. here always tests before the pull request. ci never installs anything and leaves the tests to your CI. Setup happens at the last moment, when the crew knows what it changed — never at the start of a run.

stack.commands.setup — a routine starts from a bare checkout every time. Put what the tests need (installing dependencies, starting a database) in one script and point this at it. A run fetches and claims its work before setup, so an empty queue costs seconds. When the script accepts a part name — setup.sh backend — list the parts in stack.commands.setup_parts and a run installs only what its work touches.

executor.mode — direct is correct on a CI runner, which is already disposable. Choose container when runs happen on a machine you care about.

policy.max_changed_lines — the real quality control. A large unattended diff does not get reviewed properly by anyone, including you.

review.second_vendor — a reviewer from a different model vendor, read-only, on the same diff. Two vendors disagreeing is a much stronger signal than one model checking itself.

dashboard.where — where the status page lives. local is opened with /claudrunner:dashboard. branch publishes the status to a claudrunner-status branch and /claudrunner:dashboard shows it live — the way to watch a routine or CI on a private repository. github-pages publishes the same branch as a public site. server copies the page into a folder, or uploads it over SSH from CI. See the hosting guide in the plugin’s templates/hosting/.

dashboard.show_titles — on a public page, titles often name customers, bugs and security issues. GitHub Pages therefore shows task numbers unless you turn titles on.

Credentials, by adapter

Never in this file. The orchestrator reads them from the environment, and the agent never sees them.

Adapter	Environment
github-issues	GH_TOKEN
gitlab-issues	GITLAB_TOKEN, plus GITLAB_HOST when self-managed
jira	JIRA_BASE_URL, JIRA_EMAIL, JIRA_API_TOKEN
linear	LINEAR_API_KEY
azure-boards	AZURE_DEVOPS_EXT_PAT
trello	TRELLO_API_KEY, TRELLO_TOKEN
shortcut	SHORTCUT_API_TOKEN
asana	ASANA_TOKEN
clickup	CLICKUP_TOKEN
monday	MONDAY_TOKEN
notion	NOTION_TOKEN

Two files that are not config

.claudrunner/profile.md — the project profile. init reads the code once and writes down the stack, where things live, how code is written here, how to test a change and what must not break. Every run starts from it instead of surveying the repository again, which saves minutes and tokens on every run. Keep it under 4 KB and true; re-run init when it drifts.

.claudrunner/gotchas.md — failure modes that have already happened here. Every review reads it first. This file is how the crew becomes specifically good at your codebase.

claude plugin marketplace add samiraklf/claudrunner &&
  claude plugin install claudrunner@claudrunner