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:

• System (shared) settings apply to every project. Open the panel from the gear icon in the title bar; the System tabs are shared across all projects.
• Project settings override defaults for one project only. Open them from the gear next to a project in the sidebar, or the title-bar gear while that project is active - the Project tabs always edit the active project.

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

The Settings panel opens from the title-bar gear (scoped to the active project) or the gear on any project row in the sidebar, with a project switcher in the header. Tabs split into two groups:

• Project tabs (General, Theme, Agent, Git, Browser, Shortcuts) hold per-project settings saved to that project’s .kangentic/config.json. They are hidden when no project is open.
• System tabs are shared across every project and stay fully usable with no project open. The sidebar groups them as Core (Board, Task, Changes, Terminal, Behavior, Hotkeys, Notifications), Advanced (Dictation, Memory, MCP Server, Agent Browser, Mobile Devices), and Other (Privacy, Developer).

Changes save immediately. New projects inherit only a seeded subset (theme, agent.permissionMode, git.*) from your most recent project.

General

The General tab shows the project’s location on disk with a Move… button to re-point the project at a moved or renamed folder. Tasks, sessions, and board history are keyed by project ID, so relocating preserves everything. See Multi-Project Support for details.

Theme

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

Board

Board-level layout and window chrome (a System tab, shared across projects). In v0.31.0 the old single “Layout” tab was split into Board, Task, and Changes.

Setting	Description
Column Width	Column width: narrow, default, or wide
Board Layout	horizontal (scroll sideways) or vertical (scroll down)
Auto-Apply Board Config Changes	When a kangentic.json board change is detected (from a teammate or your own pulled-back commit), apply it immediately instead of showing the confirmation dialog (skipBoardConfigConfirm)
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

Task

How individual task cards present themselves (a System tab, new in v0.31.0), grouping settings that used to live under Board and Terminal.

Setting	Description
Card Density	Task card compactness: compact, default, or comfortable
Ticket Numbers	Show each task’s #N number on its board card (showTaskNumbers, default on)
Context Bar	Toggle which pills appear in the per-session context bar: shell, agent version, elapsed time, cost, tool calls, agent-active time, tokens, context window, progress bar, and rate limits. See Terminal & Activity

Changes

Defaults for the Changes panel diff viewer (a System tab).

Setting	Description
Git Diff View	Default layout for file diffs: split (side by side) or inline (unified)
Default Diff Scope	Which changes a freshly opened Changes panel shows: working (uncommitted edits), staged (index), or the full branch vs its base
Ignore Whitespace	Hide whitespace-only changes in the diff to filter reformatting noise
Collapse Unchanged Regions	Fold away large unchanged spans so a big file shows only its changed hunks
Wrap Long Lines	Soft-wrap long lines onto the next row instead of scrolling the diff horizontally
Inline When Narrow	Render a narrow diff pane inline (unified) even when Side by side is selected, instead of squeezing two columns. On by default
File Sort	How the Changes panel orders files: by name, by status, by size (most changes first), or by extension
Flat File List	Show changed files as a flat list of full paths instead of a nested directory tree

Four of these - Ignore Whitespace, Collapse Unchanged Regions, Wrap Long Lines, and Inline When Narrow - are also reachable from the diff toolbar’s View options menu, which writes the same keys.

Terminal

Terminal cosmetics are global (shared across all projects), a System tab.

Setting	Description
Shell	Override the auto-detected shell
Font Family	Terminal font, picked from your installed system fonts via an autocomplete field
Font Size	Terminal text size in pixels
Cursor Style	Terminal cursor appearance: block, underline, or bar (default block)
Word delete on Backspace	Make plain Backspace delete the previous whole word instead of one character (sends Ctrl+H). Off by default; Ctrl+W, Alt+Backspace, and Ctrl+Backspace already word-delete regardless (terminal.backspaceSendsCtrlH)

A Colors section customizes the terminal background, foreground, and cursor with color swatches. Pick a preset (the built-in default, a preset matching your current app theme, or a curated scheme) or set colors individually; the defaults are a near-black #0c0c0c background with #e4e4e7 foreground and cursor. The 16-color ANSI palette (Windows Terminal’s “Campbell” scheme) is a fixed built-in and is not individually editable, and Reset to default clears every customization. See Terminal Colors.

Agent

Setting	Description
Default Agent	Which CLI to spawn by default for new tasks. Fourteen agents are supported: Claude Code, Codex CLI, Gemini CLI, Cursor CLI, GitHub Copilot CLI, Grok Build, Antigravity CLI, OpenCode, Aider, Qwen Code, Kimi Code, Factory Droid, Warp (Oz CLI), and Ollama (local models). Only installed agents are shown in the picker (detection runs on launch)
Default Model	Project-level model default for spawned agents, applied when no column or task override is set. Capability-gated by the Default Agent - only models that CLI supports are offered, and the picker is hidden for agents without a model flag. Leave blank to fall through to the agent’s own default. Changing the Default Agent clears this so you re-pick for the new agent
Default Effort	Project-level reasoning-effort default, applied when no column or task override is set. Only shown for agents that expose effort levels (Claude Code in particular). Leave blank to use the agent’s default
Permission Mode	Default permission mode for spawned agents. The dropdown updates dynamically based on what the selected agent supports. A column or an individual task can override it
CLI Paths	Per-agent CLI path overrides (one path per detected agent). Leave blank to auto-detect on PATH
Execution	For agents that support remote execution (today OpenCode), run the agent locally or attach to a server you run elsewhere, with a Server URL, optional Authentication, and a per-project Server Working Directory. Hidden for agents without the capability
Launch Options	Optional startup features the selected agent CLI can turn off. Today only Codex offers one, Disable ChatGPT Apps, which skips the optional cloud ChatGPT Apps connector that can hang startup

Default Model and Default Effort are also skipped when a column or a task overrides the agent, not just the model. Model ids are adapter-specific, so carrying a Claude project’s haiku onto a Codex column would produce a spawn Codex rejects outright. Those spawns fall through to the new agent’s own default instead, and the rule holds on every spawn path, including a respawn after a restart or crash recovery.

For agents with their own auth flow (Grok Build, OpenCode, Kimi Code), the picker surfaces an amber warning when no credentials are present so you can run grok login, opencode auth login, or kimi login before spawning. Ollama is a local single-turn chat model rather than an agentic coder, so it exposes no permission-mode, model, or effort settings of its own. The Idle Timeout setting now lives on the Behavior tab.

Browser

Settings for the embedded browser pane.

Setting	Description
Browser Enabled	When off, the Browser pill is hidden in the task detail window header, and an agent trying to open a pane over MCP is refused rather than opening one you have no pill to close
Default URL	Project-default URL when a task has no per-task override. Never set automatically: it changes only here or via Save as project default in the pane. A task’s own navigations are saved to that task alone, so one task’s dev-server port is never inherited by its siblings
Clear Browser Data	Clears cookies, localStorage, IndexedDB, cache, and service workers from every browser partition for the project: each task’s own cookie jar, the project’s identity jar, and the legacy shared jar. 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 tasks start from (default: main): the ref a worktree is cut from, and the one a non-worktree task’s branch checkout is fast-forwarded from. A team-shared defaultBaseBranch in kangentic.json outranks it
Copy Files	Files to copy from repo root into new worktrees
Init Script	Shell script run in each new worktree after creation (e.g. npm install). Runs to completion before the agent spawns
Link node_modules	Symlink the repo-root node_modules into each new worktree so agents skip a fresh install (default: on). Turn off to let the Init Script install dependencies in the worktree
Auto-refresh PRs	How often to refresh linked pull-request state in the background while the project is open (default: every 5 minutes)

Shortcuts

Per-project command shortcut buttons that appear in the task detail and Command Terminal window headers. Define a label and a command template, pick from presets, and control how each shortcut displays; shortcuts save to the project’s config and can be shared with your team through kangentic.json. See Command Shortcuts for the full guide.

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
Auto-Resume Agents on Restart	On	Resume the sessions that were running when you last closed Kangentic on the next launch. Turn off if resuming many agents at once overwhelms your machine; those sessions then wait for a manual Resume click on each task
Idle Timeout	0 (off)	Auto-suspend sessions after N minutes of inactivity. 0 disables
Close on Outside Click	Focused	How task-detail windows dismiss when you click empty space outside them: Off (never), Single (only when exactly one window is open), Focused (the focused window, however many are open), or All (every open window). Dismissing keeps the agent running
Restore Window Position	On	Restore the window’s position, size, and maximized state from the previous session

Note

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

Notifications

Pick which session events raise a desktop notification and tune how they present: display duration, how many stack at once, and a per-session cooldown that stops a chatty agent from spamming you. See Notifications for the full behavior, including idle badges and in-app announcements.

Agent Browser

A cross-project security policy for whether and how agents may drive the embedded Browser pane via the kangentic_browser_* MCP tools. Enable Browser Automation is the master switch; sub-toggles then gate interaction (click/type/keypress/drag), navigation, arbitrary JavaScript eval (off by default), and restricting navigation to localhost. See the MCP Server reference for the tools these gate and the Configuration Reference for the browserAutomation.* keys.

Dictation

Local push-to-talk voice-to-text into whatever text field or terminal holds focus. Toggle it on, pick a transcription engine and language, and hold the push-to-talk key (bound in Hotkeys) to dictate. Punctuation, auto-submit, and a release buffer are all configurable; transcription runs on-device by default, with an optional cloud backend for the final pass. See the Configuration Reference for every dictation.* key.

Memory

Local conversation search and recall. Kangentic indexes each agent conversation into a private, on-device index so you can search your past sessions from Quick Find and agents can recall them through the kangentic_search MCP tool. Two toggles: Index conversations (on by default) and Semantic search (opt-in). Turning on semantic search reveals a Search quality model picker (a small local embedding model, downloaded once), a status card (model name, size, download state, active backend), and a Hardware acceleration dropdown (Auto / GPU / CPU). A Rebuild index button re-runs the local index for the current project. Everything runs locally with no API key. See Conversation Memory for the full feature and the Configuration Reference for every memory.* key.

