Every file here is per-deployment and gitignored; make setup creates them.
Project-specific configuration (gitignored, created by make setup). Keys:
project.name: Project name (e.g.brave-core)project.org: GitHub organization (e.g.brave)project.prRepository: PR repository asowner/repo(e.g.brave/brave-core)project.issueRepository: Issue repository asowner/repo(e.g.brave/brave-browser)project.defaultBranch: Default branch for the PR repo (e.g.master)project.targetRepoPath: Path to the target git repo (relative to the bot dir, to its parent, or absolute — all three resolve)..is the self-hosted case: the target repo is the bot directory, so the loop develops itself. That needs a profile with"worktrees": true, because every cron job's prologue hard-resets the bot directory onto its default branch and would throw away work left in itproject.prdMode:curated(default) —data/prd.jsonis authored and is the source of truth for what the bot works on; a run never rewrites it, and the scheduledscripts/sync-prd.shonly appends stories for newly assigned issues.auto— the PRD is a cache with no manual curation:run.shrebuilds it from assigned issues and open bot PRs before each run, and retires the stories whose PR has been merged since the last one, so a landed PR does not hold a place in the queue that outranks pending work. It also retires a pending story with no PR whose issue has since been closed, which nothing else notices because intake only ever asks GitHub for open issues. Either way the sync is plain Python against the GitHub API (no agent, no tokens)project.profile: Whichprojects/<name>/profile supplies this project's rules — validation steps, test targets, and the project-specific docs the workflows point at. Omitted meansbrave-core(every deployment predating profiles is one); new setups get the profile named after the project when one exists, elsedefault. Leaving it atdefaultwhileprojects/<project.name>/exists is refused:run.shstops and says which line to change, because a profile nobody chose produces wrong work rather than no workproject.useFork:true(default) — the bot pushes branches to its own fork (origin= fork,upstream= PR repo).false— the bot has write access to the PR repo and pushes there directly (origin= PR repo, no fork). Setfalseonly when the bot account is a collaborator on the PR repo;make setupwill then stop expecting a fork and stop offering to create onebot.username: Bot's GitHub usernamebot.email: Bot's email for git commitsbot.sshKeyPath: SSH identity the bot pushes with (null= this machine's default key). See Bot identitybot.signingKeyPath: public key the bot signs commits and tags with (null= the same key it pushes with,bot.sshKeyPath). Signing with any other key — including the machine owner's — makes GitHub mark every bot commit Unverified. The key must also be registered on the bot's GitHub account as a signing key; authentication keys are a separate listbot.ghAccount:ghaccount whose token the bot uses (null= same asbot.username)bot.ghConfigDir: isolatedghconfig directory for the bot (null= use~/.config/gh). Set this to keep the bot's GitHub login out of your personalghconfig entirely — no account is added, switched, or made active outside this repo. Create it withGH_CONFIG_DIR=<dir> gh auth loginreviewer.username: the second GitHub account whose review./run.shwaits for on each pull request it pushes to (null= none, no wait). The reviews are posted by https://github.com/brave-experiments/reviewer. Must not bebot.username. See Review gate and Reviewer accountreviewer.ghConfigDir: the reviewer's ownghconfig directory (nullwith a username set =~/.config/gh-<username>, or under$XDG_CONFIG_HOME).make setupcreates it and walks you through logging inreviewer.maxRounds: how many reviews of one story./run.shwaits for before giving up on it (default5;0turns the wait off). A review that asks for changes starts a fix round and another wait. Has no effect withoutreviewer.username. See Review gatereviewer.waitMinutes: how long./run.shwaits for one review before moving on (default120). The reviewer answers on its own schedule, so this must outlast the review-request poll plus a reviewbot.agent: Which agent./run.shruns,claude(default),codex,cursor, orbravebot.make setupasks.make schedulesreads it when installing, so arun.shcron line carries--agent <name> --agent-bin <absolute path>for anything butclaude; re-run it after changing the agentbot.maxConcurrentRuns: How manyrun.shinstances may share this bot directory (default1). Above 1 requires a profile with"worktrees": true— without per-story worktrees two runs share one working tree and overwrite each other. See Concurrent runsbot.concurrentJobs: How many runs one./run.shstarts in parallel, each on a run slot of its own (default1: one invocation is one run). Cannot exceedbot.maxConcurrentRuns, and does not apply totuimode, which runs one job. See Starting several runs at oncebot.claudeModel: Claude model to use (opus,sonnet, etc.; overridden by./run.sh --modelfor Claude runs)bot.claudeBin: Path to theclaudebinary (null= found on PATH)bot.codexModel: Codex model to use (null= Codex default; overridden by./run.sh --modelfor Codex runs)bot.codexBin: Path to thecodexbinary (null= found on PATH)bot.cursorModel: Cursor model to use (null= account default; overridden by./run.sh --modelfor Cursor runs)bot.cursorBin: Path to thecursor-agentbinary (null= found on PATH)bot.bravebotModel: model for--agent bravebot(null= the agent's own choice; overridden by./run.sh --model).bot.bravebotBin: absolute path of the binary for--agent bravebot.make setupstores it, because that binary is a#!/usr/bin/env nodescript that usually lives under nvm, which cron's PATH does not have (null= found on PATH;./run.sh --agent-binoverrides it for one run).make schedulesalso puts its directory on the cron block'sPATHso the shebang findsnodelabels.*: legacy. Labels now live in the project profile (projects/<name>/profile.json);labels.disabledTestLabelandlabels.inProgressLabelare still honoured as fallbacks for deployments that set them by hand. See Project profileslabels.inProgressLabel: label marking an issue as being worked, so deployments on other machines skip it (""= off, the profile'slabels.inProgresswins where it defines one). See Concurrent runsbestPractices.docsDir: Path to the docs directory containing best practices (relative to bot dir)
A config.example.json template is included, plus a reference config per shipped
deployment: config.brave-core.json and config.brave-dev-loop.json (this repo
developing itself). Copy one over config.json to skip the wizard.
Product Requirements Document defining user stories and acceptance criteria.
stories[].id: Unique story identifierstories[].priority: Execution order (1 = highest), and the last tiebreak once the triage axes have been readstories[].triage: The issue's triage axes,{"importance": 1-5, "urgency": 1-5, "size": 1-5}, with any axis nobody has judged left out. Read off the issue's labels by the backlog sync and used to order pending work — see Backlog order. Absent on every story in a project whose profile defines nolabels.axesstories[].status: Story statestories[].branchName: Git branch name (set when work starts)stories[].prNumber: PR number (set when PR created)stories[].prUrl: PR URL (set when PR created)stories[].lastActivityBy: Who acted last —"bot"|"reviewer"|nullstories[].acceptanceCriteria: Test commands that must pass
Log of completed iterations:
- Codebase Patterns section (reusable patterns discovered during development)
- Per-iteration entries with status transitions, files changed, test results
- Learnings for future iterations
Agent instructions defining workflow, testing requirements, git operations, security guidelines, and quality standards.
data/run-state.json controls per-run behavior. With several run slots, the settings below are still read from this one file and copied into each slot's data/run-state.slot-N.json at run start; the iteration state (runId, storiesCheckedThisRun, ...) is per slot. See Concurrent runs.
| Field | Description |
|---|---|
runId |
Timestamp when this run started (auto-set) |
storiesCheckedThisRun |
Story IDs already processed in this run |
skipPushedTasks |
Skip all "pushed" PRs, only work on new development |
lastIterationHadStateChange |
Tracks if work was done last iteration |
When the branch changes between runs, previous state is automatically archived:
archive/
└── 2026-01-30-old-branch/
├── data/prd.json
└── data/progress.txt
Finished stories are archived too, but only where project.prdMode is auto.
There, prd.json is a cache rebuilt from GitHub at the start of every run, so a
merged or invalid story left in it is only something for the selector to
filter and a reader to scroll past: run.sh moves it to prd.archived.json
before any work is selected. The syncs read that file as well, so nothing that
moves there is ever re-added as fresh work. A curated PRD is the operator's
own list and is archived on the operator's say-so — make archive-prd.
Where the profile sets "worktrees": true, each story gets its own
../<repo>-<issue> checkout, and each of those grows a build directory that can
reach several gigabytes. run.sh collects them itself, so the disk does not fill
with the build output of work that has already landed:
- at the end of a session, every worktree nothing is using
- at the start of the next one, the same but only those idle over 24 hours, since another run may be mid-iteration in one it used minutes ago
scripts/clean-worktrees.py decides, and keeps anything that would lose work:
uncommitted changes, a detached worktree whose commits no ref keeps, a worktree a
live run claims, or one git has locked. Commits on a branch are none of those —
the branch is the repository's, so it outlives the worktree and the report names
it as the worktree goes. Idleness is measured from the last git command run in the
worktree, not from when it was added — a long-lived story's worktree is days old
and still in use. --dry-run reports without removing. A story whose worktree
was collected re-creates it from origin/<branch> on its next iteration, or from
the local branch where nothing was pushed.
To empty the directory by hand rather than wait for a run to collect:
make unmount-worktrees # every worktree idle for over 24 hours
make unmount-worktrees ALL=1 # every worktree, whatever it holds
make unmount-worktrees DRY_RUN=1 # report onlyALL=1 is the one that ignores the guards above, and uncommitted changes are all
it can lose — it names each worktree holding some as it removes it. Branches
belong to the repository rather than to the worktree checked out on them, so
commits no remote has survive, and git checkout <branch> in the main checkout
still finds them. A worktree a live run claims, or one git has locked, is kept
either way: deleting the directory under a running session breaks it. No model is
involved in any of the three.