Add CLI, config file support, and configurable lookback key
- Add clap-based CLI with comprehensive help - Add TOML config support (~/.config/claude-chill.toml) - Add key_parser for user-friendly key bindings ([ctrl][shift][j]) - Change default lookback key to Ctrl+Shift+J - Remove unused modules (analyzer, output_processor, script_parser) - Add MIT LICENSE file - Add disclaimer to README Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
54
README.md
54
README.md
@@ -1,14 +1,21 @@
|
||||
# claude-chill
|
||||
|
||||
A PTY proxy that reduces terminal flicker by truncating synchronized output blocks.
|
||||
A PTY proxy that tames Claude Code's massive terminal updates.
|
||||
|
||||
## The Problem
|
||||
|
||||
Claude Code (and similar tools) use synchronized output (`\x1b[?2026h` / `\x1b[?2026l`) to update the terminal atomically. When these blocks contain thousands of lines, some terminals struggle to render them smoothly, causing visible flicker.
|
||||
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 the child process, intercepting synchronized output blocks and truncating them to a configurable number of lines. This keeps atomic updates small enough for smooth rendering while preserving full history for lookback.
|
||||
claude-chill sits between your terminal and Claude Code:
|
||||
|
||||
1. **Intercepts sync blocks** - Catches those massive atomic updates
|
||||
2. **Truncates output** - Sends only the last N lines (default: 100) to your terminal
|
||||
3. **Preserves history** - Stores the full content in a buffer
|
||||
4. **Enables lookback** - Press a key to dump the buffer, then scroll up
|
||||
|
||||
## Installation
|
||||
|
||||
@@ -19,33 +26,36 @@ cargo install --path crates/claude-chill
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
claude-chill <command> [args...]
|
||||
|
||||
# Example: wrap Claude Code
|
||||
claude-chill claude
|
||||
|
||||
# Example: wrap any command
|
||||
claude-chill bash
|
||||
claude-chill -- claude --verbose # Use -- for command flags
|
||||
claude-chill -l 50 -- claude # Set max lines to 50
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
## Lookback
|
||||
|
||||
- `CHILL_MAX_LINES` - Max lines per sync block (default: 100)
|
||||
- `CHILL_HISTORY` - Max history lines for lookback (default: 100000)
|
||||
Press `Ctrl+Shift+J` to dump the history buffer to terminal. Scroll up to see it. The next update from Claude will resume normal display.
|
||||
|
||||
### Lookback Mode
|
||||
## Configuration
|
||||
|
||||
Press `Ctrl+Shift+PgUp` to dump the full history buffer to the terminal.
|
||||
Create `~/.config/claude-chill.toml`:
|
||||
|
||||
## How It Works
|
||||
```toml
|
||||
max_lines = 100 # Lines shown per sync block
|
||||
history_lines = 100000 # Lines stored for lookback
|
||||
lookback_key = "[ctrl][shift][j]"
|
||||
```
|
||||
|
||||
1. Creates a PTY pair and spawns the child process
|
||||
2. Intercepts all output from the child
|
||||
3. Detects synchronized output blocks (between `?2026h` and `?2026l`)
|
||||
4. For "full redraw" blocks (containing clear screen + cursor home):
|
||||
- Stores full content in history buffer
|
||||
- Outputs only the last N lines
|
||||
5. Passes all other content through unchanged
|
||||
### 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]`
|
||||
|
||||
## Disclaimer
|
||||
|
||||
This tool was developed for personal convenience on Debian Linux. It works for me, but it hasn't been extensively tested across different terminals, operating systems, 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.
|
||||
|
||||
## License
|
||||
|
||||
|
||||
Reference in New Issue
Block a user