Configuration

kanbo has no configuration file of its own beyond the per-project binding. Everything else is a flag or an environment variable.

Environment variables#

VariableRead byMeaning
KANBO_DATABASE_URLevery board commandConnection string of an external Postgres board. Beats the project's binding, in every shell — an agent's included.
KANBO_DB_PATHevery board command, kanbo initPath of a SQLite board file to open when neither a flag nor the project's binding names one. An app that keeps the board inside its own database sets this for the shells it starts.
KANBO_WORKSPACE_IDevery board commandThe workspace to work on, when --workspace is not given. Beats the binding.
KANBO_ACTOR_IDevery writing command, kanbo mcp, kanbo serveThe name writes are filed under. Defaults to the operating-system user name.
KANBO_ACTOR_KINDevery commandagent marks the shell as an agent's: person-only commands exit 4, no question is asked, column entry rules refuse instead of warning, and a Postgres binding's agentDatabaseUrl is used. person marks it as a person's even when an agent tool's mark is there (see Agent shells kanbo recognises). Unset, the marks decide.
KANBO_SERVE_TOKENkanbo serveBearer token the HTTP server requires (same as --token, but not visible in ps). Unset on loopback, a token is generated for the run.
KANBO_DEBUGevery command1 adds the values that caused a board refusal (Details: {…}) under its message, and says why the update check got no answer.
KANBO_NO_UPDATE_CHECKevery command, kanbo mcp1 turns off the update check (see Update check).
NO_UPDATE_NOTIFIERevery command, kanbo mcpSet to anything: the same. The variable other command-line tools honour.

Update check#

