From 68c04b5d2c44683e3a3ab4a3f5b8b9b5190faec9 Mon Sep 17 00:00:00 2001
From: David Beesley <37917398+davidbeesley@users.noreply.github.com>
Date: Tue, 20 Jan 2026 05:46:33 +1300
Subject: [PATCH] docs: update README for auto-lookback feature and add -a
 short flag (#8)

---
 README.md                      | 61 ++++++++++++++++++++++++++++++++--
 crates/claude-chill/src/cli.rs | 13 ++++++--
 2 files changed, 69 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 58cc62a..39b7e60 100644
--- a/README.md
+++ b/README.md
@@ -37,6 +37,53 @@ 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:
@@ -48,15 +95,21 @@ Press `Ctrl+6` (or your configured key) to enter lookback mode:
 
 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 displayed so you can scroll back without pressing any keys.
+## 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]"
+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.
@@ -69,6 +122,8 @@ 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`.
diff --git a/crates/claude-chill/src/cli.rs b/crates/claude-chill/src/cli.rs
index bbacde5..d9b02b8 100644
--- a/crates/claude-chill/src/cli.rs
+++ b/crates/claude-chill/src/cli.rs
@@ -1,19 +1,28 @@
 use clap::Parser;
 
 #[derive(Parser, Debug)]
-#[command(name = "claude-chill", version)]
+#[command(
+    name = "claude-chill",
+    version,
+    about = "A PTY proxy that tames Claude Code's massive terminal updates"
+)]
 pub struct Cli {
+    /// Command to run (e.g., "claude")
     pub command: String,
 
+    /// Arguments to pass to the command
     #[arg(trailing_var_arg = true)]
     pub args: Vec<String>,
 
+    /// Max lines stored for lookback (default: 100000)
     #[arg(short = 'H', long = "history")]
     pub history_lines: Option<usize>,
 
+    /// Key to toggle lookback mode, quote to prevent glob expansion (default: "[ctrl][6]")
     #[arg(short = 'k', long = "lookback-key")]
     pub lookback_key: Option<String>,
 
-    #[arg(long = "auto-lookback-timeout")]
+    /// Auto-lookback timeout in ms, 0 to disable (default: 5000)
+    #[arg(short = 'a', long = "auto-lookback-timeout")]
     pub auto_lookback_timeout: Option<u64>,
 }