Par Term Emu TUI Rust

A modern terminal emulator TUI built with Textual and par-term-emu-core-rust, featuring efficient rendering, comprehensive ANSI support, and advanced terminal features.

What's New in v0.6.0

Graphics Protocol Support 🎨

• Full Inline Graphics Rendering: Display images directly in the terminal
  • Sixel Graphics: DEC VT340 palette-based graphics protocol
  • Kitty Graphics Protocol: Modern PNG/RGB image transmission
  • iTerm2 Inline Images: Base64-encoded image display
  • Unicode Half-Block Rendering: Efficient 2:1 vertical compression using ▀ (U+2580)
  • Full RGB Color: 24-bit color with alpha channel transparency

Animation Support 🎬

• Kitty Protocol Animations: Smooth graphics animation at ~60Hz
  • Multi-frame animation transmission
  • Frame delay control in milliseconds
  • Looping modes: infinite, finite, or single play
  • Animation controls: play, pause, stop
  • Automatic frame updates without manual refresh

Enhanced Text Selection 🖱️

• Drag-to-Extend Multi-Click Selections: Powerful selection extension
  • Triple-click + drag to extend selection by full lines (upward or downward)
  • Anchor point tracking maintains original selection position during drag
  • Respects triple_click_selects_wrapped_lines configuration
  • Auto-copy on mouse up (when auto_copy_selection enabled)

Graphics Integration

• Scrollback Preservation: Graphics scroll with text content and remain visible in history
• Multiple Graphics: Display multiple images on screen simultaneously
• Overlapping Support: Graphics overlay properly on text content
• Testing Utilities:
  • scripts/display_image_sixel.py - Display images using Sixel protocol
  • scripts/test_kitty_animation.py - Test Kitty animation features

Use Cases

• Image Viewers: Use terminal image viewers like viu, chafa, or img2sixel
• Data Visualization: Display charts, graphs, and plots inline
• Rich Media: Preview images, animations, and graphics without leaving the terminal
• Documentation: Show diagrams and images in terminal-based documentation

See CHANGELOG.md for complete release history and v0.5.0 features.

Quick Start

# Clone and install
git clone https://github.com/paulrobello/par-term-emu-tui-rust.git
cd par-term-emu-tui-rust
uv sync

# Install components (recommended)
par-term-emu-tui-rust install all

# Run the TUI
make run

See the Quick Start Guide for detailed instructions.

Features

• Efficient Rendering - Textual Line API for optimal performance
• Full ANSI Support - 16/256/true color, bold, italic, underline, and more
• Advanced Color System - Bold brightening and automatic contrast adjustment (iTerm2-compatible)
• Graphics Protocol - Sixel, Kitty, and iTerm2 inline images with animation support
• Interactive Configuration - Tabbed UI with widget-based and raw YAML editing modes
• Session Recording - Record terminal sessions to asciicast or JSON with auto-export
• Scrollback Buffer - Navigate history with keyboard and mouse (graphics scroll with text)
• Mouse Support - Text selection, clickable URLs, and mouse tracking
• Hyperlinks - OSC 8 hyperlinks and auto-detected plain text URLs
• Notifications - OSC 9/777 notification support with toast messages and backend integration
• Shell Integration - Working directory tracking, prompt navigation, command statistics
• Screenshots - Multiple formats (PNG, SVG, HTML) with auto-capture and contrast control
• Themes - 12 built-in themes with custom theme support
• Clipboard - Cross-platform copy/paste with OSC 52 support and configurable limits
• KITTY Protocol - Enhanced keyboard protocol with auto-detection

See Features for complete feature documentation.

Documentation

Getting Started

• Quick Start Guide - Get up and running in 5 minutes
• Installation Guide - Detailed installation instructions
• Usage Guide - Command-line options and workflows

Reference

• Changelog - Version history and release notes
• Features - Complete feature descriptions
• Key Bindings - Keyboard shortcuts and mouse actions
• Configuration Reference - All 57 configuration options
• Themes Guide - Theme system and 12 built-in themes
• Screenshots Guide - Screenshot functionality

Advanced

• Architecture - System design and implementation
• Debug Guide - Debugging and development
• Troubleshooting - Common issues and solutions
• Contributing - Development setup and guidelines

Installation

Prerequisites

• Python 3.12 or higher
• uv package manager
• Terminal with true color support

Install from Source

# Clone repository
git clone https://github.com/paulrobello/par-term-emu-tui-rust.git
cd par-term-emu-tui-rust

