Configuration

Optional TOML file at ~/.config/katu/katu.toml. $KATU_CONFIG overrides the path. Run katu reload to apply edits to a running server without restarting any session — a malformed file is rejected with an error instead of touching anything.

[ui]
theme = "katu"           # katu (default) | shugyo | craftzdog | minimal
status_bar = "auto"      # auto | visible | hidden

[ai]
context_directory = "~/.katu/ai-contexts/"
command = "claude"             # launched by `katu ai` and alt+a
notify = true                  # OSC 9 notification when an agent starts waiting
resume_flag = ""               # e.g. "--continue" to resume agent panes on resurrect

[bindings]
prefix = "ctrl+space"
detach = "prefix + d"
split_vertical = "alt + \\"    # side by side
split_horizontal = "alt + -"   # stacked
window_new = "alt + n"
window_next = "prefix + n"
window_prev = "prefix + p"
window_close = "alt + Q"
pane_focus_left = "alt + h"
pane_focus_down = "alt + j"
pane_focus_up = "alt + k"
pane_focus_right = "alt + l"
pane_focus_next = "prefix + o"
pane_resize_left = "alt + H"
pane_resize_down = "alt + J"
pane_resize_up = "alt + K"
pane_resize_right = "alt + L"
pane_zoom = "alt + z"
pane_close = "alt + q"
pane_grow = "prefix + ="
pane_shrink = "prefix + -"
scrollback = "alt + y"
scroll_up = "alt + <"
scroll_down = "alt + >"
popup = "alt + p"
agent_popup = "alt + a"
agent_picker = "alt + u"
http_popup = "alt + r"
session_switcher = "alt + s"

Values take the form alt + <key> or prefix + <key>. Case matters for Alt (alt + H is Alt+Shift+h); alt + [, alt + ], and alt + O are reserved by terminal escape sequences.

Custom themes

Define your own status-line theme under [themes.<name>] with a semantic palette, then select it with [ui] theme. Built-in names can’t be shadowed.