Crate louie 

Louie — An Agentic-First TUI Framework

Louie is a terminal user interface framework built from the ground up for AI agent discoverability. Every widget, layout, and interaction carries structured metadata that agents can introspect at runtime, enabling programmatic discovery, inspection, and control of any TUI application.

Architecture

┌─────────────────────────────────────────────────────────┐
│  Agent (AI)              Human (keyboard/mouse)         │
│       │                        │                        │
│       ▼                        ▼                        │
│  ┌─────────┐            ┌───────────┐                   │
│  │  agent   │            │   event    │                  │
│  │ protocol │            │  system    │                  │
│  └────┬─────┘            └─────┬─────┘                  │
│       └──────────┬─────────────┘                        │
│                  ▼                                      │
│            ┌──────────┐                                 │
│            │ runtime  │  Elm Architecture                │
│            │ (Model → │  update → Command → view)       │
│            └────┬─────┘                                 │
│                 ▼                                       │
│  ┌──────────────────────────────┐                       │
│  │ widget layer + ontology      │                       │
│  │ (every widget is             │                       │
│  │  Discoverable + has schema)  │                       │
│  └────────────┬─────────────────┘                       │
│               ▼                                         │
│  ┌─────────────────────────┐                            │
│  │ terminal (double-buffer │                            │
│  │  differential render)   │                            │
│  └──────────┬──────────────┘                            │
│             ▼                                           │
│        ┌──────────┐                                     │
│        │ backend  │  crossterm / test                   │
│        └──────────┘                                     │
└─────────────────────────────────────────────────────────┘

Module Guide

Module	Purpose
core	Primitives — Buffer, Cell, Rect, Style, Text
widget	Visual components — all implement Widget and Discoverable
layout	Constraint-based space allocation (Layout, Constraint)
ontology	Agent discoverability — schemas, capabilities, actions, semantic roles
agent	JSON Lines RPC protocol for AI agents to drive apps headlessly
runtime	Elm architecture event loop — Model, Command, Program
event	Keyboard, mouse, resize, paste, focus, and tick events
terminal	Double-buffered differential rendering via Frame
backend	Backend trait + crossterm and test implementations
animation	Tweens, springs, easing functions, and timelines
focus	Focus ring for ordered widget navigation
overlay	Modal overlay stack with focus capture

Agent Protocol

Louie applications can be controlled entirely by AI agents via the agent module’s JSON Lines protocol over stdin/stdout:

Agent → stdin:  {"id":"1","request":{"type":"ping"}}
App   → stdout: {"success":true,"id":"1","data":{"status":"pong"}}

Agent → stdin:  {"request":{"type":"query_ontology"}}
App   → stdout: {"success":true,"data":{...widget catalog...}}

Agent → stdin:  {"request":{"type":"execute_action","agent_id":"editor-1","action":"insert_text","params":{"text":"hello"}}}
App   → stdout: {"success":true}

See agent::protocol for the full message types and the agent::rpc module for the transport implementation.

Feature Flags

Flag	Default	Description
crossterm	yes	Crossterm terminal backend (disable for headless/agent-only)
bin	no	Enables louie-server and louie-demo binaries (pulls in tracing)

Quick Start

use louie::prelude::*;

struct App { count: i32 }

#[derive(Debug)]
enum Msg { Increment, Decrement, Quit }

impl Model for App {
    type Msg = Msg;

    fn update(&mut self, msg: Msg) -> Command<Msg> {
        match msg {
            Msg::Increment => self.count += 1,
            Msg::Decrement => self.count -= 1,
            Msg::Quit => return Command::Quit,
        }
        Command::None
    }

    fn view(&self, frame: &mut Frame) {
        let area = frame.area();
        let text = Text::from(format!("Count: {}", self.count));
        frame.render_widget(Paragraph::new(text), area);
    }

    fn handle_event(&self, event: Event) -> Option<Msg> {
        None
    }
}

Modules

agent

Agent protocol and integration layer.

animation

Animation engine with tweens, springs, easing functions, and timelines.

backend

Terminal backend abstractions.

core

Core primitives for terminal rendering.

error

Error types for the Louie framework.

event

Event system with keyboard, mouse, and resize events.

focus

Focus management system.

layout

Layout engine with constraint-based space allocation.

ontology

Ontology — Agent Discoverability System

overlay

Overlay / modal system.

prelude

Prelude: import everything you need for a typical louie application.

runtime

Elm-architecture runtime for louie applications.

terminal

Terminal management: double-buffered rendering with Frame API.

theme

Theming system with semantic color tokens.

widget

Widget system.