Configuration

This is the full configuration reference. For a friendlier overview, see Settings & Customization.

Configuration Cascade

Kangentic resolves settings in three layers:

1. Built-in defaults — sensible defaults for all settings
2. Global user config — your personal defaults for all projects
3. Project overrides — per-repository settings

Effective config = deep-merge(defaults, global config, project config).

Configuration Files

Windows

Global: %APPDATA%/kangentic/config.json

Project: <project>/.kangentic/config.json

macOS

Global: ~/Library/Application Support/kangentic/config.json

Project: <project>/.kangentic/config.json

Linux

Global: ~/.config/kangentic/config.json

Project: <project>/.kangentic/config.json

Project settings override global settings when both are present.

Top-Level Settings

Key	Type	Default	Scope	Description
theme	string	"dark"	Both	UI theme: dark, light, moon, forest, ocean, ember, sand, mint, sky, peach
sidebarVisible	boolean	true	Global only	Show/hide the sidebar
boardLayout	string	"horizontal"	Global only	Board scroll direction: horizontal or vertical
cardDensity	string	"default"	Global only	Task card density: compact, default, or comfortable
columnWidth	string	"default"	Global only	Column width: narrow, default, or wide
terminalPanelVisible	boolean	true	Global only	Show the bottom terminal panel
statusBarVisible	boolean	true	Global only	Show the status bar at the bottom of the window
animationsEnabled	boolean	true	Global only	Enable transition animations across the UI
showBoardSearch	boolean	true	Global only	Show the search bar above board columns
skipDeleteConfirm	boolean	false	Global only	Skip confirmation dialog on task delete
skipBoardConfigConfirm	boolean	false	Global only	Skip confirmation when applying board config changes
autoFocusIdleSession	boolean	false	Global only	Auto-switch to session tab when agent goes idle
skipDoneWorktreeConfirm	boolean	false	Global only	Skip the confirmation dialog when a task moves to Done. Written by the Done-move dialog’s “don’t ask again” checkbox (not surfaced in the Settings panel)
restoreWindowPosition	boolean	true	Global only	Restore window position and size from last session
statusBarPeriod	string	"live"	Global only	Default time period for usage stats: live, today, week, month, all

Backlog Settings

Key	Type	Default	Scope	Description
backlog.priorities	array	See below	Both	Customizable priority levels with labels and colors
backlog.labelColors	object	{}	Both	Default color mappings for backlog labels ({ "label-name": "#hex" })

Default priorities:

Index	Label	Color
0	None	#6b7280
1	Low	#3b82f6
2	Medium	#eab308
3	High	#f97316
4	Urgent	#ef4444

Terminal Settings

Key	Type	Default	Scope	Description
terminal.shell	string | null	null	Both	Shell executable path. null = auto-detect
terminal.fontFamily	string	"Menlo, Consolas, \"Courier New\", monospace"	Both	Terminal font family
terminal.fontSize	number	14	Both	Terminal font size (px)
terminal.scrollbackLines	number	5000	Both	Terminal scrollback buffer size (lines)
terminal.cursorStyle	string	"block"	Both	Cursor style: block, underline, or bar
terminal.showPreview	boolean	false	Global only	Show terminal preview in task cards
terminal.panelHeight	number	250	Global only	Bottom panel height (px)
terminal.panelCollapsed	boolean	false	Global only	Persisted collapsed state of the bottom terminal panel

Agent Settings

As of v0.15.0, agent settings are unified across all supported agents (Claude Code, Codex CLI, Gemini CLI, Aider, Cursor CLI, GitHub Copilot CLI, and Warp/Oz CLI). The claude.* keys from previous releases have been renamed to agent.*.

