Settings & Customization

Kangentic is designed to adapt to your workflow. Customize everything from visual themes to how agents behave in each column.

Accessing Settings

Kangentic has two levels of settings:

• Global Settings - Click the gear icon in the title bar. These apply to all projects.
• Project Settings - Click the gear icon next to a project in the sidebar. These override global settings for that project only.

Project settings are stored in .kangentic/config.json within the project. Some settings (like max concurrent sessions and sidebar width) are global-only and cannot be overridden per-project.

Search

A search bar at the top of the settings panel filters settings by keyword. Type multiple words to narrow results - all tokens must match. Results are grouped by tab with match count badges on the sidebar tabs. Tabs with zero matches are dimmed. Press Ctrl+F (Cmd+F on macOS) to focus the search bar, Escape to clear the filter.

Sync to All Projects

When you change a project default in Global Settings, a confirmation modal asks if you want to apply the change to all existing projects. This is useful for rolling out a setting change across your workspace.

Settings Tabs

Appearance

Setting	Description
Theme	Choose from 10 built-in themes (see below)

Choose from 10 built-in themes:

Category	Themes
Base	Dark, Light
Dark variants	Moon, Forest, Ocean, Ember
Light variants	Sand, Mint, Sky, Peach

Layout

Added in v0.15.0. Controls density, sizing, and visibility of major UI chrome.

Setting	Description
Card Density	Task card compactness: compact, default, or comfortable
Column Width	Column width: narrow, default, or wide
Terminal Panel Visible	Toggle the bottom terminal panel
Status Bar Visible	Toggle the status bar at the bottom of the window
Animations Enabled	Enable or disable UI transition animations
Restore Window Position	Restore the window’s position, size, and maximized state from the previous session
Board Layout	horizontal (scroll sideways) or vertical (scroll down)

Terminal

Setting	Description
Shell	Override the auto-detected shell
Font Family	Terminal font
Font Size	Terminal text size in pixels
Scrollback Lines	Lines kept in the visible scrollback buffer (1000 to 100000, default 5000). Full session history is preserved for replay regardless of this value
Cursor Style	Terminal cursor appearance: block, underline, or bar (default block)
Show Preview	Show a terminal preview snippet in task cards

Agent

Setting	Description
Default Agent	Which CLI to spawn by default for new tasks. Eleven agents are supported: Claude Code, Codex CLI, Gemini CLI, Qwen Code, Kimi Code, OpenCode, Factory Droid, Cursor CLI, GitHub Copilot CLI, Aider, and Warp (Oz CLI). Only installed agents are shown in the picker (detection runs on launch)
Permission Mode	Default permission mode for spawned agents. The dropdown updates dynamically based on what the selected agent supports
CLI Paths	Per-agent CLI path overrides (one path per detected agent). Leave blank to auto-detect on PATH
Idle Timeout	Auto-suspend sessions after N minutes of inactivity. 0 disables
Auto-Resume Agents on Restart	When on (default), sessions that were running when you last closed Kangentic auto-resume on next launch. Turn off if auto-resuming many agents at once overwhelms your machine; paused sessions wait for a manual Resume click on each task

For agents with their own auth flow (Kimi Code, OpenCode), the picker surfaces an amber warning when no credentials are present so you can run kimi login or opencode auth login before spawning.

Browser

Settings for the embedded browser pane.

Setting	Description
Browser Enabled	When off, the Browser pill is hidden in the task detail dialog header
Default URL	Project-default URL when a task has no per-task override. Auto-saved on first navigation in a project
Clear Browser Data	Clears cookies, localStorage, IndexedDB, cache, and service workers from the shared browser partition. Per-task and project URL overrides are intentionally left alone

Git

Setting	Description
Worktrees Enabled	Create isolated branches per task
Auto Cleanup	Delete branches when worktrees are removed
Default Base Branch	Branch to create worktrees from (default: main)
Copy Files	Files to copy from repo root into new worktrees
Init Script	Shell script to run after worktree creation

Behavior

