Runtime configuration

How Kanban stores and manages your project settings, startup flags, and port options.

Kanban keeps two separate config files: a global config stored in your home directory and a per-project config stored inside the git repo. All settings you change in the Settings panel are persisted automatically — there is nothing to manually save or reload.

Cline provider settings — API keys, OAuth login, model selection, and reasoning options — are managed by the Cline SDK separately. They are not stored in Kanban’s own config files. See Agent configuration for details.

Config file locations

Kanban writes two JSON files:

Scope	Path	What it stores
Global	~/.cline/kanban/config.json	Selected agent, autonomous mode, review notifications, prompt templates
Project	<repo>/.cline/kanban/config.json	Script shortcuts for that repo

The project config file is created the first time you save a script shortcut for that repo. If you remove all shortcuts, Kanban deletes the file automatically.

Settings panel options

Open Settings from the navbar to configure the following:

Default agent

Choose which CLI agent Kanban uses for every new task card. The dropdown shows only agents that are currently installed and detected on your PATH. On first launch with no saved config, Kanban auto-selects the best available agent in priority order: claude first, then codex. If neither is installed, it defaults to cline.

You can still override the agent on a per-task basis from the task form.

Auto-review behavior

Control what happens when you click Commit or Open PR on a completed card:

• Auto-commit — Kanban immediately sends the commit prompt to the agent without waiting for your manual review.
• Auto-PR — Same behavior for pull requests.

With both disabled (the default), you review the diff first and confirm before the agent acts.

Review notifications

When enabled, Kanban notifies you when a task card moves to the Review column (meaning the agent has finished its work). This setting is on by default.

Prompt templates

Kanban sends a prompt to the agent when you trigger Commit or Open PR. You can customize both templates in Settings to match your team’s conventions.

The templates support a {{base_ref}} placeholder, which Kanban replaces with the task’s target branch at runtime. If you clear a template, Kanban reverts to the built-in default.

The default commit template instructs the agent to cherry-pick the task commit onto the base branch and handle stash conflicts automatically. The default PR template creates a branch, pushes it, and opens a PR using the gh CLI.

Script shortcuts

Named shell commands that appear as play buttons in the navbar. See Script shortcuts for the full reference.

CLI flags

Pass these flags when starting Kanban from the command line.

--host <ip>

The IP address Kanban binds to. Defaults to 127.0.0.1. Set this when you need Kanban reachable from another network interface, such as inside a container or a remote dev environment.

kanban --host 0.0.0.0

--port <number|auto>

The port Kanban listens on. Defaults to 3484.

Fixed port

Pass a number from 1–65535 to bind to that exact port. If the port is already in use, Kanban checks whether an existing instance is running at that address and opens it instead of failing.

kanban --port 4000

Auto mode

Pass auto and Kanban scans upward from port 3484 to find the first available port. This is useful when you run multiple Kanban instances simultaneously.

kanban --port auto

--no-open

Prevent Kanban from opening a browser tab automatically on startup.

kanban --no-open

--skip-shutdown-cleanup

By default, when you stop Kanban with Ctrl+C, it moves active sessions to trash and removes task worktrees. Pass this flag to skip that cleanup.

kanban --skip-shutdown-cleanup

This is useful when you need to keep worktrees and session state intact across restarts — for example, in a long-running dev environment where you frequently restart the server without wanting to lose in-progress work.

With --skip-shutdown-cleanup, worktrees accumulate on disk over time. Clean them up manually from the Kanban UI or with git worktree remove.