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.

Beyond columns, actions, and transitions, the team file can carry shortcuts (see Shortcuts), defaultBaseBranch (the team-shared branch tasks start from - the ref a worktree is cut from, and the one a non-worktree task’s branch checkout is fast-forwarded from; see Base Branch), and profiles - named Board Profiles. Profiles are team-only by design: a task’s saved profile choice must resolve on every teammate’s machine, so they never go in kangentic.local.json.

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": "{{task_xml}}{{attachments}}"
      }
    }
  ],
  "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)
description	string	Free-form note on the column’s purpose. Shown as a header tooltip and shared with your team via kangentic.json. Omit when unset
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
autoCommandMode	string	When that prompt fires: "immediate" (default - deliver on arrival, and the CLI queues it if the agent is mid-turn) or "deferred" (wait for the current turn to complete). Neither interrupts a running turn. Only written to the file when set to "deferred"
agentOverride	string	Use a specific agent CLI for sessions in this column: "claude", "codex", "gemini", "cursor", "copilot", "grok", "antigravity", "opencode", "aider", "qwen", "kimi", "droid", "warp", or "ollama". 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	Point the new agent at the prior agent’s native session history file on column entry - enables cross-agent context handoff. Any agent can receive one; whether context carries depends on the outgoing agent. Claude, Codex, Gemini, Grok, Antigravity, OpenCode, Aider, Qwen Code, Kimi Code, and Factory Droid leave a readable history, while Cursor, Copilot, Warp, and Ollama leave nothing Kangentic can hand on
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 sync is bidirectional, and the file wins: on every project open, Kangentic first applies the file’s state to the database - unprompted, before exporting - so hand-editing kangentic.json is a genuine way to change the board, not just a record of it. The confirmation banner covers only an external edit that lands while the project is already open.

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

Note the asymmetry with in-app deletion: Edit Columns and the MCP delete tool refuse to remove a non-empty column outright, while a file edit softly ghosts it instead. A file edit also does not prune Board Profile references to the removed column - the in-app and MCP paths do.

• 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.

A project with no kangentic.json at all does not start with just those two: Kangentic seeds the full seven-column default board (To Do, Planning, Executing, Code Review, Testing, Merge, Done). A team file replaces that seed with whatever columns it declares.

Quick-Start Template

Minimal kangentic.json to bootstrap a new project with a plan-then-execute workflow (an example layout, deliberately smaller than the seeded default):

{
  "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