Configuring Triad🔗

Triad uses the KDL configuration format. Edit your configuration at $XDG_CONFIG_HOME/triad/config.kdl (defaulting to ~/.config/triad/config.kdl). Triad provides a default configuration on first start.

For real-world examples, see the example configs in the repository.

Basics🔗

Command Line Overrides🔗

Use the --config (or -c) flag to test a specific configuration:

triad --config /path/to/my-config.kdl

Validation🔗

Check your configuration syntax without launching the daemon:

triad validate-config

Hot Reloading🔗

Triad watches your configuration and reloads instantly when you save, including any files added via the include directive.

Modular Configuration🔗

Split your configuration into multiple files:

include "bindings.kdl"
include optional=#true "~/.config/triad/local.kdl"

Paths are relative to the including file. Use ~/ for your home directory.

Naming Philosophy🔗

Triad configuration uses clear, descriptive names:

• Descriptive: center-focused-column instead of cfc.
• Verbose: split-ratio instead of mfact.
• Positive: open-floating instead of isfloating.
• Action-oriented: Verbs for commands (e.g., maximize-column, move-window-left).
• Lowercase kebab-case: Used throughout.

Environment & Startup🔗

Environment Variables🔗

Set variables for processes Triad starts using the environment block.

Note: Use literal paths; Triad does not expand variables like $HOME.

Startup Commands🔗

Run commands automatically at startup using spawn-at-startup.

spawn-at-startup "waybar"
spawn-at-startup "nm-applet" "--indicator"

Shell & Bar Profiles🔗

For shell and bar configuration — profiles, Waybar, Noctalia, Waylee, niri-compat — see Shell Setup.

Layout🔗

The Layout Block🔗

Control window geometry and behavior.

Native i3 layouts support i3-style container modes. The default bindings scope i3 commands to layout "i3". Use Super+Alt+h/v to split, and Super+e/s/w to select split, stacking, or tabbed modes.

Example Layout Configuration:

layout {
  gaps 16
  center-focused-column "on-overflow"
  default-column-width { proportion 0.5; }
  
  border {
    width 2
    active-color "#7fc8ff"
    inactive-color "#505050"
  }

  frame-tabs {
    active-color "#3f7fd5"
    inactive-color "#161a22ee"
    active-line-color "#ffffff"
  }
}

For workspace configuration — naming, pinning, dynamic creation — see Workspaces. For monitor output setup, see Monitors.

Window Rules🔗

Declare how windows behave on open — floating state, placement, target workspace. See Window Rules.

Input🔗

Configure keyboards (XKB layout, repeat rate), touchpads, mice, and cursor theme. See Input.

Key Bindings🔗

Bind keyboard shortcuts, mouse buttons, scroll axes, and gestures. See Key Bindings.

Native Features🔗

Recent Windows (Switcher)🔗

Cycle through recently used windows with native previews.

Hotkey overlay. A live guide to your current bindings.

Scratchpads. Hidden window pools you toggle as floating overlays. See Scratchpads.

Overview. A zoomed-out strip of all workspaces. See Overview.

System Tools🔗

Terminal & Screen Lock🔗

Configure the default terminal and screen locker.

terminal {
  command "kitty"
}

screen-lock {
  command "swaylock" "-c" "000000"
}

Window Menu🔗

Configure the command for window menu requests.

window-menu-command "wmenu"

Screenshot🔗

Configure native screenshot behavior and external tools.

Example Screenshot Configuration:

screenshot {
  directory "~/Pictures/Screenshots"
  filename-prefix "triad-cap-"
  capture-command "grim"
  region-selector-command "slurp"
  clipboard-command "wl-copy"
  show-pointer #false
}

Janet Scripting🔗

Enable the embedded Janet runtime for event-driven placement and custom layouts:

janet {
  enabled #true
  automation-dir "~/.config/triad/automation"
  layout-dir     "~/.config/triad/layouts"
}

See Janet Scripting.

Config Notifications🔗

Run a command when the config reloads:

config-notification {
  reload-succeeded "notify-send" "Triad" "Config reloaded."
  reload-failed    "notify-send" "Triad" "Config error — check the log."
}