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

Prefer a guided setup? Run bunx kanbot skills install, then ask your agent "help me set up kanbot in this repo". The kanbot-guide skill walks you through the steps below and helps you choose options.

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

In a terminal, init asks which of your skills to use for verifying, reviewing and previewing changes. Press Enter to skip. See Capabilities.

init adds, among others:

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/workflows/ci.yml	CI. Agents fix failing CI, so adjust it.

Existing files are kept. Where kanbot's version differs, it is written next to yours as <file>.kanbot-new. Pass --force to overwrite them. kanbot init lists the rest.

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. To have kanbot talk as its own bot, so you can approve its PRs, see Identity and merging.

Shell completion

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

For zsh, compinit must run first.