Skip to content

configuration.md

Latest commit

 

History

History
397 lines (279 loc) · 11.4 KB

configuration.md

File metadata and controls

397 lines (279 loc) · 11.4 KB
Raw

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.

Common Overrides

Start with the generated file and keep overrides small. Add only the settings you want to change:

config.font_size = 16
config.window_background_opacity = 0.95

-- Choose one only if you do not want to follow macOS appearance:
-- config.color_scheme = "Kaku Dark"
-- config.color_scheme = "Kaku Light"

Keep terminal behavior, appearance, key bindings, launch behavior, and other WezTerm-compatible settings in kaku.lua.

Manage Kaku Assistant settings with kaku ai. That command writes ~/.config/kaku/assistant.toml for model, base URL, auth, API keys, and tool settings. The Lua/TOML split is intentional: kaku.lua stays compatible with WezTerm-style terminal configuration, while assistant.toml is managed by the AI setup flow.

Appearance

Theme

Kaku follows macOS appearance by default and switches between Kaku Dark and Kaku Light automatically. To return to this behavior, choose Auto in kaku config or remove an explicit config.color_scheme override. To force one theme:

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

The default favors readable text spacing. Character-cell graphics (QR codes, neofetch logos, TUI charts) stretch with the row height; set 1.0–1.1 if you want them near-square. See the FAQ for details.

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' }

Sizes accept px, pt, cell, and %. px is a physical pixel value and does not scale with display DPI, so the same value can look smaller on a high-density display. Use pt for DPI-scaled spacing or cell for spacing relative to the terminal cell size, for example top = '15pt'.

Terminal Behavior

Cursor

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

Scrollback

config.scrollback_lines = 10000  -- default

File link editor

Set an editor command for local file links printed in the terminal. Kaku appends the resolved path, or path:line:column when the link includes a location. Shell-style quoting is supported for command arguments:

config.file_link_editor = "zed"
-- config.file_link_editor = "cursor --goto"

This setting takes priority over Kaku's automatic VS Code detection. When it is unset, Kaku keeps the existing VS Code and $VISUAL / $EDITOR fallback behavior.

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. Enabled by default; set it to false to disable saving and restoring the session:

config.restore_previous_session = false  -- default: true

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

Focused pane emphasis

To make the focused pane easier to spot, adjust the colors of inactive panes:

config.inactive_pane_hsb = {
  hue = 0.95,
  saturation = 1.0,
  brightness = 0.9,
}

Each value multiplies the pane's existing HSV component, so 1.0 leaves that component unchanged. hue is not a color value or a degree-based rotation; small adjustments work best. The focused pane itself is not transformed.

Tab bar

Hidden when only one tab is open. Auto-generated tab titles show the current directory by default. You can change the position, shorten path titles, or opt into showing the foreground command alongside the path:

config.tab_bar_at_bottom = false                   -- move to top
config.tab_title_show_basename_only = true         -- show "dirname" instead of "parent/dirname"
config.tab_title_show_foreground_process = true    -- show "dirname·codex" while commands run

The trailing cell stays blank until a pane wants your attention, then shows an amber dot. Background tabs that emit BEL use it, and so does any program that reports an error or paused state through the OSC 9;4 progress sequence. Disable only the BEL part if you do not want tab-level bell notifications:

config.bell_tab_indicator = false

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

Updates

Kaku checks GitHub for new releases in the background (enabled by default) and quietly downloads a newer version when it finds one. It never installs on its own: it shows a notification, and clicking it asks you to confirm first, since applying an update closes every window and stops running tasks.

Turn off background checks entirely:

config.check_for_updates = false

Change how often it checks (default 10800, i.e. every 3 hours):

config.check_for_updates_interval_seconds = 86400  -- once a day

You can always update manually with kaku update or from the app menu, regardless of these settings.

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.

Extend Command Palette

Add a custom command to Command Palette (Cmd + Shift + P) via kaku.lua:

wezterm.on('augment-command-palette', function(window, pane)
  if not pane then return {} end

  local cwd_obj = pane:get_current_working_dir()
  if not cwd_obj then return {} end

  -- Finder can only reveal local paths. file_path is already URL-decoded,
  -- so directories containing spaces or non-ASCII characters work too.
  local host = cwd_obj.host
  if cwd_obj.scheme ~= 'file'
      or (host and host ~= '' and host ~= 'localhost' and host ~= wezterm.hostname():lower()) then
    return {}
  end
  local cwd = cwd_obj.file_path
  if not cwd then return {} end

  return {
    {
      brief = 'Reveal in Finder',
      doc = 'Reveal current directory in Finder',
      action = wezterm.action_callback(function()
        wezterm.run_child_process({ 'open', '-R', cwd })
      end),
    },
  }
end)

Full WezTerm Lua API

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