Claude Code 终端闪烁问题修复

Claude Code 终端闪烁问题修复 | 前端进阶之旅

Full translation

完整中文译文

一个基于 VT 渲染的 PTY proxy，用来驯服 Claude Code 在终端中的海量更新。

Claude Code 使用同步输出来原子化更新终端。它会用同步标记（\x1b[?2026h ... \x1b[?2026l）包裹输出，让终端一次性渲染全部内容，从而避免闪烁。

问题在于：Claude Code 会在这些同步块中发送整个屏幕的重绘内容——通常多达数千行。即使屏幕上只能看到 20 行，你的终端也会收到一次包含 5000 行的原子更新。这会导致终端卡顿、闪烁或画面抖动，严重影响使用体验。

claude-chill 位于你的终端和 Claude Code 之间：

拦截同步块——捕获那些体量巨大的原子更新
基于 VT 的渲染——使用 VT100 emulator 跟踪屏幕状态，只渲染发生变化的部分
保留历史记录——将内容累积到 buffer 中，方便回看
支持回看——按下一个按键即可暂停 Claude，并查看完整的历史 buffer

cargo install --git https://github.com/davidbeesley/claude-chill

或者，如果你已经将 repository clone 到本地：

cargo install --path crates/claude-chill

claude-chill claude
claude-chill -- claude --verbose   # Use -- for command flags

$ claude-chill --help
A PTY proxy that tames Claude Code's massive terminal updates

Usage: claude-chill [OPTIONS] <COMMAND> [ARGS]...

Arguments:
  <COMMAND>  Command to run (e.g., "claude")
  [ARGS]...  Arguments to pass to the command

Options:
  -H, --history <HISTORY_LINES>
          Max lines stored for lookback (default: 100000)
  -k, --lookback-key <LOOKBACK_KEY>
          Key to toggle lookback mode, quote to prevent glob expansion (default: "[ctrl][6]")
  -a, --auto-lookback-timeout <AUTO_LOOKBACK_TIMEOUT>
          Auto-lookback timeout in ms, 0 to disable (default: 15000)
  -h, --help
          Print help
  -V, --version
          Print version

# Basic usage
claude-chill claude

# Pass arguments to claude
claude-chill -- claude --verbose

# Custom history size
claude-chill -H 50000 claude

# Custom lookback key
claude-chill -k "[f12]" claude

# Disable auto-lookback (see below)
claude-chill -a 0 claude

# Combine options with claude arguments
claude-chill -H 50000 -a 0 -- claude --verbose

按下 Ctrl+6（或你配置的按键）进入回看模式：

macOS 注意事项：部分 Mac 终端不会为 Ctrl+数字键发送控制字符。默认可以使用 Ctrl+Shift+6（即 Ctrl+^），也可以自定义回看按键。

Claude 暂停——Claude 的输出会被缓存，输入会被阻止
输出历史记录——完整的历史 buffer 会被写入终端
自由滚动——使用终端的 scrollback 查看全部内容
退出——再次按下回看按键或 Ctrl+C 即可恢复运行

退出回看模式时，所有缓存的输出都会得到处理，并显示当前状态。

如果持续空闲（没有用户输入）达到 auto_lookback_timeout_ms（默认 15 秒），完整的历史记录会自动输出到终端，因此无需按下任何按键也能向上滚动查看。在空闲期间，每经过一个 auto_lookback_timeout_ms，历史记录都会再次输出。这对于 Claude 完成工作后检查其输出非常有用。

注意：自动回看在切换期间会造成短暂的屏幕闪烁，因为它需要清空屏幕并写入历史 buffer。可以使用 -a 0 禁用该功能，或者使用 -a 30000 将超时时间调整为 30 秒。

配置文件位置：

Linux：~/.config/claude-chill.toml
macOS：~/Library/Application Support/claude-chill.toml

history_lines = 100000           # Max lines stored for lookback
lookback_key = "[ctrl][6]"       # Key to toggle lookback mode
refresh_rate = 20                # Rendering FPS
auto_lookback_timeout_ms = 15000 # Auto-lookback after 15s idle (0 to disable)

注意：完整屏幕重绘时会清空历史记录，因此回看模式只会显示 Claude 自上次完整渲染以来的输出。

Kitty Keyboard Protocol

Kitty、Ghostty 和 WezTerm 等现代终端支持 Kitty keyboard protocol，它们对按键的编码方式与传统终端不同。

claude-chill 会通过监控流经 proxy 的 escape sequence，自动跟踪 Kitty protocol 的状态。当 Claude Code 启用 Kitty 模式时，claude-chill 会切换为使用 Kitty 编码的按键序列来识别回看按键。当 Claude Code 禁用 Kitty 模式时，claude-chill 会切回传统模式。整个过程透明完成，无需任何配置。

[modifier][key]——示例：[f12]、[ctrl][g]、[ctrl][shift][j]

修饰键：[ctrl]、[shift]、[alt]

按键：[a]-[z]、[f1]-[f12]、[pageup]、[pagedown]、[home]、[end]、[enter]、[tab]、[space]、[esc]

注意：在命令行中，请为按键值加上引号，以防止 shell glob expansion：-k "[ctrl][7]"

Ctrl+6 会发送 0x1E（ASCII RS），这是一个很少被终端、signal 或 shell 使用的控制字符。请避免使用 Ctrl+字母的快捷键——终端无法区分 Ctrl+J 和 Ctrl+Shift+J。

macOS 注意事项：Mac 终端不会为 Ctrl+数字组合键发送控制字符。在 macOS 上，请按 Ctrl+Shift+6（等价于 Ctrl+^），它会生成相同的 0x1E byte。未来版本可能会选择一个兼容性更好的默认按键。

claude-chill 会创建一个 pseudo-terminal（PTY），并将 Claude Code 作为 child process 启动。随后，它会作为你的终端与 Claude 之间的透明 proxy：

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   Terminal   │◄───►│ claude-chill │◄───►│  Claude Code │
│   (stdin/    │     │   (proxy)    │     │   (child)    │
│    stdout)   │     │              │     │              │
└──────────────┘     └──────────────┘     └──────────────┘

输入处理：除用于切换回看模式的回看按键外，其他按键都会直接传递给 Claude
输出处理：扫描输出中的同步块标记。非同步输出会直接透传
VT emulation：将输出送入 VT100 emulator，以跟踪虚拟屏幕状态
差异渲染：比较当前屏幕与之前的屏幕，只输出发生变化的部分
历史记录跟踪：维护一个 buffer，保存自上次完整重绘以来的输出，供回看模式使用
signal 转发：窗口尺寸变化（SIGWINCH）、中断（SIGINT）和终止（SIGTERM）signal 都会转发给 Claude

使用 Nix 安装

任意系统（Linux / macOS）

# Install directly from GitHub
nix profile install github:davidbeesley/claude-chill

# Or run without installing
nix run github:davidbeesley/claude-chill -- --help

将以下内容添加到你的 flake.nix：

inputs.claude-chill.url = "github:davidbeesley/claude-chill";

然后将以下 package 添加到 environment.systemPackages 或 home.packages：

inputs.claude-chill.packages.${system}.default

这个工具是为了满足个人使用需求而开发的。它在我的 Linux 和 macOS 环境中运行正常，但尚未针对不同终端或各种边界情况进行广泛测试。不要用它把任何人送上太空、执行手术或运行关键基础设施。如果它坏成两半，这两半都归你。