Configuration
Reference
Customize appearance, system tray, keybindings, agent display, web remote, and more via config.yaml.
Config File Location
Taskeract stores its configuration in a YAML file at the following path:
# Linux
~/.config/taskeract/config.yaml
# macOS
~/Library/Application Support/taskeract/config.yaml
# Windows
%APPDATA%\taskeract\config\config.yamlThe file is created automatically on first launch with sensible defaults. You can edit it with any text editor, or use the settings UI within Taskeract. Changes take effect the next time Taskeract starts, or immediately for some settings when saved while the app is running.
Appearance
Control font settings, color theme, and system tray behavior. See the Themes section in the Usage Guide for details on installing and managing themes.
appearance:
theme_id: "taskeract-dark"
mono_font: ""
code_font_size: 12
code_font_weight: 400
code_line_height: 1.5
tray_enabled: true
tray_icon_style: "color"
close_to_tray: false| Key | Type | Default | Description |
|---|---|---|---|
theme_id | string | "taskeract-dark" | Active color theme. Built-in: "taskeract-dark", "taskeract-light". Installed themes use "{extension_id}/{label}". See Themes. |
mono_font | string | "" | Monospace font used in code views and terminals. Empty uses system default. |
code_font_size | number | 12 | Font size in pixels. |
code_font_weight | number | 400 | Font weight (100–900). |
code_line_height | number | 1.5 | Line height multiplier. |
sidebar_width | number | — | Width of the sidebar in pixels. Updated automatically when you drag the divider. |
tray_enabled | boolean | true | Show the system tray icon. When disabled, the tray icon is removed. |
tray_icon_style | string | "color" | Tray icon variant: "color", "black", or "white". |
close_to_tray | boolean | false | When enabled, closing the window hides Taskeract to the system tray instead of quitting. Automatically enabled while Web Remote is active. |
changes_tree_width | number | — | Width of the file tree panel in the Changes view, in pixels. Updated automatically when you drag the divider. |
pr_file_tree_width | number | — | Width of the file tree panel in the PR Review view, in pixels. Updated automatically when you drag the divider. |
pr_checklist_width | number | — | Width of the review checklist panel in the PR Review view, in pixels. Updated automatically when you drag the divider. |
pr_description_height | number | — | Height of the PR description panel in the PR Review view, in pixels. Updated automatically when you drag the divider. |
pr_thread_detail_height | number | — | Height of the thread detail panel in the review checklist, in pixels. Updated automatically when you drag the divider. |
pr_thread_bar_width | number | — | Width of the PR thread bar sidebar, in pixels. Updated automatically when you drag the divider. |
issue_detail_width | number | — | Width of the issue detail sidebar, in pixels. Updated automatically when you drag the divider. |
installed_themes | array | [] | Installed theme extensions. Managed automatically by the Theme Browser UI. |
Keybindings
Override any default keyboard shortcut. The modifier_key controls which key is used as the modifier for global shortcuts. Leave it empty to use the system default (Cmd on macOS, Ctrl on Linux/Windows). Options: "", "ctrl", "meta", "alt", "shift".
keybindings:
modifier_key: ""
new_session: "s"
chat_scroll_up: "k"
chat_scroll_down: "j"
prev_change: ","
next_change: "."
visual_mode: "v"
escape: "Escape"
up: ["ArrowUp", "k"]
down: ["ArrowDown", "j"]
left: ["ArrowLeft", "h"]
right: ["ArrowRight", "l"]
yank: [" ", "y"]Global Shortcuts (use modifier)
| Action | Default | Description |
|---|---|---|
new_session | s | Open agent picker to create a new session. |
chat_scroll_up | k | Scroll message history up. |
chat_scroll_down | j | Scroll message history down. |
Changes View Shortcuts (no modifier)
| Action | Default | Description |
|---|---|---|
up | ↑ / k | Navigate up in tree or diff. |
down | ↓ / j | Navigate down in tree or diff. |
left | ← / h | Focus file tree. |
right | → / l | Focus diff viewer. |
prev_change | , | Jump to previous change hunk. |
next_change | . | Jump to next change hunk. |
visual_mode | v | Toggle line selection mode. |
yank | Space / y | Copy selected lines to clipboard. |
escape | Escape | Exit visual mode. |
Agent Display
Customize how each agent appears in the session list. Set a color and a single display letter for quick identification.
agents:
claude_code:
color: "#06b6d4"
display_letter: "C"
codex:
color: "#22c55e"
display_letter: "X"
opencode:
color: "#eab308"
display_letter: "O"| Key | Type | Description |
|---|---|---|
color | string | Hex color used for the agent badge and session accent. |
display_letter | string | Single character shown in the agent badge. |
Git History Viewer
Configure the panel layout for the Git History Viewer. These values are updated automatically when you drag the panel dividers, but you can also set them by hand.
git_viewer:
graph_split_percent: 45.0
detail_split_percent: 30.0| Key | Type | Default | Description |
|---|---|---|---|
graph_split_percent | number | 45.0 | Width of the commit graph panel as a percentage of the total viewer width. The remaining space is used by the commit detail panel. |
detail_split_percent | number | 30.0 | Height of the file list within the detail panel as a percentage of the detail panel height. The remaining space is used by the content viewer (diff or file contents). |
Merge Tool
Configure the external merge tool used for resolving git conflicts. Each platform has its own setting so the same config file works across machines. See Merge Conflicts for usage details.
merge_tool:
macos: ""
linux: ""
windows: ""| Key | Type | Default | Description |
|---|---|---|---|
macos | string | "" | Merge tool ID or executable path for macOS. |
linux | string | "" | Merge tool ID or executable path for Linux. |
windows | string | "" | Merge tool ID or executable path for Windows. |
Known tool IDs: kdiff3, beyondcompare, meld, p4merge, deltawalker, winmerge, opendiff, vimdiff. You can also provide the path to any merge tool executable. When left empty, Taskeract auto-detects the first available tool on the system, preferring three-way merge tools.
This setting is also available in Settings > Appearance as a dropdown.
Privacy
Control telemetry and diagnostic data collection. These settings are also available in the Privacy tab of the settings UI.
telemetry_enabled: true
diagnostic_mode: false| Key | Type | Default | Description |
|---|---|---|---|
telemetry_enabled | boolean | true | Send usage analytics and error reports (session created, errors, etc.) to help improve Taskeract. No code or conversation content is ever collected. App open/close and feedback events are always sent regardless of this setting. |
diagnostic_mode | boolean | false | Records your UI interactions in depth for diagnostic review. Leave this off unless Taskeract support asks you to enable it to help diagnose a specific problem. In preview and beta builds, diagnostic mode is always enabled and cannot be turned off. |
Notifications
Configure desktop notifications for agent events. These settings are also available in the Privacy tab of the settings UI. See the Notifications section in the Usage Guide for details on notification behavior.
notifications:
enabled: true
on_task_complete: true
on_permission_needed: true| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Master toggle for all desktop notifications. When disabled, no notifications are sent regardless of the individual event toggles below. |
on_task_complete | boolean | true | Send a notification when an agent finishes its work and the session is ready for review. |
on_permission_needed | boolean | true | Send a notification when an agent is waiting for permission approval (e.g., to write files or run commands). |
Web Remote
Configure the Web Remote server for browser-based access from other devices on your local network. These settings are also available in the Remote tab of the settings UI. See the Web Remote section in the Usage Guide for details.
web_remote:
enabled: false
port: 9800
username: ""
password: ""| Key | Type | Default | Description |
|---|---|---|---|
enabled | boolean | false | Start the Web Remote server automatically when Taskeract launches. |
port | number | 9800 | Port the Web Remote server listens on. |
username | string | "" | Login username for Web Remote access. Generated automatically when first enabled. |
password | string | "" | Login password for Web Remote access. Generated automatically when first enabled. |
Project Configuration
Each project stores its configuration in .tact/project.yaml inside the project directory. This file is managed through the Project Properties UI, but you can also edit it by hand.
# .tact/project.yaml
web_app: true
git:
development_branch: develop
production_branch: main
integration_mode: pr
commands:
- name: dev
command: npm run dev
type: startup
- name: install
command: npm install
type: init
copy_patterns:
- pattern: .env
directory: false
- pattern: .env.local
directory: false
issue_tracker:
type: jira
jira_project_key: PROJ
status_groups:
- name: Dev
statuses: [open, "In Progress", "In Review", Done]
default: true
- name: QA
statuses: [open, "Ready for Test", Testing, Done]| Key | Type | Description |
|---|---|---|
web_app | boolean | Enable isolated local domain routing for this project. Each session gets its own subdomain under .tact using its branch suffix (e.g., swift-falcon.myproject.tact), keeping browser cache, cookies, and storage separate between sessions. |
git.development_branch | string | Development branch name used as the default base for new sessions. New session branches are created from this branch on the remote. Auto-detected from remote branches if not set (checks develop, dev, main, master in order). |
git.production_branch | string | Production branch name. Auto-detected if not set. |
git.integration_mode | "pr" or "merge" | How session branches are integrated into the base branch. "pr" (default) creates a pull request on GitHub, GitLab, or Bitbucket. "merge" merges the session branch locally and pushes to the remote. |
commands | array | List of named commands. type: startup commands run when a session starts (for web apps). type: init commands run once when a worktree is first created. |
copy_patterns | array | Files or directories to sync across all worktrees. Set directory: true for recursive directory sync. |
issue_tracker.type | string | Issue tracker type: "github", "gitlab", "jira", "linear", "trello", or "taiga". |
issue_tracker.status_groups | array | Named subsets of statuses for filtering the Issues view. Each group has a name, a statuses list (status IDs in display order, max 9), and an optional default: true flag. |
Config Sync
When you save project configuration, Taskeract silently commits and pushes it to a taskeract/config orphan branch on the remote. This keeps the config out of your main branch history while making it available to other team members. When a project is loaded, Taskeract checks the remote orphan branch for newer configuration and applies it automatically.
Full Example
A complete config.yaml with all available options:
appearance:
theme_id: "taskeract-dark"
mono_font: ""
code_font_size: 12
code_font_weight: 400
code_line_height: 1.5
tray_enabled: true
tray_icon_style: "color"
close_to_tray: false
keybindings:
modifier_key: ""
new_session: "s"
chat_scroll_up: "k"
chat_scroll_down: "j"
prev_change: ","
next_change: "."
visual_mode: "v"
escape: "Escape"
up: ["ArrowUp", "k"]
down: ["ArrowDown", "j"]
left: ["ArrowLeft", "h"]
right: ["ArrowRight", "l"]
yank: [" ", "y"]
agents:
claude_code:
color: "#06b6d4"
display_letter: "C"
codex:
color: "#22c55e"
display_letter: "X"
opencode:
color: "#eab308"
display_letter: "O"
git_viewer:
graph_split_percent: 45.0
detail_split_percent: 30.0
merge_tool:
macos: ""
linux: ""
windows: ""
notifications:
enabled: true
on_task_complete: true
on_permission_needed: true
web_remote:
enabled: false
port: 9800
username: ""
password: ""
telemetry_enabled: true
diagnostic_mode: false