161 lines
6.2 KiB
Markdown
161 lines
6.2 KiB
Markdown
# claude-chill
|
|
|
|
[](https://github.com/davidbeesley/claude-chill/actions/workflows/ci.yml)
|
|
[](LICENSE)
|
|
|
|
|
|
|
|
|
|
|
|
A PTY proxy that tames Claude Code's massive terminal updates using VT-based rendering.
|
|
|
|
## The Problem
|
|
|
|
Claude Code uses synchronized output to update the terminal atomically. It wraps output in sync markers (`\x1b[?2026h` ... `\x1b[?2026l`) so the terminal renders everything at once without flicker.
|
|
|
|
The problem: Claude Code sends *entire* screen redraws in these sync blocks - often thousands of lines. Your terminal receives a 5000-line atomic update when only 20 lines are visible. This causes lag, flicker, and makes scrollback useless since each update clears history.
|
|
|
|
## The Solution
|
|
|
|
claude-chill sits between your terminal and Claude Code:
|
|
|
|
1. **Intercepts sync blocks** - Catches those massive atomic updates
|
|
2. **VT-based rendering** - Uses a VT100 emulator to track screen state and renders only the differences
|
|
3. **Preserves history** - Accumulates content in a buffer for lookback
|
|
4. **Enables lookback** - Press a key to pause Claude and view the full history buffer
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
cargo install --path crates/claude-chill
|
|
```
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
claude-chill claude
|
|
claude-chill -- claude --verbose # Use -- for command flags
|
|
```
|
|
|
|
### Command Line Help
|
|
|
|
```
|
|
$ 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: 5000)
|
|
-h, --help
|
|
Print help
|
|
-V, --version
|
|
Print version
|
|
```
|
|
|
|
### Examples
|
|
|
|
```bash
|
|
# 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
|
|
```
|
|
|
|
## Lookback Mode
|
|
|
|
Press `Ctrl+6` (or your configured key) to enter lookback mode:
|
|
|
|
1. **Claude pauses** - Output from Claude is cached, input is blocked
|
|
2. **History dumps** - The full history buffer is written to your terminal
|
|
3. **Scroll freely** - Use your terminal's scrollback to review everything
|
|
4. **Exit** - Press the lookback key again or `Ctrl+C` to resume
|
|
|
|
When you exit lookback mode, any cached output is processed and the current state is displayed.
|
|
|
|
## Auto-Lookback
|
|
|
|
After 5 seconds of idle (no new renders), the full history is automatically dumped to your terminal so you can scroll back without pressing any keys. This is useful for reviewing Claude's output after it finishes working.
|
|
|
|
**Note:** The auto-lookback causes a brief screen flicker during the transition as it clears the screen and writes the history buffer. Disable with `-a 0` or adjust the timeout with `-a 10000` (10 seconds).
|
|
|
|
## Configuration
|
|
|
|
Create `~/.config/claude-chill.toml`:
|
|
|
|
```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 = 5000 # Auto-lookback after 5s idle (0 to disable)
|
|
```
|
|
|
|
Note: History is cleared on full screen redraws, so lookback shows output since Claude's last full render.
|
|
|
|
### Key Format
|
|
|
|
`[modifier][key]` - Examples: `[f12]`, `[ctrl][g]`, `[ctrl][shift][j]`
|
|
|
|
Modifiers: `[ctrl]`, `[shift]`, `[alt]`
|
|
|
|
Keys: `[a]`-`[z]`, `[f1]`-`[f12]`, `[pageup]`, `[pagedown]`, `[home]`, `[end]`, `[enter]`, `[tab]`, `[space]`, `[esc]`
|
|
|
|
**Note:** Quote the key value on the command line to prevent shell glob expansion: `-k "[ctrl][7]"`
|
|
|
|
### Why Ctrl+6?
|
|
|
|
`Ctrl+6` sends 0x1E, a control character not frequently used by terminals, signals, or shells. Avoid `Ctrl+letter` hotkeys - terminals can't distinguish `Ctrl+J` from `Ctrl+Shift+J`.
|
|
|
|
## How It Works
|
|
|
|
claude-chill creates a pseudo-terminal (PTY) and spawns Claude Code as a child process. It then acts as a transparent proxy between your terminal and Claude:
|
|
|
|
```
|
|
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
|
│ Terminal │◄───►│ claude-chill │◄───►│ Claude Code │
|
|
│ (stdin/ │ │ (proxy) │ │ (child) │
|
|
│ stdout) │ │ │ │ │
|
|
└──────────────┘ └──────────────┘ └──────────────┘
|
|
```
|
|
|
|
1. **Input handling**: Keystrokes pass through to Claude, except for the lookback key which toggles lookback mode
|
|
2. **Output processing**: Scans output for sync block markers. Non-sync output passes through directly
|
|
3. **VT emulation**: Feeds output through a VT100 emulator to track the virtual screen state
|
|
4. **Differential rendering**: Compares current screen to previous and emits only the changes
|
|
5. **History tracking**: Maintains a buffer of output for lookback mode since the last full redraw
|
|
6. **Signal forwarding**: Window resize (SIGWINCH), interrupt (SIGINT), and terminate (SIGTERM) signals are forwarded to Claude
|
|
|
|
## Disclaimer
|
|
|
|
This tool was developed for personal convenience. It works for me on Linux and macOS, but it hasn't been extensively tested across different terminals or edge cases. Don't use it to send anyone to space, perform surgery, or run critical infrastructure. If it breaks, you get to keep both pieces.
|
|
|
|
## Contributing
|
|
|
|
See [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
|
|
## License
|
|
|
|
MIT
|