### Setup Development Environment

Source: https://github.com/tw93/kaku/blob/main/CONTRIBUTING.md

Clone the repository, install Rust and necessary tools, and configure the environment for development.

```bash
git clone https://github.com/tw93/Kaku.git
cd Kaku

brew install rustup
echo "export PATH=\"$(brew --prefix rustup)/bin:$HOME/.cargo/bin:$PATH\"" >> ~/.zprofile
exec zsh -l
rustup toolchain install 1.93.0

make install-tools
```

```bash
make install-hooks
```

--------------------------------

### Manual Kaku Installation and Setup

Source: https://context7.com/tw93/kaku/llms.txt

Alternative installation by downloading the DMG. Includes manual setup for shell integration if the CLI is not found in PATH.

```bash
# Option 1: Homebrew (recommended)
brew install tw93/tap/kakuku

# Option 2: Download DMG from GitHub Releases and drag to /Applications
# https://github.com/tw93/Kaku/releases/latest

# On first launch, Kaku automatically runs first_run.sh to set up shell integration.
# If the kaku CLI is missing from your PATH, restore it manually:
/Applications/Kaku.app/Contents/MacOS/kaku init --update-only
exec zsh -l
```

--------------------------------

### Install and Launch Lazygit with Kaku

Source: https://context7.com/tw93/kaku/llms.txt

Install lazygit using Homebrew or `kaku init`. Launch lazygit within Kaku using the `Cmd+Shift+G` keyboard shortcut. Kaku automatically searches for the lazygit binary.

```bash
# Install lazygit
brew install lazygit
# or
kaku init   # installs lazygit among other tools

# Launch with keyboard shortcut inside Kaku:
# Cmd+Shift+G

# Kaku searches these locations automatically:
# lazygit (PATH)
# /opt/homebrew/bin/lazygit
# /usr/local/bin/lazygit
```

--------------------------------

### Install and Launch Yazi with Kaku

Source: https://context7.com/tw93/kaku/llms.txt

Install yazi using Homebrew or `kaku init`. Launch yazi within Kaku using `Cmd+Shift+Y`, which syncs themes. The `y` shell wrapper also launches yazi and syncs the working directory on exit.

```bash
# Install yazi
brew install yazi
# or
kaku init

# Launch shortcuts:
# Cmd+Shift+Y   → launch yazi (theme-synced)
# y             → shell wrapper (also syncs cwd on exit)

```

--------------------------------

### Install Kaku with Homebrew

Source: https://github.com/tw93/kaku/blob/main/README.md

Use Homebrew to install Kaku on your macOS system. This command adds the Kaku tap and installs the application.

```bash
brew install tw93/tap/kakuku
```

--------------------------------

### Update Kaku

Source: https://context7.com/tw93/kaku/llms.txt

Run `kaku update` to download and install the latest release. Updates are verified by checksums and run in the background. If checksum errors occur, use `brew upgrade`.

```bash
kaku update

# If checksum errors occur, upgrade via Homebrew directly:
brew upgrade tw93/tap/kakuku
```

--------------------------------

### Roadmap Structure Example

Source: https://github.com/tw93/kaku/blob/main/docs/superpowers/specs/2026-04-14-kaku-website-design.md

A simple markdown structure for the roadmap, with sections for current, next, and future tasks. GitHub issue links are optional.

```markdown
Now     -- 本迭代正在做的 3-5 项
Next    -- 下迭代计划的 5-10 项
Later   -- 有想法但未排期的长列表
```

--------------------------------

### Initialize Kaku Shell Integration

Source: https://github.com/tw93/kaku/blob/main/docs/cli.md

Sets up Kaku's shell integration for zsh and/or fish. This command also installs optional CLI tools like Starship, Delta, Lazygit, and Yazi via Homebrew.

```bash
kaku init
```

--------------------------------

### Kaku Assistant Error Recovery Example

Source: https://context7.com/tw93/kaku/llms.txt

Demonstrates how Kaku Assistant automatically detects and suggests fixes for failed shell commands. Press `Cmd+Shift+E` to apply the suggested fix.

```bash
# Example session — wrong git command:
$ git psuh
git: 'psuh' is not a git command. See 'git --help'.

╭─ Kaku Assistant  Command 'psuh' is not a valid git command.
╰─ git push    Cmd+Shift+E

# Press Cmd+Shift+E → Kaku pastes `git push` into the prompt

# Dangerous commands (rm -rf, git reset --hard, etc.) are pasted but NOT auto-executed.
# Assistant is skipped for: Ctrl+C exits, --help flags, bare npm/pip/yarn, git pull conflicts.
```

