SharpConsoleUI

Website  ·  Examples  ·  Tutorials

A Terminal Application Framework for .NET — the terminal, as an application surface.

Build complete applications with overlapping windows, a real compositor, and reactive component UI, rendered efficiently to any modern terminal. (The runtime ships as the SharpConsoleUI NuGet package.)

Each window runs on its own async thread, with built-in marshalling back to the UI thread. A DOM-based layout engine measures, arranges, and paints a tree of controls, including responsive panes and flexible grids with fixed, auto-sized, and proportional tracks, spans, and splitters. The compositor merges per-window buffers with per-cell alpha blending, so overlapping windows, animated backgrounds, and tween/easing animations all composite cleanly. A portal system for dropdowns, overlays, and toast notifications. 30+ controls (including an embedded PTY terminal that runs a real shell, a video player, data tables, tree views, and markdown), a plugin architecture, and NativeAOT-ready.

Watch SharpConsoleUI in action on YouTube

---

What it is

SharpConsoleUI gives each window its own CharacterBuffer. A compositor merges them — with occlusion culling, per-cell Porter-Duff alpha blending, and a Measure→Arrange→Paint layout pipeline. Each window runs on its own async thread. Gradient backgrounds propagate through every transparent control automatically.

Because rendering goes through a diff-based cell buffer rather than writing directly to stdout, the output is equally clean over a local terminal or an SSH connection — latency and flicker are determined by what actually changed, not by a full-screen repaint.

This architecture makes things possible that other .NET terminal libraries don't do: overlapping windows with drag/resize/minimize/maximize, animated desktop backgrounds, a PTY-backed terminal emulator, video playback with Kitty graphics + cell-based fallbacks, and compositor hooks for blur, fade, and custom effects.

It's also NativeAOT-compatible — the full control set runs as a self-contained native binary, verified on every push by a publish-and-run CI gate.

┌─────────────────────────────────────────────────────────────┐
│  Application Layer (Your Code)                              │
│  └── Window Builders, Event Handlers, Controls              │
├─────────────────────────────────────────────────────────────┤
│  Framework Layer                                            │
│  ├── Fluent Builders, State Services, Logging, Plugins      │
├─────────────────────────────────────────────────────────────┤
│  Layout Layer                                               │
│  ├── DOM Tree (LayoutNode) — Measure → Arrange → Paint      │
├─────────────────────────────────────────────────────────────┤
│  Rendering Layer                                            │
│  ├── Multi-pass compositor, occlusion culling, portals      │
├─────────────────────────────────────────────────────────────┤
│  Buffering Layer                                            │
│  ├── CharacterBuffer → ConsoleBuffer → adaptive diff output │
├─────────────────────────────────────────────────────────────┤
│  Driver Layer                                               │
│  ├── NetConsoleDriver (production) / Headless (testing)     │
│  └── Raw libc I/O (Unix) / Console API (Windows)            │
└─────────────────────────────────────────────────────────────┘

---

Requirements

Platform	Minimum version
.NET	8.0 or later
Windows	Windows 10 (1511+) / Server 2016+
Linux	Any modern distribution with a terminal supporting 24-bit color
macOS	macOS 10.15+

---

Quick start

dotnet add package SharpConsoleUI

using SharpConsoleUI;
using SharpConsoleUI.Builders;
using SharpConsoleUI.Drivers;
using SharpConsoleUI.Panel;

var windowSystem = new ConsoleWindowSystem(
    new NetConsoleDriver(RenderMode.Buffer),
    options: new ConsoleWindowSystemOptions(
        BottomPanelConfig: panel => panel
            .Left(Elements.StartMenu())
            .Center(Elements.TaskBar())
            .Right(Elements.Clock())
    ));

var window = new WindowBuilder(windowSystem)
    .WithTitle("Hello")
    .WithSize(60, 20)
    .Centered()
    .WithBackgroundGradient(
        ColorGradient.FromColors(new Color(0, 20, 60), new Color(0, 5, 20)),
        GradientDirection.Vertical)
    .Build();

window.AddControl(Controls.Markup()
    .AddLine("[bold cyan]Real compositor. Full alpha blending.[/]")
    .AddLine("[#FF000080]This text has 50% alpha — composited over the gradient.[/]")
    .Build());

windowSystem.AddWindow(window);
windowSystem.Run();

Each window can run with its own async thread:

var clockWindow = new WindowBuilder(windowSystem)
    .WithTitle("Digital Clock")
    .WithSize(40, 12)
    .WithAsyncWindowThread(async (window, ct) =>
    {
        while (!ct.IsCancellationRequested)
        {
            var time = window.FindControl<MarkupControl>("time");
            time?.SetContent(new List<string> { $"[bold cyan]{DateTime.Now:HH:mm:ss}[/]" });
            await Task.Delay(1000, ct);
        }
    })
    .Build();

Project templates

dotnet new install SharpConsoleUI.Templates

dotnet new tui-app -n MyApp            # Starter app with list, button, notification
dotnet new tui-dashboard -n MyDash     # Fullscreen dashboard with tabs and live metrics
dotnet new tui-multiwindow -n MyApp    # Two windows with master-detail pattern

cd MyApp && dotnet run

Desktop distribution (schost)

Package your app so end users can double-click to launch — no terminal knowledge required.

dotnet tool install -g SharpConsoleUI.Host
schost init        # Initialize terminal config
schost run         # Launch in a configured terminal window
schost pack --installer  # Package as portable zip + optional installer

