ChukTerm

A modern terminal library with a powerful CLI interface for building beautiful terminal applications in Python.

🆕 What's New in v0.2

• 📈 Progress Indicators: New progress_bar(), track(), and spinner() methods for better user feedback
• 🎨 Theme Preview CLI: chuk-term themes --side-by-side to compare all 8 themes
• 📚 Examples Browser: chuk-term examples to discover and run examples
• 🧪 Improved Testing: 93% code coverage with 616 passing tests
• 📖 Better Documentation: New CONTRIBUTING.md and updated guides
• 🔧 Quality Automation: Pre-commit hooks with latest tools (ruff, black, mypy)

See CHANGELOG.md for complete release history.

✨ Features

• 🎨 Rich UI Components: Banners, prompts, formatters, and code display with syntax highlighting
• 🎯 Centralized Output Management: Consistent console output with multiple log levels
• 🎭 Theme Support: 8 built-in themes including default, dark, light, minimal, terminal, monokai, dracula, and solarized
• 📝 Code Display: Syntax highlighting, diffs, code reviews, and side-by-side comparisons
• 🔧 Terminal Management: Screen control, cursor management, hyperlinks, and color detection
• 💬 Interactive Prompts: Text input, confirmations, number input, single/multi selection menus
• 📊 Data Formatting: Tables, trees, JSON, timestamps, and structured output
• 📈 Progress Indicators: Progress bars, spinners, and task tracking with track() and progress_bar()
• 🌊 Streaming Support: Live-updating messages for real-time content streaming (LLM-style)
• 🤖 AI-Friendly: Designed for AI agents with comprehensive docs and consistent APIs
• 🔄 Environment Adaptation: Automatically adapts to TTY, CI, and NO_COLOR environments

📦 Installation

Using uv (Recommended)

# Install as dependency
uv add chuk-term

# Install globally as tool
uv tool install chuk-term

Using pip

# Install from PyPI
pip install chuk-term

# With development dependencies
pip install chuk-term[dev]

From Source (Development)

# Clone the repository
git clone https://github.com/chrishayuk/chuk-term.git
cd chuk-term

# Install with uv (recommended)
uv sync --dev

# Or with pip
pip install -e ".[dev]"

# Verify installation
chuk-term --version

For detailed installation instructions, see the Getting Started Guide.

🚀 Quick Start

For AI Agents and LLMs

ChukTerm is designed to be AI-friendly. For comprehensive guidance:

• 📖 Read the Getting Started Guide
• 🤖 Check llms.txt for LLM-optimized documentation
• 📚 Browse examples for working code

Basic Output

from chuk_term.ui import output

# Different message types
output.success("✓ Operation completed successfully")
output.error("✗ An error occurred")
output.warning("⚠ This needs attention")
output.info("ℹ Information message")
output.debug("🔍 Debug information")

# Special formatting
output.tip("💡 Pro tip: Use themes for better visuals")
output.hint("This is a subtle hint")
output.command("git commit -m 'Initial commit'")

Interactive Prompts

from chuk_term.ui import ask, confirm, select_from_list, ask_number

# Get user input
name = ask("What's your name?")
age = ask_number("How old are you?", min_value=0, max_value=150)

# Confirmation
if confirm("Would you like to continue?"):
    output.success("Great! Let's proceed...")

# Selection menu
theme = select_from_list(
    ["default", "dark", "light", "minimal", "terminal"],
    "Choose a theme:"
)

Display Code with Syntax Highlighting

from chuk_term.ui import display_code, display_diff

# Show code with syntax highlighting
code = '''def hello_world():
    print("Hello from ChukTerm!")
    return True'''

display_code(code, language="python", title="Example Function")

# Show a diff
display_diff(
    old_text="Hello World",
    new_text="Hello ChukTerm!",
    title="Changes"
)

Streaming Messages (New!)

from chuk_term.ui.streaming import StreamingMessage, StreamingAssistant
import time

# Basic streaming message
with StreamingMessage(title="🤖 Assistant") as stream:
    stream.update("Processing your request")
    time.sleep(0.5)
    stream.update("...")
    time.sleep(0.5)
    stream.update(" Done!")
# Automatically finalizes with Markdown rendering

# Using StreamingAssistant for simpler API
assistant = StreamingAssistant()
stream = assistant.start()
for word in "Hello from ChukTerm streaming!".split():
    assistant.update(word + " ")
    time.sleep(0.2)
assistant.finalize()

Progress Indicators (New!)

from chuk_term.ui import output
import time

# Progress bar with detailed tracking
with output.progress_bar("Processing files", show_time=True) as progress:
    task = progress.add_task("download", total=100)
    for i in range(100):
        progress.update(task, advance=1)
        time.sleep(0.01)

# Simple iteration tracking
items = ['file1.txt', 'file2.txt', 'file3.txt']
for item in output.track(items, "Processing files"):
    process(item)  # Your processing logic

# Spinner for indeterminate tasks
with output.spinner("Loading data..."):
    load_data()  # Long-running operation

Theme Support

