settings

Files (1)

• SKILL.md

SKILL.md (first lines)

# better-tasks settings
Every setting of the better-tasks plugin, one row each. Generated by `bun scripts/settings-doc.ts` from hooks/settings.ts and plugin.json: don't edit by hand.
Grep a key (`gitFlow`) or a word (`video`) to find its row.

## Where a value lives
- **Per user, every project:** Claude Code's `/config` (rows "Better Tasks: …"), or the settings page: `/better-tasks config`, or `c` on the sprint board. It shows the groups below.
- **Per project:** `.claude/tasks/config.json`, one JSON object; keys starting with `//` are comments. Any key below may go there and wins over `/config`. Keys whose "Where" is only config.json live there alone (the settings page writes them there).
- Order: shipped default < `/config` < config.json. A bad key or value is skipped and shown on the settings page.

## How to change one
- The user: `/better-tasks config` (Enter cycles a row's value), or `/config`.
- An agent: set the key in `.claude/tasks/config.json`, keeping the other keys, e.g. `{ "gitFlow": "dev-prs" }`. Confirm the choice with the user first.

## General

| Key | What it means | Choices | Default | Where |
|---|---|---|---|---|
| `editor` | Opens task files from the board. auto: IntelliJ in a JetBrains terminal, VS Code in VS Code, else the default app. | auto, default, code, idea, cursor, zed | "auto" | /config "Editor" or config.json |
| `longCache` | 1-hour prompt cache for teammates and the lead, so a teammate stays cheap to resume. Unless you set a cache TTL yourself. | true, false | true | /config "1-hour prompt cache" or config.json |
| `statusEvery` | Minutes of quiet before the lead checks the open work and moves it forward; only while a task is running (status doing). 0: off. | number | 10 | /config "Status check (minutes)" or config.json |
| `maxTeammates` | Teammates alive at once (working or idle). At the limit a new spawn is refused: the lead gives the task to an owner of similar work (a teammate may own several tasks, done one after another) or waits for one to finish. 0: no limit. | number | 5 | /config "Team size (teammates)" or config.json |
| `keepAwake` | Holds caffeinate (the Mac stays awake) while any teammate runs. | true, false | true | /config "Keep the Mac awake" or config.json |
| `excludeWorktreesFromIde` | IntelliJ skips .claude/worktrees/ from the first run, so teammates' worktrees don't set off re-indexing (git ignores them too: .gitignore). On by default, not asked. | true, false | true | config.json |
| `useBetterTasks` | Use better-tasks in this project at all. false: it stays quiet here (no tools, no task rules, no setup questions; only its commands). Not asked: set it in config.json, then restart. | true, false | true | config.json |
| `shareWithTeam` | Who gets better-tasks in this project. true: it is in the project's shared .claude/settings.json (committed, not pushed), so teammates who open the project see it turned on, install it once, and get the release it pins (source.ref, a release tag; no autoUpdate). A newer release: asked at startup, Yes moves the pin. false: only this user has it. Asked once per git project. | true, false | false | config.json |

## Git & PRs

| Key | What it means | Choices | Default | Where |
|---|---|---|---|---|
| `gitFlow` | How teammates' work reaches main. worktree-prs ("Worktree and PR per task"), the default: each teammate its own git worktree, branch and PR, merged once the user approves it. dev-prs ("Shared dev branch, PR per task"): everyone commits on the dev branch in one checkout, a PR per task. direct ("Straight to main"): small commits on main, no branches, no PRs except a bug fix's (its own worktree and PR). Asked once per project at the first start, with a GitHub remote; without one, no PRs, so direct. | worktree-prs, dev-prs, direct | "worktree-prs" | config.json |
| `worktreeSandbox` | How a teammate's worktree is made (the worktree flows, and a bug fix's own worktree). false, the default: better-tasks makes it with git where Claude Code would (.claude/worktrees/<teammate>, branch worktree-<teammate>, from the same base, .worktreeinclude copied) and spawns the teammate without isolation, so Claude Code's worktree checks don't refuse its commands ("too complex to verify": subshells, variables, heredocs) or the edit of its task file; its rules keep it in its worktree. true: Claude Code's isolated worktree, with those checks, which can't be turned off. Permissions are the user's either way: nothing is allowed that wasn't. | true, false | false | /config "Worktree sandbox" or config.json |
| `devBranch` | The shared branch of the dev-prs git flow. | string | "dev" | config.json |
| `openPrInBrowser` | When the lead asks the user about a finished task, it first opens that task's PR in the default browser (once its video is uploaded) and waits a few seconds for the page to load. Never after the user answered. | true, false | true | /config "Open PRs in the browser" or config.json |
| `prTemplate` | The template every PR description fills in: a path relative to the project root. Empty: the project's own (.github/pull_request_template.md and the other places GitHub and GitLab look), else better-tasks' (the request and why on top, then the video, what changed, how to test, notes, commits). The settings page's "PR template" row opens it, or adds better-tasks' one to the repo as .github/pull_request_template.md. | string | "" | config.json |
| `worktree` | Old switch, kept for projects that set it: with gitFlow direct, each named teammate works in its own worktree. Use gitFlow instead. | true, false | false | /config "Worktree per teammate" or config.json |
| `pullRequests` | Old switch, kept for projects that set it: true reads as gitFlow worktree-prs. Use gitFlow instead. | true, false | false | /config "PR per task" or config.json |