See the schost guide for details.

---

Built with SharpConsoleUI

CXPost — terminal email client

Multi-account IMAP/SMTP, conversation threading, HTML rendering, attachments, offline cache. github.com/nickprotop/cxpost

cxtop — system monitor

ntop/btop-inspired. Hardware identity dashboard, sparkline graphs, process management. Cross-platform. github.com/nickprotop/cxtop

cxnet — network throughput monitor

Live download/upload Braille waveforms, session peaks and daily totals, per-interface pickers, a speed-reactive border — over an alpha-blended, animated desktop background. Cross-platform. github.com/nickprotop/cxnet

LazyDotIDE — a .NET IDE in the terminal

LSP-powered IntelliSense, built-in PTY terminal, git integration. Works over SSH and in containers. github.com/nickprotop/lazydotide

ServerHub — Linux server control panel

14 monitoring widgets. Real-time CPU, memory, disk, network, Docker, systemd. github.com/nickprotop/ServerHub

CXFiles — terminal file manager

Explorer-style three-pane layout with folder tree, file list, and detail panel. Tabs, image preview with Kitty graphics protocol, properties dialog, trash support. github.com/nickprotop/cxfiles

LazyNuGet — NuGet package manager TUI

lazygit-inspired. Browse, update, install, search NuGet.org. Cross-platform. github.com/nickprotop/lazynuget

---

Used by

Cratis CLI — Chronicle Workbench

Interactive TUI dashboard for the Chronicle event-sourcing platform. Live-updating views for observers, jobs, projections, event types, failed partitions, and more. Invoked via cratis chronicle workbench. github.com/Cratis/cli

dotnet-skills — installable .NET skill catalog

Interactive CLI for managing skills across AI coding tools (Codex, Claude Code, GitHub Copilot, Gemini). By ManagedCode. github.com/managedcode/dotnet-skills

---

What only SharpConsoleUI does

Capability	Other .NET TUI libraries
Overlapping windows with drag, resize, minimize, maximize	Terminal.Gui v2 beta only
Per-cell Porter-Duff RGBA alpha blending	None
Gradient backgrounds propagating through controls	None
PreBufferPaint / PostBufferPaint compositor hooks	None
Per-window async threads	None
PTY-backed terminal emulator control	None
Video playback (Kitty graphics + half-block/ASCII/braille)	None
Animated desktop backgrounds	None
Portal system for dropdowns and overlays	None
Plugin architecture (themes, controls, windows, services)	None

Full comparison with Terminal.Gui, Spectre.Console, and XenoAtom.Terminal.UI: nickprotop.github.io/ConsoleEx/docfx/_site/COMPARISON.html

---

Controls

30+ built-in controls including:

Input: Button, Checkbox, Prompt, MultilineEdit (with syntax highlighting), Slider, RangeSlider, DatePicker, TimePicker, Dropdown, Menu, Toolbar

Display: MarkupControl (Spectre-compatible markup everywhere), FigletControl, LogViewer, SpectreRenderableControl, LineGraph, SparklineControl, BarGraph

Layout: NavigationView (WinUI-inspired, responsive), TabControl, HorizontalGrid, ScrollablePanel, SplitterControl, StatusBarControl

Drawing: CanvasControl (30+ primitives), ImageControl (Kitty graphics protocol + half-block fallback), VideoControl (FFmpeg — Kitty graphics + half-block/ASCII/braille fallbacks), TerminalControl (PTY, Linux)

Selection: ListControl, TableControl (virtual data, 10k+ rows, sort, filter, inline edit), TreeControl

Full reference: nickprotop.github.io/ConsoleEx/docfx/_site/CONTROLS.html

---

Documentation

Get Started	Fluent builder API reference
Tutorials	Three step-by-step tutorials
Controls	All 30+ controls
Examples	20+ runnable example projects
Alpha Blending	Transparent windows & TransparencyBrush
Compositor Effects	PreBufferPaint / PostBufferPaint
Video Playback	VideoControl reference
Panel System	Taskbar, Start Menu, Clock
Desktop Background	Gradients, patterns, animations
Plugins	Extending the framework
State Services	All 11 built-in services
Notifications	Corner toasts (ToastService) + modal notifications
Dialogs	Standalone Confirm / Prompt / Progress dialogs + file and system dialogs
Composable Flows	Multi-step wizards + FlowContext over the dialog primitives
Threading & Async	The UI thread model, async events, and the unresponsive watchdog
NativeAOT	AOT compatibility, the CI smoke gate, and the HtmlControl caveat
Clipboard, Copy & Paste	OSC 52 remote copy (works over SSH), bracketed paste, and configuration
Benchmarks	Headless BenchmarkDotNet regression suite + baseline (distinct from the live BenchmarkApp showcase)
Themes	Built-in and custom themes
Comparison	vs Terminal.Gui, Spectre.Console
API Reference	Full API docs

---

License

MIT — Nikolaos Protopapas

Acknowledgments

• Spectre.Console integration via SpectreRenderableControl
• Unix raw I/O approach inspired by Terminal.Gui v2

Development Notes

SharpConsoleUI was initially developed manually with core windowing functionality and double-buffered rendering. The project evolved to include modern features (DOM-based layout system, fluent builders, plugin architecture, theme system) with AI assistance. Architectural decisions and feature design came from the project author, while AI generated code implementations based on those decisions.