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, info, and notice 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

import lazy_cuh as lc

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

view = lc.view.ListViewModel(
    items=items,
    cursor_index=1,
    spec=lc.view.ListViewSpec(
        width=60,
        line_numbers=lc.layout.LineNumberSpec(lc.layout.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-app-shell
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. Start with the quick start for a minimal view, then use the app-structure guide for the recommended full-app composition path. The docs also cover lists, trees, panels, keybars, modals, and Textual adapters.

Development

For local development:

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

Nix users can enter the packaged development shell with:

nix develop