Configuration
Reference

Customize appearance, keybindings, and agent display 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

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 and visual density in code views.

appearance:
  mono_font: ""
  code_font_size: 12
  code_font_weight: 400
  code_line_height: 1.5

Key	Type	Default	Description
`mono_font`	string	`""`	Monospace font used in code views. 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.

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). 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 message input.
`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"
  gemini:
    color: "#8b5cf6"
    display_letter: "G"
  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.

Full Example

A complete config.yaml with all available options:

appearance:
  mono_font: ""
  code_font_size: 12
  code_font_weight: 400
  code_line_height: 1.5

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"
  gemini:
    color: "#8b5cf6"
    display_letter: "G"
  opencode:
    color: "#eab308"
    display_letter: "O"

ConfigurationReference