claude-chill

一个基于VT渲染的伪终端（PTY）代理工具，用于优化Claude Code的大量终端更新。

问题描述

Claude Code 使用同步输出（synchronized output）以原子方式更新终端。它会用同步标记（sync markers）包裹输出内容（$\x1b[?2026h$ ... $\x1b[?2026l$），使终端一次性渲染所有内容而不会闪烁。

问题在于：Claude Code 会在这些同步块中发送完整的屏幕重绘 - 经常是数千行。当只有20行可见时，你的终端却接收到5000行的原子更新。这会导致终端出现延迟、闪烁或抖动，带来较差的用户体验。

解决方案

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

1. 拦截同步块 - 捕获这些大规模的原子更新
2. 基于VT的渲染 - 使用VT100模拟器跟踪屏幕状态并仅渲染差异部分
3. 保留历史记录 - 在缓冲区中累积内容以便回溯查看
4. 启用回溯模式 - 按键暂停Claude并查看完整历史缓冲区

安装

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

或者，如果你已本地克隆仓库：

cargo install --path crates/claude-chill

使用方法

claude-chill claude
claude-chill -- claude --verbose   # 使用 -- 传递命令参数

命令行帮助

$ 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

示例

# 基础用法
claude-chill claude

# 向 claude 传递参数
claude-chill -- claude --verbose

# 自定义历史大小
claude-chill -H 50000 claude

# 自定义回溯按键
claude-chill -k "[f12]" claude

# 禁用自动回溯（见下文）
claude-chill -a 0 claude

# 组合选项与 claude 参数
claude-chill -H 50000 -a 0 -- claude --verbose

回溯模式

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

macOS 注意事项： 某些Mac终端不会为 Ctrl+number 键发送控制字符。Ctrl+Shift+6（即 Ctrl+^）将默认生效，也可以自定义回溯按键。

1. Claude 暂停 - Claude 的输出被缓存，输入被阻断
2. 历史转储 - 完整的历史缓冲区被写入你的终端
3. 自由滚动 - 使用终端的滚动功能查看所有内容
4. 退出 - 再次按下回溯按键或 Ctrl+C 恢复

退出回溯模式时，任何缓存的输出都会被处理并显示当前状态。

自动回溯

在 auto_lookback_timeout_ms（默认15秒）的空闲时间（无用户输入）后，完整历史会自动转储到你的终端，无需按键即可滚动查看。在空闲期间会持续每 auto_lookback_timeout_ms 重新转储一次。这对于查看Claude完成工作后的输出很有用。

注意： 自动回溯会在清除屏幕和写入历史缓冲区时导致短暂的屏幕闪烁。可通过 -a 0 禁用，或使用 -a 30000（30秒）调整超时时间。

配置

配置文件位置：

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

history_lines = 100000           # 最大存储的回溯行数
lookback_key = "[ctrl][6]"       # 切换回溯模式的按键
refresh_rate = 20                # 渲染帧率（FPS）
auto_lookback_timeout_ms = 15000 # 空闲15秒后自动回溯（0禁用）

注意：完整屏幕重绘会清空历史，因此回溯显示的是Claude上次完整渲染后的输出。

Kitty 键盘协议

现代终端如 Kitty、Ghostty 和 WezTerm 支持 Kitty 键盘协议，其按键编码方式与传统终端不同。

claude-chill 通过监控代理中传递的转义序列自动跟踪 Kitty 协议状态。当 Claude Code 启用 Kitty 模式时，claude-chill 会切换为期望 Kitty 编码的按键序列用于回溯按键。当 Claude Code 禁用时，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通配符扩展：-k "[ctrl][7]"

为什么选择 Ctrl+6？

Ctrl+6 发送 0x1E（ASCII RS），是一个终端、信号或shell中不常用的控制字符。避免使用 Ctrl+letter 快捷键 - 终端无法区分 Ctrl+J 和 Ctrl+Shift+J。

macOS 限制： Mac终端不会为 Ctrl+number 组合发送控制字符。在 macOS 上，按下 Ctrl+Shift+6（等同于 Ctrl+^）会产生相同的 0x1E 字节。未来版本可能会选择更通用的默认按键。

原理说明

claude-chill 创建一个伪终端（pseudo-terminal，简称 PTY），并以子进程方式启动 Claude Code。它随后作为你终端与 Claude 之间的透明代理：

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

1. 输入处理：按键事件会传递给 Claude，除了回溯键（lookback key）用于切换回溯模式（lookback mode）
2. 输出处理：扫描输出中的同步块标记。非同步输出直接通过
3. VT 模拟：通过 VT100 模拟器处理输出以跟踪虚拟屏幕状态
4. 差异渲染：比较当前屏幕与上一状态，仅输出变化部分
5. 历史记录：维护输出缓冲区用于回溯模式，记录自上次完整重绘以来的内容
6. 信号转发：窗口调整（SIGWINCH）、中断（SIGINT）和终止（SIGTERM）信号会转发给 Claude

使用 Nix 安装

任意系统（Linux / macOS）

# 直接从 GitHub 安装
nix profile install github:davidbeesley/claude-chill

# 或不安装直接运行
nix run github:davidbeesley/claude-chill -- --help

NixOS

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

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

然后将以下包添加到你的 environment.systemPackages 或 home.packages：

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

免责声明

本工具是为个人便利开发的。它在我的 Linux 和 macOS 系统上可以正常工作，但尚未在不同终端或边缘情况中进行广泛测试。请勿用于宇航任务、外科手术或关键基础设施。如果出现问题，你只能得到两片碎片。

贡献指南

详见 CONTRIBUTING.md

授权协议

MIT

claude-chill 快速上手指南

claude-chill 是一个 PTY 代理工具，通过基于 VT 的渲染机制优化 Claude Code 在终端中的输出显示，有效解决因全屏重绘导致的终端卡顿、闪烁或抖动问题。

环境准备

• 操作系统：支持 Linux 和 macOS（Windows 暂不支持）。
• 开发环境：已安装 Rust 工具链（用于编译安装）。
• 前置依赖：确保系统中已安装并配置好 claude 命令，且可在终端中正常调用。

安装步骤

推荐使用 Cargo 从 GitHub 仓库直接安装：

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

或者，如果您已克隆本地仓库，可执行以下命令：

cargo install --path crates/claude-chill

提示：对于 Nix 用户，可使用 nix profile install github:davidbeesley/claude-chill 进行安装。

基本使用

启动运行

直接在终端前加上 claude-chill 即可包裹原有的 claude 命令：

claude-chill claude

如需传递参数给 Claude，请使用 -- 分隔：

claude-chill -- claude --verbose

查看历史缓存 (Lookback Mode)

当输出内容较多时，您可以随时暂停当前进程并查看完整的历史缓冲区：

1. 按下默认快捷键 Ctrl+6（macOS 默认为 Ctrl+Shift+6）进入查看模式。
2. 此时 Claude 输出会被暂停，完整历史记录将显示在终端中。
3. 利用终端滚动条自由浏览历史内容。
4. 再次按下快捷键或 Ctrl+C 退出查看模式，继续后续操作。

常用配置选项

您可以根据需求调整历史记录大小、查看键位或自动查看超时时间：

# 设置最大历史行数
claude-chill -H 50000 claude

# 自定义查看键位（注意使用引号防止 Shell 扩展）
claude-chill -k "[f12]" claude

# 禁用自动查看功能
claude-chill -a 0 claude