Key	Type	Default	Scope	Description
agent.permissionMode	string	"acceptEdits"	Both	Default permission mode for spawned agents
agent.cliPaths	object	{}	Global only	Per-agent CLI path overrides, keyed by agent name (claude, codex, gemini, aider, cursor, copilot, warp). null = auto-detect. Example: { "claude": null, "codex": "/usr/local/bin/codex", "cursor": "/usr/local/bin/agent" }
agent.maxConcurrentSessions	number	8	Global only	Max concurrent PTY sessions across all agents
agent.queueOverflow	string	"queue"	Global only	Overflow behavior: queue or reject
agent.idleTimeoutMinutes	number	0	Global only	Auto-suspend sessions after N minutes idle. 0 = disabled
agent.autoResumeSessionsOnRestart	boolean	true	Global only	When true, agent sessions that were running at last close auto-resume when Kangentic restarts. When false, sessions stay paused and require a manual Resume click on each task. Turn off if auto-resuming many agents at once overwhelms your machine.

Permission Modes

Each agent advertises its own supported permission modes, and the Edit Column and Settings dropdowns update dynamically when you switch agents. The full set of modes is:

Mode	Behavior	Supported by
plan	Read-only tools auto-approved; edits require approval	Claude, Codex, Gemini, Aider, Copilot, Warp
default	Uses the agent’s built-in defaults (e.g., Claude Code’s .claude/settings.json allowlist)	Claude, Codex, Gemini, Aider, Cursor, Copilot, Warp
acceptEdits	File edits auto-approved; other actions prompt	Claude, Codex, Gemini, Aider, Copilot
bypassPermissions	Full autonomy, no permission prompts at all	Claude, Codex, Gemini, Aider, Cursor, Copilot, Warp
dontAsk	Deny everything not already allowed, no interactive prompts	Claude, Codex, Copilot
auto	Classifier-driven auto-approval	Claude, Copilot

Per-agent defaults:

Agent	Default permission mode	Notes
Claude Code	acceptEdits
Codex CLI	acceptEdits
Gemini CLI	acceptEdits
GitHub Copilot CLI	acceptEdits
Aider	bypassPermissions	Aider is an edit-first CLI that expects broad file-write access
Cursor CLI	bypassPermissions	Non-interactive mode is the default so the stream-JSON init event fires and the ContextBar model pill resolves
Warp (Oz CLI)	default	Permission-mode labels are informational only; Warp manages permissions via agent profiles (--profile)

Note

When you switch an agent (globally or per-column), Kangentic preserves the current mode if the new agent supports it; otherwise it falls back to that agent’s recommended default.

Permission mode is resolved in priority order:

1. Column’s permission_strategy (if set)
2. Action’s permissionMode config (if set)
3. agent.permissionMode from config

Caution

bypass-permissions gives agents full autonomy with no safety prompts. While worktree isolation prevents changes to your main working tree, agents can still run arbitrary commands. Use plan or acceptEdits if you prefer to review before execution.

Git Settings

Key	Type	Default	Scope	Description
git.worktreesEnabled	boolean	true	Both	Create isolated git worktrees per task
git.autoCleanup	boolean	true	Both	Delete branches when worktrees are removed
git.defaultBaseBranch	string	"main"	Both	Default base branch for worktrees
git.copyFiles	string[]	[]	Both	Files to copy from repo root into new worktrees
git.initScript	string | null	null	Both	Shell script to run after worktree creation

Tip

Use git.copyFiles to copy files like .env or node_modules symlinks into worktrees. Use git.initScript to run setup commands like npm install after worktree creation.

Context Bar Settings

Key	Type	Default	Scope	Description
contextBar.showShell	boolean	true	Global only	Show shell name in context bar
contextBar.showVersion	boolean	true	Global only	Show Claude Code version
contextBar.showModel	boolean	true	Global only	Show model name
contextBar.showCost	boolean	true	Global only	Show session cost
contextBar.showTokens	boolean	true	Global only	Show token usage
contextBar.showContextFraction	boolean	true	Global only	Show context window fraction
contextBar.showProgressBar	boolean	true	Global only	Show context window progress bar
contextBar.showRateLimits	boolean	true	Global only	Show Claude 5-hour session and weekly plan-usage rate-limit bars (Claude only)

Sidebar Settings

Key	Type	Default	Scope	Description
sidebar.width	number	400	Global only	Sidebar width in pixels

