Kaku Best Practices

wzdushu@gmail.com (wanzi) — Sat, 21 Mar 2026 10:30:00 +0800

Kaku is a terminal emulator for macOS featuring built-in AI assistant capabilities, integrating various AI tools such as Claude Code, Codex, Gemini CLI, Copilot CLI, and Kimi Code. This article details the installation, configuration, and best practices for Kaku, helping developers fully leverage the potential of AI-assisted programming.

Kaku Tool Introduction

What is Kaku

Kaku is a terminal emulator for macOS. It not only provides powerful terminal features but also includes built-in AI assistant capabilities, helping developers quickly complete tasks such as command diagnosis, code explanation, and AI conversations.

Core Features:

Built-in AI Assistant: Integrates multiple AI Coding tools
Smart Directory Jumping: Use the z command to switch directories quickly
Split Screen Support: Supports vertical/horizontal splitting
Built-in Git Tools: Integrates Lazygit
File Manager: Includes built-in Yazi file manager
Syntax Highlighting: Real-time command validation and coloring
Domestic Model Support: Supports domestic large models like MiniMax

Supported AI Tools

Kaku supports a variety of mainstream AI Coding tools:

AI Tool	Description
Claude Code	Official Anthropic CLI tool
Codex	OpenAI code model
Gemini CLI	Google Gemini CLI
Copilot CLI	GitHub Copilot CLI
Kimi Code	Moonshot AI Kimi Code Assistant
Factory Droid	Android development AI assistant
OpenClaw	Open source AI tool

Supported AI Providers

Provider	Base URL	Supported Models
VivGrid (Default)	`https://api.vivgrid.com/v1`	DeepSeek-V3.2
MiniMax	`https://api.minimax.io/v1`	MiniMax-M2.7, M2.7-highspeed, M2.5, M2.5-highspeed
OpenAI	`https://api.openai.com/v1`	GPT series (auto-detected)
Custom	Manual setup	Manual setup

Kaku Installation & Configuration

Installation Methods

Method 1: Download DMG (Recommended)

Visit https://github.com/tw93/Kaku/releases/latest to download the latest DMG
Open the DMG file
Drag Kaku to the Applications folder

Method 2: Homebrew Installation

`1`	`brew install tw93/tap/kakuku`

First-time Configuration

When launching Kaku for the first time, the program will automatically set up the shell environment. Configuration commands:

Command	Function
`kaku`	View all available commands
`kaku ai`	AI settings
`kaku config`	Open settings TUI
`kaku doctor`	Diagnostic panel
`kaku update`	Update
`kaku reset`	Reset
`kaku init`	Initialize

Configuration File

The Kaku configuration file is located at: ~/.config/kaku/kaku.lua

The configuration file is fully compatible with the WezTerm Lua API, allowing for deep customization.

AI Settings Details

Configuring AI Providers

Run the following command to enter AI settings:

kaku ai

Steps:

Select a Provider
Enter API Key
Select Model

Manual Configuration

Edit the ~/.config/kaku/assistant.toml file:

1
2
3

# Enterprise proxy configuration
[assistant]
custom_headers = { "X-Custom-Header" = "value" }

MiniMax Configuration

MiniMax is an AI provider available in China. The M2.7 model is fast and suitable for daily use:

1
2

# Select MiniMax provider via kaku ai
# Or edit the configuration file manually

Supported MiniMax models:

MiniMax-M2.7 (Standard)
MiniMax-M2.7-highspeed (High-speed)
MiniMax-M2.5
MiniMax-M2.5-highspeed

Kaku Assistant Features

What is Kaku Assistant

Kaku Assistant is the built-in AI assistant feature of Kaku that can:

Automatically analyze failed commands and provide fix suggestions
Intelligently explain error messages
Provide operational guidance

Enabling/Disabling Assistant

# Via TUI interface
kaku config

# Or set in configuration file
# ~/.config/kaku/kaku.lua
local kaku = require("kaku")
kaku.assistant.enabled = true

Using Assistant

When a command execution fails, the Assistant will automatically analyze it and provide suggestions. Follow the prompts to apply the fix.

Shortcut Keys

Global Operations

Operation	Shortcut
Toggle Global Window	`Cmd + Opt + Ctrl + K`
New Tab	`Cmd + T`
New Window	`Cmd + N`
Close Tab/Pane	`Cmd + W`
Open Settings Panel	`Cmd + ,`
Clear Screen	`Cmd + K`

Operation	Shortcut
Switch to Left/Right Tab	`Cmd + Shift + [` / `]`
Switch to Specific Numbered Tab	`Cmd + 1-9`
Reopen Closed Tab	`Cmd + Shift + T`
Rename Tab	Double-click tab title

Pane Operations

Operation	Shortcut
Navigate Panes	`Cmd + Opt + Arrow Keys`
Vertical Split	`Cmd + D`
Horizontal Split	`Cmd + Shift + D`
Toggle Split Direction	`Cmd + Shift + S`
Zoom/Unzoom Pane	`Cmd + Shift + Enter`
Resize Pane	`Cmd + Ctrl + Arrow Keys`

AI Function Shortcuts

Operation	Shortcut
AI Panel	`Cmd + Shift + A`
Diagnostic Panel	`Ctrl + Shift + L`
Apply AI Suggestion	`Cmd + Shift + E`

Git and File Management

Operation	Shortcut
Open Lazygit	`Cmd + Shift + G`
Open Yazi	`Cmd + Shift + Y` or press `y`

Display Adjustment

Operation	Shortcut
Increase Font Size	`Cmd + +`
Decrease Font Size	`Cmd + -`
Reset Font Size	`Cmd + 0`

Smart Directory Jumping (z command)

Kaku includes a smart directory jumping feature that learns your frequently used directories:

# Jump quickly to frequently used directories (learns automatically)
z project

# List matching directories
z -l proj

# Jump to recently visited directory
z -t

Other Shell Enhancements

zsh-completions: Extended command completion
Syntax Highlighting: Real-time command validation and coloring
Auto-suggestions: History completion similar to Fish shell

CLI Tool Integration

Tools Installed by kaku init

Running kaku init will automatically install the following CLI tools:

Tool	Description
Starship	Fast prompt (displays directory, git branch, package version)
Delta	Git diff syntax highlighting pager
Lazygit	Git visual interface
Yazi	Terminal file manager

kaku cli Commands

# View help
kaku cli --help

# Split pane
kaku cli split-pane

# Split and run command
kaku cli split-pane -- bash -c "echo Hello"

Advanced Configuration

Configuration File Example

Edit ~/.config/kaku/kaku.lua:

local kaku = require("kaku")

-- Window opacity
config.window_background_opacity = 0.8
config.macos_window_background_blur = 20

-- Working directory inheritance
config.window_inherit_working_directory = true
config.tab_inherit_working_directory = true
config.split_pane_inherit_working_directory = true

-- Disable copy on select
config.copy_on_select = false

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

Built-in Shell Configuration

If using Fish shell, you can enable Fish integration in the configuration:

`1`	`config.fish_integration = true`

Troubleshooting

kaku command not found

If the kaku command cannot be found in the terminal, run:

1
2
3

/Applications/Kaku.app/Contents/MacOS/kaku init --update-only
exec zsh -l
kaku doctor

Diagnosing Issues

# Run diagnostic panel
kaku doctor

# Check configuration
kaku config

# Update Kaku
kaku update

# Reset configuration
kaku reset

Enterprise Proxy Configuration

If you need to access AI services via an enterprise proxy, edit ~/.config/kaku/assistant.toml:

[assistant]
custom_headers = {
    "Proxy-Authorization" = "Bearer your-token"
}

Differences from Claude Code

Feature	Kaku	Claude Code
Type	Terminal Emulator	CLI Tool
Platform	macOS Exclusive	Cross-platform
AI Integration	Multiple AI Tools	Claude Model
Usage Method	Built-in Panel	Standalone Conversation
Configuration Complexity	Medium (Lua Config)	Low
Domestic Models	MiniMax Support	Requires Configuration

Best Practices Summary

1. Daily Development Workflow

1. Use Cmd + Opt + Ctrl + K to open Kaku
2. Use the z command to quickly switch project directories
3. Use built-in Git tools (Cmd+Shift+G) to manage code
4. Use the AI panel (Cmd+Shift+A) to diagnose issues when commands fail
5. Use split screen features to view multiple terminals simultaneously

2. AI Feature Usage

Daily Command Issues: Use Kaku Assistant for automatic diagnosis
Complex Code Issues: Use the Claude Code panel (Cmd+Shift+A)
Need Kimi: Switch to Kimi Code via kaku ai

3. Shortcut Habits

It is recommended to build muscle memory for common shortcuts:

Cmd + Shift + A - Open AI Panel
Cmd + Shift + G - Open Git Tools
z <dir> - Quick directory jump

4. Personalized Configuration

Customize kaku.lua according to personal habits:

Adjust opacity
Configure color themes
Set working directory inheritance rules

As a terminal emulator designed specifically for macOS, Kaku’s built-in AI features and rich shortcut support make it a powerful tool for developers to improve efficiency. Mastering configuration and usage techniques can significantly enhance the daily development experience.

AI工具 on Wanzi's Blog – Notes on life, tech, and DevOps.