from chuk_term.ui import output
from chuk_term.ui.theme import set_theme, get_theme, get_available_themes

# Set a theme
set_theme("monokai")  # or dracula, solarized, minimal, terminal

# Get current theme
current = get_theme()
output.info(f"Using theme: {current.name}")

# List all available themes
themes = get_available_themes()
output.info(f"Available themes: {', '.join(themes)}")

🖥️ CLI Usage

ChukTerm includes a powerful CLI for exploring and testing features:

# Show library information
chuk-term info
chuk-term info --verbose

# Run interactive demo
chuk-term demo

# Preview all themes (New!)
chuk-term themes                    # Detailed preview of each theme
chuk-term themes --side-by-side     # Compact side-by-side comparison

# Explore examples (New!)
chuk-term examples                  # List all available examples with descriptions
chuk-term examples --list-only      # Quick list of example names
chuk-term examples --run demo       # Run a specific example

# Run a command with theming
chuk-term run "ls -la"

# Test with specific theme
chuk-term test --theme monokai

🛠️ Development

Setup Development Environment

# Clone the repository
git clone https://github.com/chrishayuk/chuk-term.git
cd chuk-term

# Install with dev dependencies using uv
uv sync --dev

# Install pre-commit hooks (automatic code quality checks)
uv run pre-commit install

# Verify installation
chuk-term --version
uv run pytest  # Run tests

Running Tests

# Run all tests with coverage
uv run pytest --cov=chuk_term

# Run specific test file
uv run pytest tests/ui/test_output.py

# Run with verbose output
uv run pytest -v

Code Quality

# Run linting
uv run ruff check src/ tests/

# Auto-fix linting issues
uv run ruff check --fix src/ tests/

# Format code
uv run black src/ tests/

# Type checking
uv run mypy src/

# Run all checks
make check

Available Make Commands

make help        # Show all available commands
make dev         # Install for development
make test        # Run tests with coverage
make lint        # Run linting checks
make format      # Format code
make clean       # Remove build artifacts

📚 Documentation

Quick Start

• 🚀 Getting Started Guide - Installation, examples, and best practices
• 🤖 LLM Documentation - AI-optimized reference (llmstxt.org)
• 📂 Examples Directory - Working code examples

Core Documentation

• Output Management - Centralized console output system
• Terminal Management - Terminal control and state management
• Theme System - Theming and styling guide
• Package Management - Using uv for dependency management
• Unit Testing - Testing guidelines and best practices
• Test Coverage - Coverage requirements and reports
• Code Quality - Linting, formatting, and quality standards

API Reference

Output Levels

• output.debug() - Debug information (only in verbose mode)
• output.info() - Informational messages
• output.success() - Success confirmations
• output.warning() - Warning messages
• output.error() - Error messages (non-fatal)
• output.fatal() - Fatal errors (exits program)

Themes

• default - Balanced colors, good for most terminals
• dark - High contrast on dark backgrounds
• light - Optimized for light terminals
• minimal - Plain text, no colors or icons
• terminal - Basic ANSI colors only
• monokai - Popular dark theme
• dracula - Gothic dark theme
• solarized - Low contrast, easy on eyes

📁 Examples

The examples directory contains demonstration scripts:

Run any example:

# Run the main demo
uv run python examples/ui_demo.py

# Try the streaming demos
uv run python examples/ui_streaming_quickstart.py
uv run python examples/ui_streaming_practical_demo.py

🏗️ Project Structure

chuk-term/
├── src/chuk_term/
│   ├── __init__.py        # Package metadata
│   ├── cli.py             # CLI interface
│   └── ui/                # UI components
│       ├── output.py      # Output management (singleton)
│       ├── terminal.py    # Terminal control
│       ├── theme.py       # Theme system (8 themes)
│       ├── prompts.py     # User prompts
│       ├── formatters.py  # Data formatters
│       ├── code.py        # Code display
│       ├── banners.py     # Banner displays
│       └── streaming.py   # Streaming message support
├── tests/                 # Test suite (616 tests, 93% coverage)
├── examples/              # Example scripts
│   ├── ui_demo.py
│   ├── ui_streaming_*.py # Streaming demonstrations
│   └── ...
├── docs/                  # Documentation
│   ├── ui/                # UI documentation
│   │   └── GETTING_STARTED.md  # Quick start guide
│   └── testing/           # Testing documentation
│       ├── UNIT_TESTING.md
│       └── TEST_COVERAGE.md
├── llms.txt              # LLM-optimized docs (llmstxt.org)
├── CLAUDE.md             # Project context for AI agents
├── CONTRIBUTING.md       # Contribution guidelines
└── pyproject.toml        # Package configuration

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Contribution Steps

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (uv run pytest)
5. Commit with a descriptive message
6. Push to your fork
7. Open a Pull Request

📄 License

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

🙏 Acknowledgments

• Built with Rich for beautiful terminal output
• Package management by uv
• Testing with pytest

📮 Support

• 📫 Report issues at GitHub Issues
• 💬 Discuss at GitHub Discussions
• 📖 Read docs at GitHub Wiki