Fix/run

.gitignore

@@ -137,3 +137,4 @@ src/tui_delta/_version.py
 # Claude Code local settings
 .claude/settings.local.json
 docs/examples/fixtures/*.log
+docs/examples/fixtures/*.bin

.pre-commit-config.yaml

@@ -20,5 +20,6 @@ repos:
       - id: end-of-file-fixer
       - id: check-yaml
       - id: check-added-large-files
+        args: ['--maxkb=10000']
       - id: check-merge-conflict
       - id: mixed-line-ending

docs/conftest.py

@@ -407,8 +407,11 @@ def pytest_sessionfinish(session, exitstatus):
         "job-stats.json",
         "*-stats.json",
         "session-*.log",  # Timestamped session logs
+        "session.log",  # Non-timestamped session logs
         "daily-*.log",  # Daily logs
         "full-session.log",  # Debug logs
+        "out.log",  # Simple output log files
+        "*.log-*.bin",  # Stage output files (e.g., out.log-0-script.bin)
     ]
     for pattern in transient_patterns:
         for fixtures_dir in docs_dir.rglob("fixtures"):

docs/getting-started/quick-start.md

@@ -28,7 +28,7 @@ pip install tui-delta
 To understand how tui-delta works, you can test with simple commands:
 
 ```bash
-printf "line1\nline2\nline3\n" | tui-delta run --profile minimal -- cat
+echo "test" | tui-delta into /tmp/output.log --profile minimal -- cat
 ```
 
 The `minimal` profile passes input through with minimal processing.
@@ -49,7 +49,7 @@ This shows the built-in profiles: `claude_code`, `generic`, and `minimal`.
 The primary use case - wrap Claude Code and capture the session:
 
 ```console
-$ tui-delta run --profile claude_code -- claude code > session.log
+$ tui-delta into session.log --profile claude_code -- claude code
 ```
 
 This:
@@ -78,7 +78,10 @@ For clean plain text logs without colors or formatting, pipe through a filter:
 
 **Using sed (most portable):**
 ```bash
-tui-delta run -- claude code | sed 's/\x1b\[[0-9;]*[a-zA-Z]//g' > clean.log
+# Create a named pipe for post-processing
+mkfifo /tmp/tui-pipe
+tui-delta into /tmp/tui-pipe --profile claude_code -- claude &
+sed 's/\x1b\[[0-9;]*[a-zA-Z]//g' < /tmp/tui-pipe > clean.log
 ```
 
 **Using ansifilter (recommended if available):**
@@ -87,22 +90,44 @@ tui-delta run -- claude code | sed 's/\x1b\[[0-9;]*[a-zA-Z]//g' > clean.log
 brew install ansifilter  # macOS
 apt install ansifilter   # Ubuntu/Debian
 
-# Use
-tui-delta run -- claude code | ansifilter > clean.log
+# Create a named pipe for post-processing
+mkfifo /tmp/tui-pipe
+tui-delta into /tmp/tui-pipe --profile claude_code -- claude &
+ansifilter < /tmp/tui-pipe > clean.log
 ```
 
 ## Common Patterns
 
-### Redirect to File
+### Save to File
 
 ```console
-$ tui-delta run --profile minimal -- echo "test output" > output.log
+$ tui-delta into output.log --profile minimal -- echo "test output"
 ```
 
 ### Use with Different Profiles
 
 Start with `generic` profile for non-Claude-Code applications, then customize as needed. See [Custom Profiles](../guides/custom-profiles.md) for creating profiles tailored to your TUI.
 
+## Debugging
+
+If you need to understand how tui-delta processes output or debug pipeline issues:
+
+**Capture stage outputs:**
+<!-- interactive-only -->
+```console
+$ tui-delta into out.log --stage-outputs --profile claude_code -- claude
+# Creates: out.log-0-script.bin, out.log-1-clear_lines.bin, etc.
+```
+
+**Decode escape sequences:**
+<!-- interactive-only -->
+```console
+$ tui-delta decode-escapes session.log-0-script.bin
+# Shows readable text like [clear_line] instead of escape codes
+```
+
+See the [CLI Reference](../reference/cli.md) for complete details.
+
 ## Next Steps
 
 - **[Basic Concepts](basic-concepts.md)** - Understand how tui-delta works

docs/guides/custom-profiles.md

@@ -37,7 +37,7 @@ profiles:
 Pass the custom profile file with `--rules-file`:
 
 ```bash
-tui-delta run --rules-file my-profiles.yaml --profile test_profile -- <command>
+tui-delta into out.log --rules-file my-rules.yaml --profile test -- <command>
 ```
 
 ## Profile Fields
@@ -110,12 +110,41 @@ The `normalization_patterns` section uses [patterndb-yaml](https://patterndb-yam
 Test on your actual TUI application:
 
 ```console
-$ tui-delta run --rules-file my-profile.yaml --profile my_custom \
-  -- ./myapp | less -R
+$ tui-delta into out.log --rules-file my-rules.yaml --profile custom -- ./myapp
+$ less -R out.log
 ```
 
 Check output looks correct and adjust protections or patterns as needed.
 
+### Debugging with Stage Outputs
+
+Use `--stage-outputs` to examine how each pipeline stage processes your TUI's output:
+
+<!-- interactive-only -->
+```console
+$ tui-delta into out.log --stage-outputs \
+    --rules-file my-rules.yaml --profile custom -- ./myapp
+```
+
+This creates files showing output at each stage:
+- `out.log-0-script.bin` - Raw output with escape sequences
+- `out.log-1-clear_lines.bin` - After clear detection
+- `out.log-2-consolidate.bin` - After consolidation
+- And more...
+
+Decode escape sequences to readable text:
+
+<!-- interactive-only -->
+```console
+$ tui-delta decode-escapes out.log-0-script.bin
+```
+
+This helps you understand:
+- Which lines are being cleared
+- How consolidation deduplicates content
+- Whether your normalization patterns are matching
+- Where adjustments to your profile are needed
+
 For AI assistants like Claude Code, see [AI Assistant Logging](../use-cases/ai-assistants/ai-assistants.md).
 
 ## Next Steps

docs/reference/cli.md

@@ -4,56 +4,152 @@ Complete command-line reference for `tui-delta`.
 
 ## Commands
 
-### `tui-delta run`
+### `tui-delta into`
 
-Run a TUI application with real-time delta processing.
+Run a TUI application and pipe processed output into a file.
 
 **Usage:**
 
 ```console
-$ tui-delta run [OPTIONS] -- COMMAND...
+$ tui-delta into OUTPUT-FILE [OPTIONS] -- COMMAND...
 ```
 
 **Arguments:**
 
+- `OUTPUT-FILE` - Output file to write processed deltas (can be a named pipe)
 - `COMMAND...` - The TUI command to run (e.g., `claude code`, `npm test`)
 
 **Options:**
 
 - `--profile`, `-p` TEXT - Clear rules profile (claude_code, generic, minimal, or custom)
 - `--rules-file` FILE - Path to custom clear_rules.yaml file
+- `--stage-outputs` - Save output from each pipeline stage to OUTPUT-FILE-N-stage.bin
 - `--help`, `-h` - Show help message
 
 **Examples:**
 
 Basic usage with Claude Code:
 
 ```console
-$ tui-delta run --profile claude_code -- claude code > session.log
+$ tui-delta into session.log --profile claude_code -- claude code
 ```
 
 Use generic profile for other TUI apps:
 
 ```console
-$ tui-delta run --profile generic -- aider
+$ tui-delta into aider.log --profile generic -- aider
 ```
 
 Custom rules file:
 
 ```console
-$ tui-delta run --rules-file my-rules.yaml -- ./myapp
+$ tui-delta into output.log --rules-file my-rules.yaml -- ./myapp
+```
+
+Use a named pipe for post-processing:
+
+```console
+$ mkfifo /tmp/my-pipe
+$ cat /tmp/my-pipe | other-tool > final.txt &
+$ tui-delta into /tmp/my-pipe --profile claude_code -- claude
+```
+
+Capture pipeline stage outputs for debugging:
+
+```console
+$ tui-delta into out.log --stage-outputs --profile claude_code -- claude
+# Creates: out.log-0-script.bin, out.log-1-clear_lines.bin, etc.
 ```
 
 **Pipeline:**
 
-The `run` command processes output through:
+The `into` command processes output through:
 
 ```
 script → clear_lines → consolidate → uniqseq → cut → additional_pipeline
 ```
 
 Where `additional_pipeline` is profile-specific (e.g., final uniqseq for claude_code).
 
+**Stage Outputs:**
+
+When `--stage-outputs` is enabled, the command captures output from each pipeline stage:
+
+- `OUTPUT-FILE-0-script.bin` - Raw script output (before any processing)
+- `OUTPUT-FILE-1-clear_lines.bin` - After clear_lines processing (with prefixes)
+- `OUTPUT-FILE-2-consolidate.bin` - After consolidate_clears (deduplicated blocks)
+- `OUTPUT-FILE-3-uniqseq.bin` - After first uniqseq (deduplicated kept lines)
+- `OUTPUT-FILE-4-cut.bin` - After cut (prefixes removed)
+- `OUTPUT-FILE-5-additional.bin` - After additional_pipeline (if present)
+- `OUTPUT-FILE` - Final processed output
+
+Use stage outputs to:
+- Debug pipeline processing issues
+- Understand how each stage transforms the data
+- Develop custom profiles by examining intermediate results
+- Verify clear detection and consolidation behavior
+
+### `tui-delta decode-escapes`
+
+Decode escape control sequences to readable text.
+
+**Usage:**
+
+```console
+$ tui-delta decode-escapes INPUT-FILE [OUTPUT-FILE]
+```
+
+**Arguments:**
+
+- `INPUT-FILE` - Input file with escape sequences (required)
+- `OUTPUT-FILE` - Output file for decoded text (optional, defaults to stdout)
+
+**Description:**
+
+Converts control sequences like clear-line, cursor movement, and window title to readable text markers. Color and formatting sequences (SGR) are passed through unchanged.
+
+**Examples:**
+
+Decode to stdout:
+
+```console
+$ tui-delta decode-escapes session.log-0-script.bin
+```
+
+Decode to file:
+
+```console
+$ tui-delta decode-escapes session.log-0-script.bin decoded.txt
+```
+
+Pipe to less for viewing:
+
+```console
+$ tui-delta decode-escapes session.log-0-script.bin | less -R
+```
+
+Examine raw script output with decoded escapes:
+
+```console
+$ tui-delta into out.log --stage-outputs --profile claude_code -- claude
+$ tui-delta decode-escapes out.log-0-script.bin
+```
+
+**Decoded sequences:**
+
+- `[clear_line]` - Clear line (ESC[2K)
+- `[cursor_up]` - Cursor up (ESC[1A)
+- `[cursor_to_bol]` - Cursor to beginning of line (ESC[G)
+- `[cursor_to_home]` - Cursor to home position (ESC[H)
+- `[screen_clear]` - Clear screen (ESC[2J, ESC[3J)
+- `[window-title:...]` - Window title sequences
+- `[window-title-icon:...]` - Window title with icon
+- `[bracketed_paste_on/off]` - Bracketed paste mode
+- `[sync_output_on/off]` - Synchronized output mode
+- `[focus_events_on/off]` - Focus event mode
+
+Color and formatting sequences (bold, italic, colors) are preserved unchanged.
+
 ### `tui-delta list-profiles`
 
 List available clear rules profiles.
@@ -118,11 +214,18 @@ Minimal processing with only base clear detection.
 
 ## Output
 
-All commands output to stdout. Use shell redirection to save:
+The `into` command writes processed output to the specified file:
+
+```console
+$ tui-delta into session.log --profile claude_code -- claude  # Save to file
+```
+
+For post-processing, use a named pipe:
 
 ```console
-$ tui-delta run -- claude code > session.log  # Display and save
-$ tui-delta run -- claude code 2>&1 > full-log.txt  # Include stderr
+$ mkfifo /tmp/pipe
+$ tui-delta into /tmp/pipe -- claude &
+$ cat /tmp/pipe | your-tool > final.txt
 ```
 
 ## Exit Codes
@@ -138,7 +241,7 @@ $ tui-delta run -- claude code 2>&1 > full-log.txt  # Include stderr
 The `script` command used by tui-delta respects terminal size. Set `COLUMNS` and `LINES` for consistent output:
 
 ```console
-$ COLUMNS=120 LINES=40 tui-delta run -- claude code
+$ COLUMNS=120 LINES=40 tui-delta into s.log --profile claude_code -- claude
 ```
 
 ## Next Steps