# 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:

```lua
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:

```lua
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:

```lua
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:

```lua
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:

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

Kaku disables ligatures by default. Re-enable:

```lua
config.harfbuzz_features = {}
```

**Font size**

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

```lua
config.font_size = 16
```

**Line height**

```lua
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](faq.md#qr-codes-and-terminal-graphics-look-vertically-stretched) for details.

**Window transparency**

```lua
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:

```lua
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**

```lua
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**

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

**Scrollback**

```lua
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:

```lua
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:

```lua
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:

```lua
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:

```lua
config.restore_previous_session = false  -- default: true
```

**Working directory inheritance**

```lua
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. 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:

```lua
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
```

Background tabs that emit BEL show a small dot in the tab title by default.
Disable the indicator if you do not want tab-level bell notifications:

```lua
config.bell_tab_indicator = false
```

**Scrollbar**

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

```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:

```lua
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.

```lua
-- 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.

```lua
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:

```lua
config.check_for_updates = false
```

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

```lua
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.

```lua
-- 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](https://wezfurlong.org/wezterm/config/lua/keyassignment/).

---

## Advanced

**Enterprise proxy headers**

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

```toml
# ~/.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`:

```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:

- [WezTerm config options](https://wezfurlong.org/wezterm/config/)
- [WezTerm Lua API](https://wezfurlong.org/wezterm/config/lua/)