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

New Project Seeding

When you create a new project, Kangentic seeds its .kangentic/config.json with only a subset of your most recently configured project’s settings: theme, terminal.*, agent.permissionMode, and git.*. Everything else falls back to the built-in defaults. Project-specific data - notably browser.* (including browser.defaultUrl) and saved backlog import sources - is stored per-project and is never copied into a new project, so one repository’s dev-server URL or issue-tracker connections cannot leak into another.

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

Agent settings are unified across all supported agents: Claude Code, Codex CLI, Gemini CLI, Qwen Code, Kimi Code, OpenCode, Factory Droid, Cursor CLI, GitHub Copilot CLI, Aider, and Warp/Oz CLI.

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, qwen, kimi, opencode, droid, aider, cursor, copilot, warp). null = auto-detect. Example: { "claude": null, "codex": "/usr/local/bin/codex", "kimi": "/Users/me/.local/bin/kimi" }
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, Qwen, Kimi, OpenCode (Plan agent), Aider, Copilot, Warp
default	Uses the agent’s built-in defaults (e.g., Claude Code’s .claude/settings.json allowlist)	Claude, Codex, Gemini, Qwen, Kimi, Droid, Aider, Cursor, Copilot, Warp
acceptEdits	File edits auto-approved; other actions prompt (OpenCode: maps to its Build agent)	Claude, Codex, Gemini, Qwen, OpenCode, Aider, Copilot
bypassPermissions	Full autonomy, no permission prompts at all	Claude, Codex, Gemini, Qwen, Kimi, 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
Qwen Code	acceptEdits	Labeled “Auto Edit” - soft fork of Gemini CLI
Kimi Code	default	Labels: Plan, Default (Confirm Actions), YOLO
OpenCode	acceptEdits	Labels surface OpenCode’s native Plan and Build agents - selecting Plan maps to OpenCode’s read-only built-in agent
Factory Droid	default	Single “Default” entry; autonomy is controlled in the Droid TUI (Shift+Tab cycles low/medium/high)
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_mode (if set)
2. 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 agent CLI version
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 adapter-reported rate-limit bars (Claude reports 5-hour session and 7-day weekly windows; hidden for adapters that don’t report rate limits)

The model and effort pills are always visible when the adapter reports them. Both pills double as click-targets for the per-task model/effort picker popover, so they no longer have show/hide toggles. Effort levels are surfaced for adapters whose discoverCapabilities reports a non-empty effortLevels list (Claude Code in particular).

Sidebar Settings

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

Browser Settings

Settings for the embedded browser pane.

Key	Type	Default	Scope	Description
browser.enabled	boolean	true	Both	When false, the Browser pill is hidden in the task detail dialog header
browser.defaultUrl	string | undefined	undefined	Both	Project-default URL used when a task has no per-task override. Auto-saved on first navigation in a project. Stored per-project; never seeded into new projects

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_mode	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", "qwen", "kimi", "opencode", "droid", "aider", "cursor", "copilot", "warp"). null inherits the project default agent
model_override	string | null	null	Adapter-specific model identifier passed at spawn (e.g. Claude --model opus, Codex --model gpt-5-codex). Live-applied via the agent’s /model slash on column transition when supported
effort_override	string | null	null	Adapter-specific effort/reasoning level passed at spawn (e.g. Claude --effort xhigh). Live-applied via the agent’s /effort slash on column transition when supported
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. Supported in both directions for Claude, Codex, Gemini, Qwen, Kimi, and OpenCode; no-op for Cursor, Copilot, Droid, Aider, and Warp

The available models and effort levels are surfaced from each adapter’s discoverCapabilities probe - the Edit Column dropdown shows only what the active CLI supports. 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
• 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)
• developer.* (all developer 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.

Developer Settings

Power-user toggles for diagnosing the activity engine and other internal subsystems. All are global-only and default to off. Toggle the whole panel from anywhere with Ctrl+Shift+D.

Key	Type	Default	Description
developer.activityDebugOverlay	boolean	false	Show the floating activity-engine debug overlay (live counters, current activity reason, and recent transitions per running session). Also writes a per-session JSON snapshot under .kangentic/debug/ on each state change
developer.persistConsoleLogs	boolean	false	Persist info/debug/log console output to .kangentic/logs/<date>.log (errors and warnings are always persisted). Read via the kangentic_tail_logs MCP tool
developer.recordIpcTraffic	boolean	false	Record every IPC handler call (channel, args, result, duration) to .kangentic/logs/ipc-<date>.jsonl. Sensitive channels are redacted. Off by default - non-trivial disk impact
developer.previewInspectionServer	boolean	dev: true, prod: false	Bind a localhost-only HTTP inspection bridge powering the dev-only devtools MCP tools. The UI affordance is excluded from production builds; the key persists for type compatibility but has no effect in shipped binaries
developer.previewEvalEnabled	boolean	false	Stricter gate on top of previewInspectionServer that enables high-risk inspection endpoints (eval, synthetic session events, raw PTY input). Off by default even in dev

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.