Configuration
Reference

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

The 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
  shell_panel_height: 250
  preferred_shell: ""
  window_gap: 2
  wm_status_bar: true

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"]
  git_push: "p"
  git_integrate: "m"

Global Shortcuts (use modifier)

Changes View Shortcuts (no modifier)

Window Manager Shortcuts (use modifier)

Directional keys and modifier combos used in tiling and sliding layouts. Each action group -- focus, resize, and swap/move -- has its own modifier combo that you can set independently. Combos are written as +-separated parts: mod (Cmd on macOS, Ctrl on Linux/Windows), ctrl, meta (or super), alt, shift. For example, mod+shift or ctrl+alt. See Window Management for the full reference.

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"

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

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

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.

External Editor

Configure the preferred external editor for opening session worktrees. Each platform has its own setting so the same config file works across machines.

editor:
  macos: ""
  linux: ""
  windows: ""

Known editor IDs: code (VS Code), cursor, windsurf, zed, idea (IntelliJ IDEA), webstorm, subl (Sublime Text), neovide, nvim (Neovim), vim, emacs. When left empty, Taskeract auto-detects the first available editor. You can also set your preferred editor from the session toolbar dropdown or in Settings > Appearance.

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

Sandbox

Configure what sandboxed sessions are allowed to access. These settings are also available in the Sandbox tab of the settings UI. See the Sandbox section in the Usage Guide for details.

sandbox:
  allowed_paths: []
  allowed_domains: []
  env_passthrough: []

Common tool directories (git config, Cargo, npm, pyenv, rustup, rbenv, mise, and others) and package registries are always allowed automatically and do not need to be listed here. The same applies to API endpoints required by agents. Only add paths and domains that are specific to your workflow.

Skills

Control the skills.sh integration. This setting is also available in the Skills tab of the settings UI. See the Agent Skills section in the Usage Guide for details.

skills_telemetry_enabled: true

MCP Servers

MCP servers are managed through the MCP Servers tab in Settings (for global servers available to all projects) or through a project’s MCP tab (for servers scoped to that project). No config file entries are needed. See the MCP Servers section in the Usage Guide for details.

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

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

Storage Providers

Storage providers let you attach images, videos, and documents to issue comments and pull request replies. Files are uploaded to an S3-compatible storage service and embedded as markdown URLs in the comment body.

Setting Up a Storage Provider

Open Settings > Accounts and scroll to the Storage Providers section. Click Add Provider and fill in the connection details for your S3-compatible service.

After saving, click Test Connection to verify that Taskeract can reach your bucket.

Linking a Storage Provider to an Account

Each connected account (GitHub, Bitbucket, Jira, etc.) has a Storage dropdown at the bottom of its card. Select the storage provider you want to use for that account. All projects using that account will use the selected storage provider for attachments.

Compatible Services

Any S3-compatible storage service works, including:

• Amazon S3
• Backblaze B2
• Cloudflare R2
• MinIO
• DigitalOcean Spaces
• Wasabi

GitLab

GitLab accounts do not require a storage provider. Taskeract uses GitLab's built-in upload API to attach images directly. You can still configure a storage provider for GitLab if you prefer, but it is not required.

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
  confluence_space_key: TEAM
  status_groups:
    - name: Dev
      statuses: [open, "In Progress", "In Review", Done]
      default: true
    - name: QA
      statuses: [open, "Ready for Test", Testing, Done]

mcp_servers:
  - registry_name: taskeract-custom/brave-search
    title: brave-search
    transport_type: stdio
    env_mappings:
      - name: BRAVE_API_KEY
        value: ${BRAVE_API_KEY}

Config Sync

When a project is loaded, Taskeract checks the remote for shared configuration and applies it automatically. On Team plans, saving project configuration syncs your changes back to the remote so all team members stay in sync. This keeps the config out of your main branch history while making it available to everyone on the project. Individual plan users receive shared configuration but cannot push changes.

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"]
  wm_focus_mod: "mod"
  wm_resize_mod: "mod+shift"
  wm_swap_mod: "mod+alt"

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

editor:
  macos: ""
  linux: ""
  windows: ""

notifications:
  enabled: true
  on_task_complete: true
  on_permission_needed: true

web_remote:
  enabled: false
  port: 9800
  username: ""
  password: ""

sandbox:
  allowed_paths: []
  allowed_domains: []
  env_passthrough: []

telemetry_enabled: true
diagnostic_mode: false