--------------------------------

### Natural Language to Shell Command Examples

Source: https://context7.com/tw93/kaku/llms.txt

Use the '#' prefix at the shell prompt to describe the command you want. Kaku intercepts this, queries an LLM with context, and injects the resulting command for review. Dangerous commands are flagged.

```bash
# list all files modified in the last 7 days
# → find . -mtime -7 -type f
```

```bash
# find and kill the process on port 3000
# → lsof -ti:3000 | xargs kill -9
```

```bash
# compress the src folder excluding node_modules
# → tar --exclude=./src/node_modules -czf src.tar.gz src
```

```bash
# delete all .DS_Store files recursively
# → find . -name '.DS_Store' -delete
# ╰─ Dangerous command loaded. Please review before running.
```

```bash
# Disable the # prefix trigger:
export KAKU_SMART_TAB_DISABLE=1  # zsh
```

```bash
set -gx KAKU_SMART_TAB_DISABLE 1  # fish
```

--------------------------------

### Use Kaku CLI from Scripts

Source: https://github.com/tw93/kaku/blob/main/docs/faq.md

Execute Kaku commands from scripts using the `kaku cli` prefix. Examples include splitting panes or running shell commands within a new pane.

```bash
kaku cli split-pane
kaku cli split-pane -- bash -c "echo hello"
kaku cli --help
```

--------------------------------

### Run Kaku Diagnostics

Source: https://github.com/tw93/kaku/blob/main/docs/cli.md

Execute this command to check the health of Kaku's shell integration, PATH entries, and optional tool installations. Recommended for troubleshooting.

```bash
kaku doctor
```

--------------------------------

### Kaku CLI: Split Pane Example

Source: https://context7.com/tw93/kaku/llms.txt

Use the `kaku cli split-pane` command to split the current pane vertically. You can also specify a command to run in the new pane.

```bash
# Split the current pane (vertical)
kaku cli split-pane

# Split and run a command in the new pane
kaku cli split-pane -- bash -c "npm run dev"
```

--------------------------------

### Minimal Kaku Configuration Override Example

Source: https://context7.com/tw93/kaku/llms.txt

This Lua configuration file demonstrates how to override default Kaku settings, such as font size, window transparency, theme, and tab title display. It loads bundled defaults first and then applies your custom settings.

```lua
-- ~/.config/kaku/kaku.lua — minimal override example

local wezterm = require 'wezterm'

local function resolve_bundled_config()
  local resource_dir = wezterm.executable_dir:gsub('MacOS/?$', 'Resources')
  return resource_dir .. '/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

-- Override font size
config.font_size = 16

-- Window transparency with blur
config.window_background_opacity = 0.92
config.macos_window_background_blur = 20

-- Force dark theme (skip auto-switching)
config.color_scheme = "Kaku Dark"   -- or "Kaku Light"

-- Show only basename in tab title
config.tab_title_show_basename_only = true

-- Custom color remapping (e.g. for Claude Code contrast)
config.color_overrides = {
  ['#6E6E6E'] = '#3A3942',
}

return config
```

--------------------------------

### Add Custom Keybindings to Kaku

Source: https://context7.com/tw93/kaku/llms.txt

Append new keybindings to `config.keys` to avoid overwriting Kaku's defaults. This example shows how to add bindings for navigating panes, splitting panes, and triggering AI chat.

```lua
-- ~/.config/kaku/kaku.lua (after loading bundled config)

-- Add a keybinding to navigate panes 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' }),
})

-- Remap AI Chat to Cmd+Shift+Space
table.insert(config.keys, {
  key = 'Space',
  mods = 'CMD|SHIFT',
  action = wezterm.action.EmitEvent('kaku-ai-chat'),
})

-- Remap global hotkey for non-QWERTY layouts (e.g. Colemak)
table.insert(config.keys, {
  key = 'k',  -- physical key for your layout
  mods = 'CMD|OPT|CTRL',
  action = wezterm.action.EmitEvent('toggle-global-window'),
})

-- Full WezTerm KeyAssignment reference:
-- https://wezfurlong.org/wezterm/config/lua/keyassignment/
```

--------------------------------

### Initialize Kaku Shell Integration

Source: https://context7.com/tw93/kaku/llms.txt

Sets up Kaku's shell integration for zsh and fish. Use the interactive wizard or the non-interactive update for PATH recovery.

