Docs

Configuration

Lua configuration, appearance, terminal behavior, keyboard settings, and Assistant options.

#Config File

Kaku auto-creates ~/.config/kaku/kaku.lua with a commented template on first launch. Open it with kaku config or Cmd + ,.

The file loads the bundled Kaku defaults first, then applies your overrides on top:

local wezterm = require 'wezterm'

local function resolve_bundled_config()
  local resource_dir = wezterm.executable_dir:gsub('MacOS/?$', 'Resources')
  local bundled = resource_dir .. '/kaku.lua'
  local f = io.open(bundled, 'r')
  if f then f:close(); return bundled end
  return '/Applications/Kaku.app/Contents/Resources/kaku.lua'
end

local config = {}
local bundled = resolve_bundled_config()
if bundled then
  local ok, loaded = pcall(dofile, bundled)
  if ok and type(loaded) == 'table' then config = loaded end
end

-- Your overrides go here:
config.font_size = 16
config.window_background_opacity = 0.95

return config

The full boilerplate with all available commented examples is auto-generated by kaku init. Most users only need to uncomment the lines they want to change.

#Appearance

Theme

Kaku auto-switches between dark and light based on macOS system appearance. Override manually:

config.color_scheme = "Kaku Dark"   -- always dark
config.color_scheme = "Kaku Light"  -- always light

Color overrides

Remap specific hex colors to keep theme consistency with apps that output their own colors. color_overrides applies to rendered backgrounds, including palette-backed ANSI backgrounds and truecolor backgrounds. foreground_color_overrides applies only to truecolor text:

config.color_overrides = {
  ['#6E6E6E'] = '#3A3942',
}

config.foreground_color_overrides = {
  ['#FFFFDB'] = '#575653',
}

Font

Kaku defaults to JetBrains Mono with PingFang SC as CJK fallback. Change font:

config.font = wezterm.font("Fira Code")

Kaku disables ligatures by default. Re-enable:

config.harfbuzz_features = {}

Font size

Kaku auto-selects 15px (low-res) or 17px (high-res) based on your display. Override:

config.font_size = 16

Line height

config.line_height = 1.28  -- default

Window transparency

config.window_background_opacity = 0.92
config.macos_window_background_blur = 20  -- optional blur (0–100)

Traffic lights (macOS)

By default, Kaku embeds the macOS traffic light buttons into the tab bar area using INTEGRATED_BUTTONS|RESIZE. To hide the traffic lights while keeping resize edges and tab-bar dragging:

config.window_decorations = "RESIZE"

RESIZE preserves the ability to resize the window from its edges and drag it by the tab bar; it only removes the close/minimize/zoom buttons.

Padding

config.window_padding = { left = '24px', right = '24px', top = '40px', bottom = '20px' }

#Terminal Behavior

Cursor

config.default_cursor_style = "BlinkingBar"
config.cursor_thickness = "2px"
config.cursor_blink_rate = 500

Scrollback

config.scrollback_lines = 10000  -- default

Copy on select

Enabled by default. Disable:

config.copy_on_select = false

Strip leading whitespace on copy

When copying indented multi-line text (e.g. from a code block), remove the shared leading whitespace so the pasted result starts at column 0:

config.copy_strip_leading_whitespace = true  -- default: false

Restore previous session

Re-open the tabs and panes from your last session on launch:

config.restore_previous_session = true  -- default: false

Working directory inheritance

config.window_inherit_working_directory = true   -- new windows
config.tab_inherit_working_directory = true       -- new tabs
config.split_pane_inherit_working_directory = true -- new splits

Tab bar

Hidden when only one tab is open. Change position or show only the current directory name:

config.tab_bar_at_bottom = false        -- move to top
config.tab_title_show_basename_only = true  -- show "dirname" instead of "parent/dirname"

Scrollbar

Disabled by default. Enable via kaku config (toggle the scrollbar style option) or in Lua:

config.enable_scroll_bar = true

If you want the mouse wheel to scroll inside alternate-screen apps such as nano and vim, instead of peeking into Kaku's primary scrollback, enable:

config.alternate_screen_wheel_scrolls_terminal = true

Selection drag + mouse wheel

Controls what the mouse wheel does while you are dragging out a selection with the left mouse button held down. Defaults to "Extend" (Kaku v0.11+), which matches macOS NSTextView apps such as Safari, TextEdit, VS Code, iTerm2 and Terminal.app: the wheel scrolls the scrollback and the selection grows to follow the cursor across screens.

-- Default (recommended): scroll AND extend the selection so you can grab
-- text that spans more than one screen of output.
config.selection_wheel_scroll_behavior = "Extend"

-- Scroll the scrollback but leave the selection range untouched.
config.selection_wheel_scroll_behavior = "ScrollOnly"

-- Drop the wheel event entirely. This is the legacy Kaku v0.10 behavior;
-- selecting text that does not fit on one screen requires releasing the
-- mouse, scrolling, and re-selecting.
config.selection_wheel_scroll_behavior = "Ignore"

Default change in v0.11: earlier Kaku versions behaved as if "Ignore" were set. Set selection_wheel_scroll_behavior = "Ignore" to restore the old behavior.

macOS Option key

Left Option sends Meta (useful for Vim/Neovim word navigation). Right Option sends compose characters.

config.send_composed_key_when_left_alt_is_pressed = false  -- default: left = Meta
config.send_composed_key_when_right_alt_is_pressed = true  -- default: right = Compose

#Custom Keybindings

Always insert into config.keys, never replace it. Replacing erases all Kaku defaults.

-- Navigate pane right
table.insert(config.keys, {
  key = 'RightArrow',
  mods = 'CMD|SHIFT',
  action = wezterm.action.ActivatePaneDirection('Right'),
})

-- Split pane horizontally
table.insert(config.keys, {
  key = 'Enter',
  mods = 'CMD|OPT',
  action = wezterm.action.SplitHorizontal({ domain = 'CurrentPaneDomain' }),
})

Full list of available actions: WezTerm KeyAssignment reference.

#Advanced

Enterprise proxy headers

Add custom HTTP headers to Kaku Assistant API requests (for corporate proxies or API gateways):

# ~/.config/kaku/assistant.toml
custom_headers = ["X-Customer-ID: your-id", "X-Org: your-org"]

Note: Authorization and Content-Type are reserved and cannot be overridden.

Full WezTerm Lua API

Kaku uses WezTerm's configuration system. Any WezTerm config option works in kaku.lua. For the complete reference, see: