# Configuration

## Config file

`.kanbot/config.yml` is created by `init` and `board create`. All fields except `repo` have defaults. kanbot keeps your comments when it updates the file.

```yaml
# yaml-language-server: $schema=./config.schema.json
provider: claude # claude | codex
repo: owner/name
baseBranch: main
project: { owner: my-org, number: 7 }

columns: # names of the board's Status options
  ideas: Ideas
  planning: Planning
  ready: Ready
  inProgress: In Progress
  review: Review
  done: Done

concurrency: 3 # max agent workers at once
pollSeconds: 60 # min 10
priority: [fix, review, plan, implement] # which waiting jobs run first
maxAttempts: 2 # failures before needs-human

timeoutMinutes:
  plan: 20
  implement: 90
  review: 30
  fix: 45

implementers: # type:<key> label → agent
  frontend: implementer-frontend
  backend: implementer-backend
  docs: implementer-docs
  infra: implementer-technical
  default: implementer-backend

review:
  copilot: false # add GitHub Copilot as a reviewer
  copilotOnPush: false
  copilotWaitMinutes: 15

codex:
  networkAccess: false

notify:
  desktop: true
  webhook: null
```

Restart the daemon after changes.

### Schema

`init` and `sync` write `.kanbot/config.schema.json`, matching your kanbot version. The header line above points editors at it (VS Code needs the YAML extension), giving autocomplete, docs on hover and errors. `doctor` reports a stale schema.

The schema also ships in the package as `schema/config.schema.json`, e.g. `https://unpkg.com/kanbot/schema/config.schema.json`.

### Columns

Rename columns to match your board's Status field. `kanbot doctor` reports missing ones.

### Concurrency and priority

Each exploratory variant counts as one worker. `priority` orders waiting jobs by kind; board order decides within a kind.

### Implementers

Maps a `type:*` label to an agent. Issues without a matching label use `default`. See [Agents](./agents.md#common-changes).

### Review

Adds GitHub Copilot as a third reviewer. See [Copilot review](./copilot-review.md).

## Notifications

kanbot acts as your GitHub account, so GitHub won't notify you about agent work. kanbot notifies you when:

- a PR is ready to test,
- exploratory PRs are ready to compare,
- an agent answered your PR feedback or needs input,
- an implementer is blocked,
- an issue needs a human.

Turn off desktop notifications with `notify.desktop: false`. To get them elsewhere, set a webhook. It receives a JSON `POST` with `title`, `message` and `url`, plus `Title` and `Click` headers, so an [ntfy.sh](https://ntfy.sh) topic URL works as is:

```yaml
notify:
  webhook: https://ntfy.sh/my-secret-topic
```

## Labels

`kanbot board create` adds these labels.

| Label                                 | Set by  | Meaning                                     |
| ------------------------------------- | ------- | ------------------------------------------- |
| `technical`                           | you     | Plan as a technical goal, not a user story. |
| `type:frontend\|backend\|docs\|infra` | planner | Picks the implementer.                      |
| `explore:2..4`                        | you     | Build N approaches as N PRs.                |
| `variant:1..4`                        | kanbot  | Marks which approach a PR is.               |
| `kanbot:working`                      | kanbot  | An agent is working on it.                  |
| `agent-reviewed`                      | kanbot  | Passed agent review. Ready for you.         |
| `needs-human`                         | kanbot  | Agents stopped. Remove it to retry.         |
| `kanbot-review`                       | you     | Agent review for a PR without a card.       |

## Shared agent rules

`AGENTS.md` holds rules every agent follows, in kanbot and in normal sessions. `CLAUDE.md` imports it. Add repo-wide rules here; put commands and conventions in the [`project-conventions` skill](./skills.md#project-conventions).

## Issue and PR templates

`init` adds issue templates in `.github/ISSUE_TEMPLATE/` (user need and technical task) and `.github/pull_request_template.md`. Edit them freely.

## CI

Agents fix failing CI on their PRs, up to 3 times per PR. Adjust `.github/workflows/ci.yml` to run your tests, lint and typecheck.

`.github/workflows/kanbot-merged.yml` closes sibling PRs when one exploratory PR is merged. It runs on GitHub, so it works when the daemon is off.

## Limitations

- Ready-column order is the project's manual item order, not a view's sort.
- Workers run as your user. `gh` and `git push` are blocked by command patterns, not missing credentials.