Board Configuration

Kangentic stores your board layout in a kangentic.json file at the root of each project. This file is designed to be committed to git so your entire team shares the same columns, actions, and transitions.

Two-File System

File	Purpose	Git tracked?
kangentic.json	Team-shared board layout	Yes
kangentic.local.json	Personal overrides	No (auto-added to .gitignore)

Effective config = deep-merge(kangentic.json, kangentic.local.json). Local values win when both files define the same column, action, or transition.

File Format

{
  "version": 1,
  "columns": [
    {
      "id": "e6350e8a-...",
      "name": "To Do",
      "role": "todo",
      "icon": "layers",
      "color": "#6b7280"
    },
    {
      "name": "Planning",
      "icon": "map",
      "color": "#8b5cf6",
      "autoSpawn": true,
      "permissionMode": "plan",
      "planExitTarget": "Executing"
    },
    {
      "name": "Executing",
      "icon": "square-terminal",
      "color": "#3b82f6",
      "autoSpawn": true
    },
    {
      "name": "Done",
      "role": "done",
      "icon": "circle-check-big",
      "color": "#10b981"
    }
  ],
  "actions": [
    {
      "name": "Kill Session",
      "type": "kill_session",
      "config": {}
    },
    {
      "name": "Start Planning Agent",
      "type": "spawn_agent",
      "config": {
        "prompt": "{{title}}{{description}}\n\nWork in {{worktreePath}} on branch {{branchName}}."
      }
    }
  ],
  "transitions": [
    {
      "from": "*",
      "to": "Planning",
      "actions": ["Kill Session", "Start Planning Agent"]
    }
  ]
}

Column Options

Field	Type	Description
id	string	Auto-generated UUID. Enables precise reconciliation - leave blank when hand-writing.
name	string	Display name (must be unique)
role	string	"todo" or "done" - assigns special behavior
icon	string	Lucide icon name (e.g., "layers", "square-terminal")
color	string	Hex color for column header
autoSpawn	boolean	Spawn an agent when a task arrives
permissionMode	string	Permission mode override ("default", "plan", "acceptEdits", "dontAsk", "auto", "bypassPermissions")
planExitTarget	string	Target column name when a plan-mode agent exits
autoCommand	string	Prompt injected into the session when a task arrives
agentOverride	string	Use a specific agent CLI for sessions in this column: "claude", "codex", "gemini", "qwen", "kimi", "opencode", "droid", "cursor", "copilot", "aider", or "warp". Omit to inherit the project’s default agent
modelOverride	string	Adapter-specific model identifier passed at spawn (e.g. opus for Claude, gpt-5-codex for Codex). When a running session moves into a column with a different modelOverride, Kangentic live-applies it via the agent’s /model slash. Hidden in the Edit Column dialog when the active CLI’s capability probe doesn’t expose a --model flag
effortOverride	string	Adapter-specific effort/reasoning level (e.g. low, medium, high, xhigh, max for Claude). Live-applied via /effort on column transition when supported. Hidden when the adapter’s capability probe doesn’t expose effort levels
handoffContext	boolean	Pass the prior agent’s native session history file to the new agent on column entry - enables cross-agent context handoff. Supported in both directions for Claude, Codex, Gemini, Qwen Code, Kimi Code, and OpenCode
sessionTarget	string	Which session track a task runs on in this column: "main" (default - the task’s shared main conversation) or "isolated" (this column’s own separate, context-isolated session, keyed by the column - it does not inherit the main conversation, which suits work like a code review). Only written to the file when set to "isolated"
sessionSpawnStrategy	string	What the column does with its session track on entry: "create_or_resume" (default - resume an existing session, else spawn) or "always_spawn_new" (a fresh, independent pass each entry). Isolated columns default to "always_spawn_new"; only written to the file when it differs from the default

Action Options

Field	Type	Description
name	string	Unique action name (referenced in transitions)
type	string	One of: spawn_agent, send_command, run_script, kill_session, create_worktree, cleanup_worktree, create_pr, webhook
config	object	Type-specific configuration (see Custom Workflows)

Transition Options

Field	Type	Description
from	string	Source column name, or "*" for any column
to	string	Target column name
actions	string[]	Ordered list of action names to execute

Auto-Export

Kangentic automatically exports your board to kangentic.json whenever you make changes in the UI - adding columns, editing actions, reordering, etc. You don’t need to manually maintain this file.

The export uses atomic writes (temp file + rename) so the file is never left in a half-written state.

Team Workflow

Initial setup

1. Open your project in Kangentic and configure your board
2. Kangentic auto-exports kangentic.json to the project root
3. Commit kangentic.json to git and push

Receiving changes

When a teammate pushes an updated kangentic.json:

1. Pull the changes - Kangentic’s file watcher detects the update automatically
2. A reconciliation banner appears asking to apply the new config
3. Click Apply to sync the changes into your board

Kangentic watches the kangentic.json file for changes in real time. Any external modification - a git pull, a hand edit, or another tool - triggers the reconciliation prompt, including a commit you made elsewhere and pulled back onto this machine. Kangentic’s own UI exports write back silently, so they never prompt. Your board stays in sync with your team without any manual import/export steps.

Auto-applying changes

By default, an incoming kangentic.json change waits behind the reconciliation banner so you can review it before it touches your board. To skip the banner and apply detected changes immediately, turn on Auto-Apply Board Config Changes under Settings > Behavior (config key skipBoardConfigConfirm, default off, global-only).

This suits single-author projects and high-trust teams that always want the latest layout. Personal overrides in kangentic.local.json never prompt regardless of this setting - they reload silently.

Personal overrides

If you want to customize a column color or add a personal column without affecting the team file:

1. Make changes in the UI
2. The team-shared properties go to kangentic.json
3. Create kangentic.local.json for overrides you want to keep private

kangentic.local.json is automatically added to .gitignore.

Hand-Written vs. Auto-Exported

Hand-written configs (no id fields) are treated as additive - Kangentic creates missing columns but never deletes existing ones. This is safe for bootstrapping a new team.

Auto-exported configs (with id fields) are treated as canonical - columns in the database that don’t appear in the config are removed or ghosted. This enables full two-way sync.

Note

When you first open a hand-written config, Kangentic assigns UUIDs to all columns and exports the enriched version. Subsequent syncs use ID-based matching.

Ghost Columns

When a teammate removes a column from kangentic.json but you still have tasks in that column:

• The column becomes a ghost - hidden from the board but preserved in the database
• Your tasks are safe; move them to another column
• Once empty, ghost columns are automatically cleaned up on the next reconciliation

This prevents data loss when board layouts change.

System Columns

Every board must have a To Do column (role: "todo") and a Done column (role: "done"). If your config omits them, Kangentic creates defaults. To Do is always first; Done is always last.

Quick-Start Template

Minimal kangentic.json to bootstrap a new project with a plan-then-execute workflow:

{
  "version": 1,
  "columns": [
    { "name": "To Do", "role": "todo" },
    { "name": "Planning", "permissionMode": "plan", "planExitTarget": "Executing", "autoSpawn": true },
    { "name": "Executing", "autoSpawn": true },
    { "name": "Code Review" },
    { "name": "Done", "role": "done" }
  ],
  "actions": [],
  "transitions": []
}

Drop this file in a repo root, open the project in Kangentic, and the board is ready.

Next steps

Next: Custom Workflows - build the transitions and actions that bring your board to life.

See also:

• Shortcuts - team shortcuts also live in kangentic.json
• Configuration Reference - all available keys and types