Setting	Default	Description
Max Concurrent Sessions	8	How many agents can run at once (excess tasks are queued)
Queue Overflow	Queue	What happens when the concurrent limit is hit: queue new sessions or reject them
Auto-Focus Idle Session	Off	Auto-switch to a session’s terminal tab when it goes idle

Note

Several confirmation dialogs (delete task, Done-move worktree cleanup, board-config apply) have built-in “don’t ask again” checkboxes. Tick them to suppress the corresponding prompt without visiting Settings. The underlying skipDeleteConfirm / skipDoneWorktreeConfirm / skipBoardConfigConfirm keys are still editable in config.json.

Privacy

Kangentic collects anonymous usage analytics via Aptabase to help improve the product. Only high-level events are collected (e.g., app_launch, project_added) - no code, task content, or personal data.

To opt out, set the environment variable:

KANGENTIC_TELEMETRY=off

Permission Modes

Each agent session runs with a permission mode that controls how much autonomy the agent has. Kangentic supports multiple agents, and each agent advertises its own set of supported modes - the dropdown updates dynamically when you switch agents.

Mode	Description	Supported by
Plan	Read-only tools auto-approved; edits require approval	Most agents (OpenCode maps this to its built-in Plan agent)
Default	Uses the agent’s built-in defaults	All agents
Accept Edits	File edits auto-approved; other actions require approval (OpenCode: maps to its Build agent)	Most agents
Bypass	Full autonomy - no prompts at all	Most agents
Don’t Ask	Deny everything not already allowed - no interactive prompts	Claude, Codex, Copilot
Auto	Classifier-driven auto-approval	Claude, Copilot

Defaults vary: Claude, Codex, Gemini, Qwen Code, OpenCode, and Copilot default to Accept Edits. Kimi Code, Droid, and Warp default to Default (Droid’s autonomy is controlled inside its TUI; Warp manages permissions via --profile; Kimi exposes Plan/Default/YOLO labels). Aider and Cursor default to Bypass Permissions (Aider is edit-first; Cursor runs non-interactive so its stream-JSON init event fires).

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.

The most specific setting wins:

1. Column’s permission_mode (if set)
2. agent.permissionMode from config

Tip

Use Plan mode on a “Planning” column so the agent creates a plan first, then auto-moves to an “Executing” column where it runs with more autonomy. See Custom Workflows for details.

Per-Column Customization

Each column on your board can be individually configured. Click the settings icon on any column header to access:

Option	Description
Name	Column display name
Color	Header accent color
Icon	Lucide icon name (e.g., square-terminal, code, flask-conical)
Agent Override	Use a specific agent (any of the eleven) for sessions in this column instead of the project default. The permission mode dropdown re-populates with the new agent’s supported modes. Hidden for To Do / Done columns
Permission Mode	Override the global permission mode for agents in this column
Model Override	Pin sessions in this column to a specific model. Live-applied via /model on column transition. Hidden when the active CLI doesn’t expose a --model flag
Effort Override	Pin sessions in this column to a specific reasoning level. Live-applied via /effort. Hidden when the adapter doesn’t expose effort levels
Auto Spawn	Whether dragging a task here spawns an agent (default: on)
Auto Command	A prompt injected into the running session when a task arrives
Handoff Context	When enabled, the prior agent’s native session history file is passed to the new agent as context on column entry - enables multi-agent handoff across agent types
Plan Exit Target	For plan-mode columns: where tasks move when planning completes

Open the Edit Columns dialog from the board toolbar to manage all columns from one place - add, rename, reorder, and configure each column’s settings without per-column dialogs.

Column Roles

Two columns have special roles:

• To Do - Holding area. Moving a task here kills its session (worktree is preserved).
• Done - Moving a task here suspends its session (preserving context for later resume) and archives the task.

All other columns are fully customizable with no built-in behavior.

Config File Locations

Windows

%APPDATA%/kangentic/config.json

macOS

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

Linux

~/.config/kangentic/config.json

For the full configuration reference with JSON keys and types, see Configuration Reference.

Next steps

Next: Configuration Reference - the underlying JSON keys, types, and resolution order.

See also:

• Custom Workflows - column-level customization
• Shortcuts - keyboard and command shortcuts