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": "Backlog",
      "role": "todo",
      "icon": "layers",
      "color": "#6b7280"
    },
    {
      "name": "Planning",
      "icon": "map",
      "color": "#8b5cf6",
      "autoSpawn": true,
      "permissionMode": "plan",
      "planExitTarget": "Executing"
    },
    {
      "name": "Executing",
      "icon": "square-terminal",
      "color": "#2563eb",
      "autoSpawn": true
    },
    {
      "name": "Done",
      "role": "done",
      "icon": "check-circle",
      "color": "#16a34a"
    }
  ],
  "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", "cursor", "copilot", "aider", or "warp". Omit to inherit the project’s default agent
handoffContext	boolean	Pass the prior agent’s native session history file to the new agent on column entry — enables cross-agent context handoff

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 modification — whether from a git pull, a manual edit, or another tool — triggers the reconciliation prompt. This means your board stays in sync with your team without any manual import/export steps.

Tip

Set skipBoardConfigConfirm: true in your settings to auto-apply config changes without the confirmation banner.

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 Backlog column (role: "todo") and a Done column (role: "done"). If your config omits them, Kangentic creates defaults. Backlog 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": "Backlog", "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.