Every time kanbo starts, it asks npm (https://registry.npmjs.org/kanbo-cli/latest) which version is the latest, alongside the command — once per run, with no schedule and nothing cached. The request gets about 1.5 seconds and never holds the command up: its answer is used only if it arrives before the command finishes, plus at most 0.3 seconds. A command that fails ends at once, and the request is dropped. Pre-releases count only when you run one. If npm cannot be reached, nothing is said (KANBO_DEBUG=1 says why).

Only a global install (npm install -g kanbo-cli) is ever updated in place; how kanbo was started decides what else happens:

Install kindDetected asUpdate command
Globalanything not below, run from this Node's own global node_modulesnpm install -g kanbo-cli@latest
Projecta node_modules/kanbo-cli in the current folder or one above itnpm install kanbo-cli@latest
npxrun from npm's _npx cachenpx kanbo-cli@latest

When a newer kanbo is out:

  • A person at a terminal, global install, is asked after the command's output: kanbo X is available (you have Y). Update now? (default No). Yes runs npm install -g kanbo-cli@latest in the same terminal and prints Updated to X., or npm's failure and the command to run yourself. When npm could not write its global folder (EACCES/EPERM), the failure adds: Your npm global folder needs permissions — see https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally.
  • The home screen (kanbo alone) shows a dim line under the summary and a menu item instead of the question — Update kanbo to X — npm install -g kanbo-cli@latest for a global install (a successful update prints Updated to X — start kanbo again to use it. and ends, exit 0: the running process is still the old kanbo); How to update kanbo to X — <its command> otherwise (Windows, a project install, npx), which only prints the line. Leaving the menu (Exit or Ctrl-C) without updating prints the one-line notice below — no question — if npm's answer has come by then (waiting 0.3 seconds at most).
  • On Windows, a global install never installs itself: the running kanbo holds its SQLite module open, and Windows does not let npm replace a file in use. Instead of the question there is one line on stderr: kanbo X is available (you have Y). Close kanbo and run: npm install -g kanbo-cli@latest.
  • A project install gets one line, in a person's shell or nobody's: kanbo X is available (you have Y). This project installs kanbo; update it here: npm install kanbo-cli@latest. Nothing is asked and nothing is installed.
  • npx gets one line: kanbo X is available (you have Y). npx runs the newest kanbo when you pass @latest: npx kanbo-cli@latest. Nothing is asked and nothing is installed — npx kanbo-cli … without @latest keeps running whatever npx has cached.
  • An agent's shell is told to ask a person, never the raw install command: kanbo X is available (running Y). Ask a person to update: <the install kind's command above>.
  • Any other shell with nobody to ask (a script, CI) gets the same one-line form a person's terminal would for that install kind, e.g. kanbo X is available (you have Y) — npm install -g kanbo-cli@latest for a global install.
  • kanbo doctor shows it as an update finding (info) instead of asking, its fix always the global command (npm install -g kanbo-cli@latest) whatever this install's kind; with --fix, the second round of checks reports the same answer. It waits for npm no longer than any other command does.
  • kanbo mcp asks once, when the server starts, and ends the kanbo_prime tool's answer with Note: kanbo X is available (running Y). Ask a person to update: npm install -g kanbo-cli@latest — always the global command, since an MCP client starts kanbo the way it was registered. It never prints anything else on stdout.

No check is made when CI is set (to anything but empty, 0 or false), with KANBO_NO_UPDATE_CHECK=1 or NO_UPDATE_NOTIFIER set, for machine output (--json, --format json), for --version and --help, and on the kanbo mcp command line itself (only its kanbo_prime note).

Agent shells kanbo recognises#

Some agent tools leave a mark in the environment of every command their agent runs. kanbo reads a shell carrying one as an agent's, exactly as if KANBO_ACTOR_KIND=agent were set: kanbo approve, kanbo return, kanbo sprint close, kanbo columns rules, kanbo columns add|rename|move|remove|template|add-standard, kanbo run clear-session and kanbo run attach-session --replace exit 4 with Only a person can …. This shell belongs to an agent (<mark>): ask a person to … on the board page (kanbo serve)., then a second line, If you are a person in an editor terminal, run: KANBO_ACTOR_KIND=person kanbo <the command as typed> (on Windows: If you are a person in an editor terminal, run in PowerShell: $env:KANBO_ACTOR_KIND='person'; kanbo <the command as typed>) — and nothing asks a question (so kanbo uninstall --purge keeps the board file).

MarkSet bySource
CLAUDECODE=1Claude Code, in its Bash and PowerShell tools, hooks and stdio MCP servers — and in the integrated terminal of its IDE extensionscode.claude.com/docs/en/env-vars
GEMINI_CLI=1Gemini CLI, in run_shell_commandgeminicli.com/docs/tools/shell
CURSOR_AGENT (any value)Cursor, in the Agent's terminalcursor.com/docs/agent/tools/terminal
CODEX_THREAD_ID (any value)Codex, in every shell command it runsnot in Codex's own documentation — populate_env, codex-rs shell_environment.rs, and seen in headless runs (Codex 0.153.0, 2026-09-28)

Your own terminal carries a mark — typically an IDE terminal where the Claude Code extension sets CLAUDECODE=1, or a shell Codex started that inherits CODEX_THREAD_ID — so person-only commands refuse there: set KANBO_ACTOR_KIND=person in that terminal (or its profile; in PowerShell $env:KANBO_ACTOR_KIND='person'), or run the command the refusal's second line prints. KANBO_ACTOR_KIND always wins over the marks. kanbo doctor shows which mark it saw (actor warn).

The session a run records#

kanbo run start without --session, and kanbo_run_start without session, record the session of the agent that runs them, read from the environment:

VariableSet byRecorded as
CLAUDE_CODE_SESSION_IDClaude Code, in its Bash and PowerShell tools, hooks and stdio MCP servers (env-vars)claude:<id>
CODEX_THREAD_IDCodex, in every shell command (its session id; populate_env in codex-rs shell_environment.rs)codex:<id>

Only when exactly one is set: an agent started inside the other's shell inherits both, and nothing says which one is running. Both were seen in a headless run on 2026-09-28 (Claude Code 2.1.283, Codex 0.153.0). CODEX_THREAD_ID is also what marks a Codex shell as an agent's (above); CLAUDE_CODE_SESSION_ID records the session but is not itself a mark — CLAUDECODE is.

How a command finds its board#

First match wins:

terminal
--db <path>  or  --database-url <url>        (both at once: exit 1)
  > KANBO_DATABASE_URL
  > databaseUrl in .kanbo/binding.json        (agentDatabaseUrl in an agent's shell, when present)
  > dbPath in .kanbo/binding.json             (written by kanbo init --file)
  > KANBO_DB_PATH
  > exit 2: This folder has no kanbo board yet. Run kanbo to set one up
            (or kanbo init --yes for the defaults).

The binding is the nearest .kanbo/binding.json at or above the current directory, so commands work from any subdirectory of the project. A relative dbPath is resolved against the project root (the directory holding .kanbo/).

kanbo migrate and kanbo roles apply never use agentDatabaseUrl: they are the owner's commands.

How a command finds its workspace#

Cards are numbered per workspace (APP-001), so every board command needs one:

terminal
--workspace <nameOrId>
  > KANBO_WORKSPACE_ID
  > workspaceId in .kanbo/binding.json
  > (host database only) the workspace whose folder contains the current directory
  > exit 2

On a board file or a Postgres board, the card-key prefix comes from identifier in the binding, so kanbo init always writes one. A board that lives inside another app's SQLite database (a host database) keeps its own workspaces(id, name, identifier, locator_json) table; there kanbo reads the workspace and its prefix from that table, and never writes to it.

.kanbo/binding.json#

Written by kanbo init, merged on every later run, mode 0600, and listed in .kanbo/.gitignore so it is never committed.

json
{
  "schemaVersion": 1,
  "workspaceId": "acme-api",
  "boardId": null,
  "dbPath": ".kanbo/board.db",
  "identifier": "API"
}
FieldMeaning
schemaVersionAlways 1.
workspaceIdThe workspace this project is.
boardIdThe board inside the workspace (--board), usually null.
dbPathThe board file kanbo init --file created, relative to the project root. null or absent otherwise.
databaseUrlThe external Postgres board (--database-url). A secret: this file is the only place it is written.
agentDatabaseUrlThe same board as the agent role logs in (--agent-url). Given to agents' shells and to kanbo mcp.
identifierThe card-key prefix (--identifier).

.kanbo/#

PathCommitted?Written by
.kanbo/binding.jsonnokanbo init
.kanbo/.gitignoreyeskanbo init — lists binding.json, and the board file with its -wal/-shm when the board file is inside .kanbo/
.kanbo/board.db (+ -wal, -shm)nokanbo init --file

kanbo never edits your own .gitignore.

Files kanbo init may also write#

FlagFileContent
--instructions claudeCLAUDE.mdThe instruction block between the <!-- KANBO_START … --> and <!-- KANBO_END --> markers.
--instructions agentsAGENTS.mdThe same block.
--mcp claude.mcp.json{"mcpServers":{"kanbo":{"type":"stdio","command":"kanbo","args":["mcp"]}}}, merged.
--mcp cursor.cursor/mcp.jsonThe same entry, merged.
--mcp codex.codex/config.toml[mcp_servers.kanbo] with command = "kanbo", args = ["mcp"] and default_tools_approval_mode = "approve" (so codex exec can call the board's tools without asking), appended.

These are committed project files, and none of them contains a secret: kanbo mcp reads the board from the binding like every other command.