## Testing & videos

| Key | What it means | Choices | Default | Where |
|---|---|---|---|---|
| `demoVideos` | Every finished task comes with a short narrated before/after video (red boxes, arrows, subtitles read aloud by Kokoro, set up once per machine). Asked once per project. | true, false | false | /config "Before/after videos" or config.json |
| `videoQuality` | The videos' size: low = 720p small file, medium = 1080p (a few MB a minute), high = 1080p sharper, bigger file. | low, medium, high | "medium" | /config "Video quality" or config.json |
| `releaseVideos` | A release comes with one narrated video of everything it ships: a card per task, then that task's own before/after video (before: the code before the task, so the previous release for that feature). Linked at the top of the release notes. Made by `bin/release-video.sh` (better-tasks' own `scripts/release.sh` runs it); tasks without a video are listed on the opening card. false: the release goes out without one. Not asked. | true, false | true | config.json |
| `offScreen` | Teammates test and record in a hidden browser, simulator or terminal, so the screen, mouse and keyboard stay the user's. On by default, not asked. | true, false | true | config.json |
| `testScreen` | The screen teammates test and record Mac apps on. virtual: the project's own virtual display, kept below the user's screens. Else a real screen's name as the settings page lists it ("Built-in Retina Display", "DELL U2720Q"); not connected: the virtual display, and the teammate tells the user. Not asked: change it on the settings page's "Test screen" row. | string | "virtual" | config.json |
| `batchDeviceTests` | When builds or device tests are slow, the lead gives each task its own instance (simulator, emulator, app copy, test user) where it can, tested in parallel; where it can't, tasks from areas that don't interact share one build, a change that must be tested on its own or may clash behind its own short-lived feature flag (off by default, a launch argument or env var). Each flag and its old path come out once its task is confirmed working. | true, false | true | /config "Batch device tests" or config.json |
| `liveReview` | While a teammate tests on the test screen (`bin/live-review.sh`), Gemini watches it live and reports, each at its second in the recording, what the teammate asked it to check and anything else not OK; the teammate then reviews those moments, and the reports can go on the before/after video. Sends only the test display's changed frames (masks blacked out, 1280 px wide) to Google's Gemini Live API under the user's own AI Studio key (the `geminiKey` row below). About $0.02 a minute. Not asked. | true, false | false | /config "Live review (Gemini)" or config.json |

## Teammate models

