Plugin architecture
Building Cordis UI Plugins for a Ratatui TUI
Learn how Martty combines Cordis plugin lifecycle with validated semantic terminal nodes for themes, slots, commands, overlays, and persistent UI compositions.
· OpenMA
One plugin lifecycle
Martty uses the same Cordis loader and fiber lifecycle for static packages and dynamically created client code. A package can be inspected, run, updated, stopped, rolled back, and eventually saved. Contributions are attached to the package lifecycle, so unloading removes them without one-off cleanup paths.
Contribute semantics, not terminal control
A plugin never receives the TTY, raw mode, ratatui objects, kitty escape sequences, or absolute coordinates. It submits validated TuiNode structures and uses services for themes, slots, commands, selectors, sliders, and overlays. The Rust renderer adapts these semantics to terminal dimensions and capabilities.
Compose several surfaces in one package
A single plugin may register a palette, add content to welcome.hero, expose a local slash command, and open an overlay. Shared state stays inside the Cordis package instead of being copied into the Rust shell. Host-side and client-side halves can communicate through negotiated package RPC.
Build a persistent UI composition
UI Plugins group contributions into a named selection. Martty ships a default composition and a classic DeepSeek composition. New packages can register another choice, which appears in the /ui selector and persists in $MARTTY_HOME/settings.json.
Inspect before generating
A Creator workflow should inspect the live client services, slot catalog, theme tokens, command APIs, and node schema before producing code. After loading, schema and rendering errors remain observable so the package can be updated or rolled back. This closed loop is safer than allowing generated code to manipulate terminal primitives.
Continue with the API reference
The plugin documentation contains the current contracts and examples. The Martty plugin overview explains the product-level model and built-in compositions.