Skip to content
Kaku

Lua Configuration

Configuration

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:

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

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

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

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: