Settings

The Settings panel has two levels, per project and shared across projects. This page walks every tab in the order the panel lists them, then the permission modes, the per-column options, and where the config files live.

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.

Project tabs

The first six tabs are per project: their values save to that project’s .kangentic/config.json, a project switcher in the panel header picks which project they edit, and they are hidden when no project is open. Changes save immediately. New projects inherit only a seeded subset (the Theme tab’s four keys, 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 Multiple projects for details.

Theme

Setting	Description
Follow system appearance	Keep one theme for when the OS is light and another for when it is dark (`themeFollowsSystem`, with `themeLight` and `themeDark`). The app paints whichever matches the OS right now and switches the moment the OS does, with no restart
Theme	Choose from 12 built-in themes (see below), stored as `theme`

The 12 themes are a grid of tiles, each painted in its own colors, so you pick by eye. Rest the pointer on a tile to try that theme on the whole app without changing anything; move off the grid and it reverts. Click a tile to keep it, or with the grid focused use the arrow keys, Home and End, or type the first letter of a name. The tiles are grouped by whether the theme is dark or light underneath:

Group	Themes
Dark	Graphite, Rust, Moon, Forest, Ocean, Ember
Light	Paper, Clay, Sand, Mint, Sky, Peach

Graphite and Paper are the neutral defaults. Rust and Clay are the product pair, built from kangentic.com’s own colors, so the app and the site read as one surface; their tiles carry the brand mark. Color only: the site’s typefaces do not come with the theme, and the terminal keeps its own color scheme (see Terminal colors). In config.json, Graphite and Paper keep their original ids, dark and light; the others are their lower-cased names.

With Follow system appearance on, each group in the grid has its own selected tile and the other tiles dim so the pair stands out (a dimmed tile still previews on hover and can be picked). Turning it on keeps the theme you had, as that group’s choice, and turning it off keeps whichever theme is showing. The launch background follows the same rule, so a follow-system install opens in the right color.

Agent

Setting	Description
Agent (Project defaults)	Which CLI to spawn by default for new tasks, from the fifteen supported agents. Only installed agents are shown in the picker (detection runs on launch)
Model (Project defaults)	Project-level model default for spawned agents, applied when no column or task override is set. Capability-gated by the project’s 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 Agent clears this so you re-pick for the new agent
Effort (Project defaults)	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
Permissions (Project defaults)	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 path	Per-agent CLI path overrides (one path per detected agent). Leave blank to auto-detect on `PATH`. A path you set is probed and used as-is: if it does not answer its version command, the agent reports as not found at that path rather than silently falling back to `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

The project’s Model and Effort defaults 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 or effort settings of its own. Idle timeout (minutes) is on the Behavior tab.

Git

The tab has three cards: Branches, Worktrees, and Pull requests.

Setting	Card	Description
Default base branch	Branches	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
Auto-fetch remote	Branches	On by default. Fetches the project’s remotes 5 minutes after its last full fetch, so ahead/behind counts stay current. Fetch only, never a pull or merge, with credential prompts disabled. Off, the project still fetches when it opens, and creating a worktree always fetches its base branch first
Worktrees	Worktrees	On by default. Gives tasks the option to run in their own worktree, so the New Task dialog offers Worktree or Project. Off, the dialog drops the choice and tasks run in the project folder; a task that already has a worktree keeps it. The rows below it show only while this is on
Auto-cleanup	Worktrees	Delete a task’s branch when its worktree is removed by a move to To Do or a delete (default: on). A move to Done keeps the branch either way
Link node_modules	Worktrees	Symlink the repo-root `node_modules` into each new worktree so agents skip a fresh install (default: on). Turn off to let the Post-worktree script install dependencies in the worktree
Copy files	Worktrees	Files to copy from repo root into each new worktree, such as `.env`
Post-worktree script	Worktrees	Shell script run in each new worktree after creation (e.g. `npm install`). Runs to completion before the agent spawns
Auto-refresh PRs	Pull requests	On by default. Checks each open PR about 2 minutes after its own last check, keeping merge readiness current. Off, PRs are checked when the project opens and nothing re-polls one whose checks are running
Count merge bypass as ready	Pull requests	On by default, GitHub only. A PR still waiting on a required review reads `blocked` even when your bypass would merge it, and stays that way once a sibling PR lands and leaves yours behind the base. On, such a PR reads `ready`, at one extra `gh` call per such PR per check - never past a failing or unfinished check

Azure DevOps PRs always have their branch policies evaluated since v0.44.0, so the Evaluate branch policies switch is gone, and a clean Azure PR reads ready or blocked the same way a GitHub one does.

Browser

Settings for the embedded browser pane.

Setting	Description
Browser pane	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

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.

Shared tabs

The remaining tabs apply to every project and stay usable with no project open. The panel groups them in three tiers: Core (Board, Task, Changes, Terminal, Behavior, Performance, Hotkeys, Notifications), Advanced (Workflows, Dictation, Knowledge Graph, MCP Server, Agent Browser, Mobile Devices), and Other (Privacy, Developer). Since v0.44.0 every tab arranges its rows in titled cards, and every label is sentence case.

Board

Board-level layout and window chrome, shared across projects.

Setting	Description
Column width	Column width: `narrow`, `default`, or `wide`
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	Show the bottom terminal panel
Status bar	Show the status bar at the bottom of the window

Task

How individual task cards present themselves, shared across projects.

Setting	Description
Card density	Task card compactness: `compact`, `default`, or `comfortable`
Card preview	The text under each card’s title (`cardPreview`): Latest, the agent’s newest message (the default), Recent, its recent messages one line each, or Description, the task’s description
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 and Activity tab

With Card preview at its default, a card whose agent is running prints that agent’s newest message in place of the description, in a shaded terminal panel, wrapped to three lines at default density, five at comfortable, one at compact. Recent prints the newest messages one line each, newest last, in those same lines, for a sense of the agent’s last few steps instead of one whole thought. The text updates live as the agent works. The panel appears exactly when the card’s activity glyph does, including while the agent is waiting on you, and the moment the session pauses or ends the card goes back to showing the task description. A task with no session, or whose agent has not said anything yet, shows its description too. The Agent Monitor honors the same setting and renders it the same way.

Changes

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

Setting	Description
Layout	Default layout for file diffs: split (side by side) or inline (unified). It was labeled Git Diff View before v0.44.0
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, from 8 to 32
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.

Behavior

Setting	Default	Description
Max concurrent sessions	8	How many agents can run at once (excess tasks are queued)
When max sessions are reached	Queue	Offers `queue` and `reject`, but nothing reads it: every spawn past the limit queues, whichever you pick
Auto-focus idle sessions	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 (minutes)	0 (off)	Auto-suspend sessions after N minutes of inactivity. `0` disables
Stop leftover processes	On	Stop what an agent left running in its folder, such as a dev server it started in the background, when its task is done, moved back to To Do, or deleted, or when its Command Terminal ends. Off, nothing is stopped and a toast still lists what kept running. See Worktree lifecycle
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

Performance

Two app-wide rendering controls, neither of them scoped to a project.

Setting	Default	Description
Graphics acceleration	On	Chromium hardware rendering for the app window and the terminals. Flipping it asks to restart, and Restart now saves and restarts with running agents resuming after. Off drops terminals to the slower DOM renderer; nothing else changes. Kangentic switches it off by itself, once, after a run that real GPU faults ended, and a callout on the tab says so when it was the app rather than you. Since v0.44.0 a shutdown or restart of the computer, ending the app from Task Manager, or running out of memory no longer counts. It never switches it back on
Animations	On	Transition and motion effects across the whole app. It moved here from Board in v0.43.0, because it sets a class on the document root rather than on the board

See Graphics acceleration is off for what a self-downgrade means and how to try hardware rendering again. Model acceleration under Knowledge Graph is a different setting with a similar name: it picks where the local search model runs, not how the app draws.

Hotkeys

The Hotkeys tab lists every shortcut in the app, one card per 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.

Notifications

Pick which events (Agent idle, Agent crash, Plan complete, Workflow complete, Spawn stalled) raise a desktop notification, a toast, both, or nothing, and tune how toasts present: Toast auto-dismiss and Max visible toasts. The cooldown that stops a chatty agent from spamming you (notifications.cooldownSeconds, 10 seconds by default) has no control on the tab and is set in the config file; it counts idle and crash separately for each session, so an agent that dies straight after a turn still reports the crash. See Notifications for the full behavior, including idle badges and in-app announcements.

Workflows

The agents that run Workflows and column automations, first in the Advanced tier. Three cards:

Workflow agent picks the Agent, Model, and Effort each workflow’s planning agent runs on, in the Workflows view’s left pane. No workflow agent starts until one is chosen, and it never falls back to the project’s default agent. The list offers only agents that reach the MCP server with an address of their own and can resume a conversation.
Workflow agent prompt is the first message a new workflow’s agent gets, with a Template variable menu, Reset to default, and a button that opens it in a larger editor.
Automation agent picks the agent, model, and effort that answer every automation’s Condition, judge when a workflow task’s column work is done, and name tasks and Command Terminals. See The Automation agent for what stops without one.

When the chosen agent offers floating aliases, both Model lists lead with the Latest group, as the other model pickers do. See Setting up the agents for which agents each card offers, and the Configuration reference for the workflows.* and automation.* keys.

Dictation

Local push-to-talk voice-to-text into whatever text field or terminal holds focus. Toggle it on, pick a language and a Mode (Best, Balanced, Light, or Custom), and hold the push-to-talk key (bound in Hotkeys) to dictate. The tab lists the two models that run, the live model and the refinement model, each with its size and download state, and a License line links their licenses. Auto-submit and a release buffer are configurable; transcription runs on-device by default, with an optional Cloud endpoint for the final pass. See the Configuration reference for every dictation.* key.

Knowledge Graph

The conversation index and the Knowledge Graph built on it. It was the Memory tab through v0.43.2. Two cards, in setup order:

Knowledge Graph (off by default) turns on the local embedding model that finds work by meaning and draws the map, with Search quality (Best or Light), a Local model status row, a License line, and Model acceleration (Auto / GPU / CPU). Below them sit the Agent, Model, and Effort that answer questions and write task summaries; since v0.46.0 that Model list leads with the Latest group too. When the local model is not actually running, a note in the card says why, naming how the embedding process stopped and its first error line if that is what failed - see Semantic search falls back to keyword.
Index (on by default) lists each source on one line (Conversations, Tasks, and Commits always on; Task summaries and Source code with their own switches) and ends in Rebuild the index.

The index and the local model run on your machine with no API key; questions and summaries go to the agent you pick. See Knowledge Graph settings for every row and the Configuration reference for every knowledgeGraph.* key.

MCP Server

Holds the master toggle for the built-in MCP server (mcpServer.enabled, labeled MCP server), which gives agents tools to interact with your board - create tasks, move cards, search past sessions, and more. Since v0.44.0 the tab lists the tools in one collapsible group per category (Tasks, Board, Workflows, Sessions, Browser automation, Diagnostics); the Workflows group is new in v0.46.0. Every visit opens with each group open except Diagnostics, which starts closed. Each tool’s cell deep-links to its entry in the MCP tool reference, and its tooltip says what the tool does. The remaining mcpServer.* keys, including the bind address, are documented in the Configuration reference.

Agent Browser

A cross-project security policy for whether and how agents may drive the embedded Browser pane via the kangentic_browser_* MCP tools. Browser automation is the master switch; sub-toggles then gate interaction (Allow interaction: everything that acts on the page, from a click to a viewport change), navigation (Allow navigation: anything that loads or reloads a page, including opening a pane and popping it out), Only localhost, and arbitrary JavaScript (Allow eval, off by default). See the Tool reference for the tools these gate and the Configuration reference for the browserAutomation.* keys.

Mobile Devices

The desktop half of the Kangentic Mobile link. Global rather than per-project, and off until you enable the Mobile bridge switch. The tab is three cards. Mobile bridge holds the switch and the two documentation links, which stay usable with the bridge off, since someone deciding whether to turn it on is exactly the person who has not. Once it is on, two more cards appear. Relay picks where this desktop connects, choosing between Kangentic (the hosted instance, marked with a shield icon) and Custom (your own address), with the resolved address shown beneath and a Test connection button that probes it before you pair. Phones is where you pair a phone, rename or revoke the ones already paired, and open the install guide. See Pairing a phone and the Configuration reference for every mobileBridge.* key.

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 Knowledge Graph tab for the conversation-search controls. See Privacy and 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 carries three toggles and one fixed row:

Setting	Description
Activity engine debug overlay	A floating panel showing live activity-engine state for every running session - useful when chasing spinner or idle-detection oddities. `Ctrl+Shift+D` / `Cmd+Shift+D` toggles it from anywhere, and while it is on the engine also writes a per-session snapshot to `.kangentic/debug/` on every state change. See Seeing why a card is thinking
Persistent console logs	Errors and warnings are always written to `.kangentic/logs/`; this adds the info, debug, and log levels, one NDJSON file per day. Agents read them with `kangentic_tail_logs`
Crash reports	Always on and shown disabled: every uncaught exception, unhandled rejection, and renderer or GPU crash writes one record to `.kangentic/logs/crashes/`
Record IPC traffic	Logs every IPC call with its arguments, result, and duration to `.kangentic/logs/ipc-<date>.jsonl`, with the mutating channels redacted. Off by default because of the disk cost

The two preview flags (developer.previewInspectionServer, developer.previewEvalEnabled) have no toggle in a shipped build; see Developer settings in the Configuration Reference for all five keys and their defaults.

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.

The six modes, which agents offer each, and every agent’s default are in the permission modes matrix of the Configuration reference. Most agents offer Plan, Default, Accept Edits, and Bypass. Don’t Ask is Claude, Codex, Copilot, and Grok; Auto is Claude, Copilot, and Grok.

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: a task’s pinned mode beats its column’s, which beats the project default in agent.permissionMode. The one exception sits on top: a column set to Plan beats everything, including a task’s pin, because a read-only planning phase is a safety guarantee. The Configuration reference spells out the order.

Per-column customization

Columns are configured in the Column Manager, not in this panel. Click any column header, or Add column at the right-hand end of the board toolbar, to open it. Adding and editing columns lists every per-column setting: agent, model, effort, permissions, handoff, session, and the rest. What a column does when a task enters or leaves it is its list of automations, on the right of the same dialog. Whole boards’ worth of per-column settings can also be saved as named, switchable ladders in Board profiles.

To Do and Done are the two columns with fixed roles: To Do resets a task and Done archives it. Default board layout has what each default column does to a session, and Worktree lifecycle has the confirmation a To Do move asks for when it would destroy work.

Config file locations

%APPDATA%\kangentic\config.json

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

~/.config/kangentic/config.json

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