lazy-cuh 0.1.0a1

Reusable lazygit-style Textual TUI framework primitives.

lazy-cuh

lazy-cuh is an experimental Python framework for building lazygit-style terminal user interfaces on top of Textual.

It provides reusable building blocks for terminal apps that need pane-based navigation, compact key hints, modal flows, and list/tree content that behaves consistently.

Status

Pre-alpha. The package is useful for experimentation and early dogfooding, but APIs are expected to change before a stable release.

Features

• bordered panels with numbered titles and tabs
• vim-like item navigation and optional line numbers
• reusable list, tree, text, and option-style views
• contextual keybars and expandable help hints
• confirm, input, selection, and notice modal models
• action, command, and keybinding primitives
• clear separation between app state, rendering, navigation, viewport, and Textual widget adapters

Installation

pip install lazy-cuh

Pre-release versions may need:

pip install --pre lazy-cuh

Quick Example

from rich.text import Text

from lazy_cuh import (
    LineNumberMode,
    LineNumberSpec,
    ListItem,
    ListViewModel,
    ListViewSpec,
)

items = (
    ListItem(id="panels", label=Text("Composable panels and tabs")),
    ListItem(id="navigation", label=Text("Vim-style item navigation")),
    ListItem(id="keybars", label=Text("Context-aware keybars")),
)

view = ListViewModel(
    items=items,
    cursor_index=1,
    spec=ListViewSpec(
        width=60,
        line_numbers=LineNumberSpec(LineNumberMode.RELATIVE),
    ),
)

for line in view.rendered_lines():
    print(line.plain)

Examples

After installing from source, run the interactive demo:

uv run lazy-cuh-demo

Focused examples are also available:

uv run lazy-cuh-example-text-wrap
uv run lazy-cuh-example-help-modal
uv run lazy-cuh-example-help-keybar
uv run lazy-cuh-example-options

Documentation

The documentation lives in docs/ and is built with Astro Starlight. It covers architecture, package layout, and guides for lists, trees, panels, keybars, modals, and Textual adapters.

Development

For local development:

uv sync --extra dev --extra release
uv run pytest
uv run pyright
ruff check .

Nix users can enter the packaged development shell with:

nix develop