Getting started

Requirements

• Bun 1.3 or newer.
• gh logged in, with the project scope.
• claude or codex logged in with a subscription. See Providers.
• A GitHub repository you can push to.

Add the project scope to your gh token:

gh auth refresh -s project

Install

Run it without installing:

bunx kanbot <command>

Or install it globally:

bun add -g kanbot

Set up a repository

cd your-repo
kanbot init --provider claude   # or codex

init adds:

Path	What
.kanbot/config.yml	Config. See Configuration.
.kanbot/agents/*.md	Agent definitions. See Agents.
.agents/skills/	Shared skills. See Skills.
.claude/, .codex/	Generated from .kanbot/agents. Don't edit.
AGENTS.md, CLAUDE.md	Rules every agent follows.
.github/ISSUE_TEMPLATE/	User story and technical issue templates.
.github/workflows/ci.yml	CI. Agents fix failing CI, so adjust it to your stack.
.github/workflows/kanbot-merged.yml	Closes sibling PRs when one exploratory PR is merged.
.github/CODEOWNERS	You, as owner.

Existing files are kept. Pass --force to overwrite them.

Fill in project conventions

Edit .agents/skills/project-conventions/SKILL.md. Add your stack, commands and conventions. Every agent reads it first, so wrong commands here cause wrong work everywhere.

Also review AGENTS.md and .github/workflows/ci.yml.

Create the board

kanbot board create

This creates a GitHub Project with the six columns and adds the labels. To use an existing project instead:

kanbot board link --owner <login> --number <n>

Then enable these built-in workflows in the project (Project → ⋯ → Workflows). They can't be set through the API:

• Item closed → Status: Done
• Pull request merged → Status: Done
• Auto-add to project → filter is:issue repo:<owner>/<repo>
• Item added to project → Status: Ideas

Commit and push

Agents work in worktrees made from the base branch, so the kanbot files must be pushed:

git add -A && git commit -m "chore: add kanbot" && git push

Check and run

kanbot doctor                # checks auth, board, labels and generated files
kanbot run --once --dry-run  # shows what it would do
kanbot run                   # starts the daemon

Run one daemon per repo. Next, read the development flow.

Shell completion

echo 'source <(kanbot completion)' >> ~/.zshrc     # or ~/.bashrc
kanbot completion --shell fish > ~/.config/fish/completions/kanbot.fish

For zsh, compinit must run first.