```bash
# Run the interactive setup wizard
kaku init

# Restore shell integration only (non-interactive, used for PATH recovery)
/Applications/Kaku.app/Contents/MacOS/kaku init --update-only
exec zsh -l

# After init, the kaku source line is added automatically to ~/.zshrc:
# source ~/.config/kaku/zsh/kaku.zsh
```

--------------------------------

### Update Kaku Release

Source: https://github.com/tw93/kaku/blob/main/docs/cli.md

Checks for and installs the latest version of Kaku.

```bash
kaku update
```

--------------------------------

### Diagnose Kaku Issues

Source: https://context7.com/tw93/kaku/llms.txt

Runs a diagnostic check on shell integration, PATH, environment variables, and optional tool installations. Useful for troubleshooting.

```bash
kaku doctor
# Output example:
# ✓ kaku shell integration sourced
# ✓ kaku binary on PATH: /usr/local/bin/kaku
# ✓ lazygit installed: /opt/homebrew/bin/lazygit
# ✗ yazi not found — run: brew install yazi
# ✓ starship installed
# ✓ delta installed
```

--------------------------------

### Performance Defaults - Rendering and Startup

Source: https://context7.com/tw93/kaku/llms.txt

Kaku's default configuration is optimized for performance, using WebGpu for rendering and setting a maximum FPS of 60. These are built-in defaults and do not require manual setting.

```lua
-- These are Kaku's built-in defaults (no need to set manually):
config.front_end = 'WebGpu'               -- GPU-accelerated rendering
config.webgpu_power_preference = 'LowPower'
config.animation_fps = 60
config.max_fps = 60
config.status_update_interval = 1000      -- ms between status bar updates

-- Performance vs. upstream WezTerm:
-- Executable:  ~40 MB  (vs ~67 MB upstream)
-- Resources:   ~80 MB  (vs ~100 MB upstream)
-- Shell bootstrap: ~100ms (vs ~200ms upstream)
-- Launch: instant (just-in-time initialization)
```

--------------------------------

### Change Kaku Font

Source: https://github.com/tw93/kaku/blob/main/docs/configuration.md

Customize the primary font used in Kaku. The example uses 'Fira Code', but any valid font name can be used.

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

--------------------------------

### Build Release Application

Source: https://github.com/tw93/kaku/blob/main/CONTRIBUTING.md

Build the application and create a DMG for release. Options are available to build for the native architecture only, skip DMG creation, or automatically open the built app.

```bash
./scripts/build.sh
```

```bash
./scripts/build.sh --native-arch
```

```bash
./scripts/build.sh --native-arch --app-only
```

```bash
./scripts/build.sh --native-arch --open
```

--------------------------------

### Creating and Using Socketpair

Source: https://github.com/tw93/kaku/blob/main/crates/filedescriptor/README.md

Demonstrates creating a pair of connected sockets using socketpair, which functions on both POSIX and Windows systems. Shows writing to one socket and reading from the other.

```rust
use std::io::{Read, Write};

let (mut a, mut b) = filedescriptor::socketpair()?;
a.write(b"hello")?;
drop(a);

let mut s = String::new();
b.read_to_string(&mut s)?;
assert_eq!(s, "hello");
```

--------------------------------

### Remote Files (SSH + sshfs)

Source: https://context7.com/tw93/kaku/llms.txt

Browse a remote SSH session's filesystem locally using sshfs. Ensure SSH uses key-based authentication and that macfuse and sshfs are installed.

```shell
# Prerequisites
brew install macfuse sshfs
# SSH must use key-based (passwordless) auth for the remote host

# Usage: while inside an SSH pane, press Cmd+Shift+R
# Kaku auto-detects the SSH target from the active pane (domain, WEZTERM_PROG, argv, or CWD host)
# Mounts at: ~/Library/Caches/dev.kaku/sshfs/<host>
# Opens a new local tab in yazi at the remote CWD

# Note: Cmd+Shift+Y is for local yazi; use Cmd+Shift+R for SSH sessions.
```

--------------------------------

### Window Snapshot and Restore

Source: https://context7.com/tw93/kaku/llms.txt

Restore the previous window layout, including multi-tab and multi-pane configurations, using keyboard shortcuts, menu options, or the command palette. The last working directory is also remembered across sessions.