| Key | What it means | Choices | Default | Where |
|---|---|---|---|---|
| `easyModel` | Model for easy tasks (a typo, a text, a small fix). inherit: the lead's own model. | sonnet, opus, fable, haiku, inherit | "opus" | /config "Easy-task model" or config.json |
| `easyEffort` | How hard teammates think on easy tasks. | low, medium, high, xhigh, max | "low" | /config "Easy-task effort" or config.json |
| `normalModel` | Model for normal tasks (an ordinary feature or bug fix). inherit: the lead's own model. | sonnet, opus, fable, haiku, inherit | "opus" | /config "Normal-task model" or config.json |
| `normalEffort` | How hard teammates think on normal tasks. | low, medium, high, xhigh, max | "medium" | /config "Normal-task effort" or config.json |
| `hardModel` | Model for hard tasks (deep debugging, security, changes across several areas). inherit: the lead's own model. | sonnet, opus, fable, haiku, inherit | "opus" | /config "Hard-task model" or config.json |
| `hardEffort` | How hard teammates think on hard tasks. | low, medium, high, xhigh, max | "high" | /config "Hard-task effort" or config.json |
| `escalate` | A teammate that fails or goes in circles is replaced by one a level up: easy to normal, normal to hard. | true, false | true | /config "Escalate when stuck" or config.json |

## Sprint

| Key | What it means | Choices | Default | Where |
|---|---|---|---|---|
| `sprintWeeks` | How many weeks one sprint lasts. | 1, 2, 3, 4 | "1" | /config "Sprint length (weeks)" or config.json |
| `sprintStart` | The weekday a sprint starts. | sunday, monday, tuesday, wednesday, thursday, friday, saturday | "monday" | /config "Sprint starts on" or config.json |

## Task files and paths

| Key | What it means | Choices | Default | Where |
|---|---|---|---|---|
| `taskPrefix` | The id's prefix: "T-" in "T-001". | string | "T-" | config.json |
| `taskPadding` | Digits in the id, zero-padded: 3 gives "001". | number | 3 | config.json |
| `taskStart` | The first task's number. | number | 1 | config.json |
| `taskFileName` | A task's file name; {id}, {slug} and {title} are filled in. | string | "{id}-{slug}.md" | config.json |
| `tasksFolder` | Folder of the task files, from the project root. | string | ".claude/tasks" | config.json |
| `logFile` | The finished-task log, from the project root. | string | "docs/tasks.md" | config.json |
| `sprintsFile` | Sprint goals and reviews, from the project root. | string | ".claude/tasks/sprints.md" | config.json |

## Per user, outside /config
| Key | What it means | Choices | Default | Where |
|---|---|---|---|---|
| `geminiKey` | The key live review sends frames under: a key of an AI Studio project with billing on (Plan "Paid" at aistudio.google.com/apikey), since on the free tier Google may use what is sent to improve its products, and people may review it (the Gemini API terms, "Unpaid Services"). One for every project, or a project's own, which wins. Never in a file. | a key | none | the macOS Keychain, service "better-tasks gemini", account "global" or the project's root; set on the settings page's "Gemini API key" row, or `bin/live-review.sh key set [--project]` |
| `upstreamPr` | After a change to better-tasks itself (made in the user's fork), offer a PR to the better-tasks repo. never: not asked again. | ask, never | "ask" | `<claude config dir>/better-tasks/user.json`; set with the `upstream_pr` tool (answer `ask` undoes never) |

## Project files
Open or create them from the settings page ("This project").
- `.claude/tasks/config.json`: this project's values, above.
- `.claude/better-tasks/<file>`: extends better-tasks' instruction of the same name (lead.md, teammate.md, status-check.md, done.md, testing.md, video.md, pull-request.md, contribute.md); "replace: true" in its front matter replaces it. The shipped ones are in the plugin's .claude/better-tasks/.
- `.claude/tasks/task-template.md`: the body a new task file starts with.

From iosifnicolae2/better-tasks, MIT.

More from iosifnicolae2/better-tasks