Notification Settings

Key	Type	Default	Scope	Description
notifications.desktop.onAgentIdle	boolean	true	Global only	Desktop notification when agent goes idle
notifications.desktop.onAgentCrash	boolean	true	Global only	Desktop notification when agent crashes
notifications.desktop.onPlanComplete	boolean	true	Global only	Desktop notification when planning completes
notifications.toasts.onAgentIdle	boolean	true	Global only	In-app toast when agent goes idle
notifications.toasts.onAgentCrash	boolean	true	Global only	In-app toast when agent crashes
notifications.toasts.onPlanComplete	boolean	true	Global only	In-app toast when planning completes
notifications.toasts.durationSeconds	number	4	Both	How long toasts display
notifications.toasts.maxCount	number	5	Global only	Maximum simultaneous toasts on screen
notifications.cooldownSeconds	number	10	Global only	Minimum seconds between repeated notifications

Column-Level Settings

Each column (swimlane) can override settings individually:

Field	Type	Default	Description
permission_strategy	string | null	null	Permission mode override for this column
auto_spawn	boolean	true	Whether moving a task here spawns an agent
auto_command	string | null	null	Command injected into running sessions on task arrival
plan_exit_target_id	string | null	null	Target column when plan-mode agent exits
agent_override	string | null	null	Use a specific agent for sessions in this column (one of "claude", "codex", "gemini", "aider", "cursor", "copilot", "warp"). null inherits the project default agent
handoff_context	boolean	false	When enabled, hand the prior agent’s native session history file to the next agent when a task moves into this column. Enables multi-agent context handoff (supported for Claude, Codex, and Gemini; no-op for agents without a parseable native history file)

See Custom Workflows for details on how these interact.

Themes

Kangentic includes 10 built-in themes:

Dark themes

• Dark — Default dark theme
• Moon — Cool-toned dark theme
• Forest — Green-accented dark theme
• Ocean — Blue-accented dark theme
• Ember — Warm orange-accented dark theme

Light themes

• Light — Default light theme
• Sand — Warm neutral light theme
• Mint — Green-accented light theme
• Sky — Blue-accented light theme
• Peach — Warm pink-accented light theme

Set the theme in the settings panel or in your global config file.

Global-Only Settings

These settings cannot be overridden per-project:

• agent.maxConcurrentSessions
• agent.queueOverflow
• agent.cliPaths
• agent.idleTimeoutMinutes
• agent.autoResumeSessionsOnRestart
• sidebarVisible
• showBoardSearch
• skipDeleteConfirm
• skipDoneWorktreeConfirm
• skipBoardConfigConfirm
• autoFocusIdleSession
• boardLayout
• cardDensity
• columnWidth
• terminalPanelVisible
• statusBarVisible
• animationsEnabled
• sidebar.width
• terminal.panelHeight
• terminal.panelCollapsed
• terminal.showPreview
• restoreWindowPosition
• statusBarPeriod
• notifications.* (all notification settings)
• contextBar.* (all context bar settings)

MCP Server Settings

Key	Type	Default	Scope	Description
mcpServer.enabled	boolean	true	Both	Enable/disable the MCP server that lets agents interact with the board

When enabled, each agent session gets access to MCP tools for creating tasks, searching the board, browsing the backlog, and reading session transcripts. As of v0.15.0 the MCP server runs as an in-process streamable HTTP transport (replacing the earlier file-bridge). Disable this if you don’t want agents to be able to modify the board.

Environment Variables

Variable	Description
KANGENTIC_DATA_DIR	Override the config/data directory path
KANGENTIC_LOG_LEVEL	Set log verbosity: debug, info, warn, error
KANGENTIC_TELEMETRY	Set to off to disable anonymous usage analytics

Telemetry & Analytics

Kangentic collects anonymous usage analytics via Aptabase. No personal data, code, or file paths are collected. Opt out by setting KANGENTIC_TELEMETRY=0.

See Privacy & Analytics for full details on what is collected and how to opt out.