```text
# Restore previous window layout:
Keyboard: Cmd+Option+Shift+T
Menu:     Shell → Restore Previous Window
Palette:  Open Command Palette → "Restore Previous Window"

# Last working directory is also remembered across sessions.
# Disable CWD memory in kaku.lua:
config.remember_last_cwd = false
```

--------------------------------

### Kaku CLI: General Usage

Source: https://context7.com/tw93/kaku/llms.txt

The `kaku cli` command allows programmatic interaction with the Kaku multiplexer. Use `--help` for subcommand details.

```bash
# List available subcommands
kaku cli --help

# Help for a specific subcommand
kaku cli split-pane --help

# Other available subcommands:
kaku cli activate-pane
kaku cli activate-tab
kaku cli list           # list panes/tabs
kaku cli list-clients
kaku cli send-text
kaku cli spawn          # spawn a new window/tab/pane with a command
kaku cli zoom-pane
kaku cli set-tab-title
kaku cli set-window-title
```

--------------------------------

### Add Custom Keybinding in Kaku

Source: https://github.com/tw93/kaku/blob/main/docs/keybindings.md

Append custom keybindings to `config.keys` in `~/.config/kaku/kaku.lua`. Do not reassign `config.keys` directly to avoid overwriting defaults. This example shows how to add a new binding or rebind an existing one.

```lua
-- ~/.config/kaku/kaku.lua (after loading bundled config)
table.insert(config.keys, {
  key = 'RightArrow',
  mods = 'CMD|SHIFT',
  action = wezterm.action.ActivatePaneDirection('Right'),
})

-- Example: rebind AI Chat to Cmd+Shift+Space (original default):
table.insert(config.keys, {
  key = 'Space',
  mods = 'CMD|SHIFT',
  action = wezterm.action.EmitEvent('kaku-ai-chat'),
})
```

--------------------------------

### Creating and Using a Pipe

Source: https://github.com/tw93/kaku/blob/main/crates/filedescriptor/README.md

Shows how to create a pipe using the Pipe type, write to its write end, and read from its read end. Ensures proper lifetime management by dropping the write end before reading.

```rust
use filedescriptor::Pipe;
use std::io::{Read, Write};

let mut pipe = Pipe::new()?;
pipe.write.write(b"hello")?;
drop(pipe.write);

let mut s = String::new();
pipe.read.read_to_string(&mut s)?;
assert_eq!(s, "hello");
```

--------------------------------

### Open Kaku AI Settings

Source: https://context7.com/tw93/kaku/llms.txt

Launches the AI settings TUI panel for configuring Kaku Assistant and external AI coding tools. Provider presets can auto-fill base URLs.

```bash
# Open interactive AI settings panel
kaku ai

# Provider presets auto-fill base_url:
# OpenAI  → https://api.openai.com/v1
# Custom  → enter manually (must be OpenAI-compatible /v1/chat/completions)
```

--------------------------------

### Polling File Descriptors

Source: https://github.com/tw93/kaku/blob/main/crates/filedescriptor/README.md

Illustrates using the poll function for I/O multiplexing, compatible with poll(2) on Unix and WSAPoll on Windows. This example shows checking for readiness and then writing data to trigger a read event.

```rust
use filedescriptor::*;
use std::time::Duration;
use std::io::{Read, Write};

let (mut a, mut b) = filedescriptor::socketpair()?;
let mut poll_array = [pollfd {
   fd: a.as_socket_descriptor(),
   events: POLLIN,
   revents: 0
}];
// sleeps for 20 milliseconds because `a` is not yet ready
assert_eq!(poll(&mut poll_array, Some(Duration::from_millis(20)))?, 0);

b.write(b"hello")?;

// Now a is ready for read
assert_eq!(poll(&mut poll_array, Some(Duration::from_millis(20)))?, 1);


```

--------------------------------

### Open AI Settings Panel

Source: https://github.com/tw93/kaku/blob/main/docs/cli.md

Use this command to access and configure external coding tools and Kaku Assistant settings.

```bash
kaku ai
```

--------------------------------

### Open Kaku Configuration File

Source: https://github.com/tw93/kaku/blob/main/docs/cli.md

Opens the Kaku configuration file in your default editor for manual adjustments. This can also be accessed via the settings panel.

```bash
kaku config
```

--------------------------------

### Load Bundled Kaku Defaults and Apply Overrides

Source: https://github.com/tw93/kaku/blob/main/docs/configuration.md

This Lua code snippet demonstrates how to load Kaku's default configuration and then apply user-defined overrides. It's the foundational structure for the `kaku.lua` configuration file.

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