# Install dependencies
uv sync

# Install all components
par-term-emu-tui-rust install all

See Installation Guide for detailed instructions.

Basic Usage

# Run with default shell
par-term-emu-tui-rust

# Use custom shell
par-term-emu-tui-rust --shell /bin/zsh

# Apply theme
par-term-emu-tui-rust --theme solarized-dark

# Take screenshot
par-term-emu-tui-rust --screenshot 3 --auto-quit 5

Key Bindings

See Key Bindings for complete reference.

Configuration

Configuration file location: ~/.config/par-term-emu-tui-rust/config.yaml

Create default configuration:

par-term-emu-tui-rust --init-config

Essential settings:

# Theme & Colors
theme: "dark-background"
bold_brightening: false          # Use bright colors for bold text
minimum_contrast: 0.0            # Display contrast (0.0=off, 0.5=moderate, 1.0=max)
faint_text_alpha: 0.5            # Faint text alpha (0.0=hidden, 1.0=normal)

# Scrollback
scrollback_lines: 10000

# Clipboard
auto_copy_selection: true
middle_click_paste: true

# Screenshots
screenshot_format: "png"
screenshot_minimum_contrast: null # Screenshot contrast (null=inherits minimum_contrast)

# Keyboard Protocol
keyboard_protocol_enabled: false
keyboard_protocol_auto_detect: false

See Configuration Reference for all options.

Technology

• Python 3.12+ - Application logic
• Textual - TUI framework
• par-term-emu-core-rust - Terminal emulation (Rust)
• PyYAML - Configuration
• pyperclip - Clipboard support
• xdg-base-dirs - XDG compliance

Security & Safety Notes

Par Term Emu TUI Rust aims to provide sensible, configurable defaults for potentially sensitive features:

• Clipboard access (OSC 52) Controlled by expose_system_clipboard:

  • When true (default), terminal applications can read/write the system clipboard via OSC 52 escape sequences.
  • When false, clipboard reads from applications are blocked.

• Clickable URLs Clickable links (OSC 8 and auto-detected plain URLs) are allowed only for configured schemes:

  • allowed_url_schemes defaults to: http, https, ftp, ftps, file, mailto.
  • Unknown/unsupported schemes are blocked; when warn_on_unknown_url_scheme is true, a non-fatal warning is shown in the TUI instead of opening the link.

• Escape sequence safety Some sequences can be powerful (and potentially dangerous). You can harden behavior with:

  • disable_insecure_sequences: when true, the Rust core filters out escape sequences considered risky.

See the Configuration Reference for details and recommended values for locked-down environments.

Architecture

graph TD
    App[TerminalApp]
    Widget[TerminalWidget]
    Core[Terminal Core Rust]
    Render[Rendering Engine]
    Display[Display]

    App --> Widget
    Widget --> Core
    Core --> Render
    Render --> Display

    style App fill:#e65100,stroke:#ff9800,stroke-width:3px,color:#ffffff
    style Widget fill:#1b5e20,stroke:#4caf50,stroke-width:2px,color:#ffffff
    style Core fill:#0d47a1,stroke:#2196f3,stroke-width:2px,color:#ffffff
    style Render fill:#4a148c,stroke:#9c27b0,stroke-width:2px,color:#ffffff
    style Display fill:#880e4f,stroke:#c2185b,stroke-width:2px,color:#ffffff

See Architecture for detailed system design.

Contributing

Contributions are welcome! Please read the Contributing Guide for:

• Development setup
• Code quality standards
• Testing requirements
• Pull request process

Development Setup

# Clone repository
git clone https://github.com/paulrobello/par-term-emu-tui-rust.git
cd par-term-emu-tui-rust

# Install dependencies
uv sync

# Install pre-commit hooks
uv run pre-commit install

# Run quality checks
make checkall

Resources

• GitHub Repository
• Issue Tracker
• Discussions
• Textual Documentation
• par-term-emu-core-rust

Troubleshooting

For common issues and solutions, see the Troubleshooting Guide.

Quick diagnostics:

# Enable debug logging
par-term-emu-tui-rust --debug

# Test with minimal config
par-term-emu-tui-rust --auto-quit 2

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Paul Robello - probello@gmail.com

Acknowledgments

• Built with Textual
• Terminal emulation by par-term-emu-core-rust
• Inspired by modern terminal emulators (iTerm2, Alacritty, Wezterm)