MCP Server

Holds the master toggle for the built-in MCP server (mcpServer.enabled), which gives agents tools to interact with your board - create tasks, move cards, search past sessions, and more. The tab lists the available tools, each deep-linking to its entry in the Tool Reference. The remaining mcpServer.* keys, including the bind address, are documented in the Configuration Reference.

Mobile Devices

The desktop half of the Kangentic Mobile link. Global rather than per-project, and off until you enable the Mobile Bridge toggle. Below the toggle the tab splits in two: Relay picks where this desktop connects, choosing between Kangentic Relay (the hosted instance, marked Official) and Custom Relay (your own address), with the resolved address shown beneath and a Test connection button that probes it before you pair. Mobile is where you pair a phone, rename or revoke the ones already paired, and open the install guide. Both sections end in a documentation link that stays clickable with the bridge off, since someone deciding whether to turn it on is exactly the person who has not. See Pairing a Phone and the Configuration Reference for every mobileBridge.* key.

Hotkeys

The Hotkeys tab lists every shortcut in the app, grouped by area (General, Dictation, Task Detail, Git Changes, Windows, Terminal), and lets you rebind most of them to a keyboard chord or a mouse button (middle or side). Conflicting bindings are flagged, and rebinding onto a combo the embedded terminal consumes shows a warning. Overrides are stored per-machine and never shared per-project. See Hotkeys for the full default list and rebinding details.

Privacy

Kangentic sends anonymous usage analytics to Aptabase and crash and error reports to Sentry, to help improve the product. Only high-level events are collected (e.g., app_launch, project_create) - no code and no task content - and machine-specific paths are stripped from stack traces before an error report leaves your machine. The tab is informational and also points to the Memory tab for the (fully local, on-device) conversation-search controls. See Privacy & Analytics for the full breakdown.

To opt out, set the environment variable:

KANGENTIC_TELEMETRY=0

Or turn off error reporting alone and keep usage analytics on:

KANGENTIC_ERROR_REPORTING=0

Developer

Diagnostic aids for debugging Kangentic itself. The tab’s toggle is Activity Engine Debug Overlay, a floating panel showing live activity-engine state for every running session - useful when chasing spinner or idle-detection oddities. The other developer.* flags are file-only; see Developer Settings in the Configuration Reference.

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, Grok
Auto	Classifier-driven auto-approval	Claude, Copilot, Grok

Defaults vary: Claude, Codex, Gemini, Copilot, Grok Build, Antigravity, OpenCode, and Qwen Code 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. Task’s permission_mode (if set) - pinned per task in the New Task Advanced section or the task-detail edit form; it holds for the task’s whole lifetime regardless of column moves
2. Column’s permission_mode (if set)
3. 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
Description	Free-form note on the column’s purpose. Shown as a header tooltip and shared with your team via kangentic.json. Display only: it is never sent to the agent
Color	Header accent color
Icon	Lucide icon name (e.g., square-terminal, code, flask-conical)
Agent Override	Use a specific agent (any of the fourteen) 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
Start an agent here	Whether dragging a task here spawns an agent (the auto_spawn toggle; default: on)
Message to agent	A prompt sent to the running session when a task arrives in this column. Plain prose or a slash command; an insert-variable picker offers the template variables. Stored as autoCommand in kangentic.json
Message timing	Whether that message is delivered on arrival (Run immediately, the default) or held until the agent’s current turn finishes (Wait for current turn). Neither interrupts a running turn
Receive context from prior agent	When enabled, the prior agent’s native session history file is passed to the new agent as context on column entry (the handoff_context toggle) - enables multi-agent handoff across agent types
After Plan Mode	For plan-mode columns: where tasks move when planning completes
Session	Whether tasks in this column run on the task’s shared Main session or an Isolated session of their own, context-isolated from the main conversation. Isolated suits work that should stay independent, such as a code review. Hidden for To Do / Done columns
On enter	Whether entering this column resumes the target session when one exists (Create or resume) or always starts a fresh pass (Always spawn new). Isolated columns default to a fresh pass each entry

Click Add column on the board toolbar (or click any column header) to open the Edit Columns dialog and manage every column from one place - add, rename, reorder, and configure each column’s settings. Whole boards’ worth of these per-column settings can also be saved as named, switchable ladders - see Board Profiles.

Column Roles

Two columns have special roles:

• To Do - Holding area. Moving a task here is a full reset: the session is killed and its history wiped, the worktree is removed, and the branch is deleted when Auto Cleanup is on. If the move would destroy uncommitted or unmerged work, a confirmation dialog flags it first - see Worktree Lifecycle.
• 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
• Hotkeys - the global keyboard shortcut reference
• Shortcuts - custom commands in the task detail dialog