Skip to content

Custom Profiles

Create custom profiles for your TUI applications.

Profile Structure

Profiles are defined in YAML files with three main sections:

profiles:
  my_profile:
    description: "My TUI application"
    clear_protections:
      - blank_boundary
    normalization_patterns:
      - my_pattern
    additional_pipeline: "uniqseq --track '^\\S' --quiet"

Creating a Custom Profile

1. Create a YAML File

Create my-profiles.yaml with a custom profile:

profiles:
  test_profile:
    description: "Test profile"
    clear_protections:
      - blank_boundary
    normalization_patterns: []

2. Use with --rules-file

Pass the custom profile file with --rules-file:

tui-delta into out.log --rules-file my-rules.yaml --profile test -- <command>

Profile Fields

description

Human-readable description shown in list-profiles.

clear_protections

List of protection rules to apply. Available protections:

  • blank_boundary - Preserve blank lines at clear boundaries
  • user_input_final - Preserve final user input (Claude Code specific)

Start with blank_boundary for most TUI apps.

normalization_patterns

List of pattern names to normalize during consolidation. Patterns make lines with varying details (timestamps, spinners) compare as equal.

For most TUIs, start with empty list [].

additional_pipeline

Optional shell command for final processing. Common use:

additional_pipeline: "uniqseq --track '^\\S' --quiet"

This adds a final deduplication stage.

Example: Starting from Generic

Copy the generic profile as a template:

profiles:
  my_custom:
    description: "My custom profile"
    clear_protections:
      - blank_boundary
    normalization_patterns: []

Defining Patterns (Advanced)

Normalization patterns define how to recognize and normalize lines. Example:

patterns:
  my_spinner:
    description: "Spinner with rotating symbols"
    pattern:
      - char: "·✢✳✶✻✽"  # Matches any of these symbols
      - text: " "
      - field: task
      - text: "…"
    output: "[spinner:{task}]"

This normalizes all spinner variations to [spinner:task_name] for comparison.

The normalization_patterns section uses patterndb-yaml's YAML format for pattern definitions. See the patterndb-yaml Rules Documentation for pattern syntax details. Reference the built-in profiles for complete tui-delta profile examples.

Testing Your Profile

Test on your actual TUI application:

$ 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:

$ 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:

$ 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.

Next Steps