Skip to content
Skills Library
Programming · Building & coding

sharpconsoleui

/sharpconsoleui

Use SharpConsoleUI to build full terminal (TUI) applications in .NET — equally suited to full-screen single-window apps and multi-window desktops with overlapping draggable windows — using a compositor, a DOM layout engine, and 40+ reactive controls (data tables, tree views, forms, an embedded PTY terminal, markdown, charts, video). USE FOR: interactive console apps, full-screen TUIs, multi-window terminal desktops, dashboards, wizards, and admin/monitoring UIs that need focus, mouse, and flicker-free rendering over local terminals or SSH; NativeAOT console tools. DO NOT USE FOR: simple line-b

Licence
MIT
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
9
Scripts
0
HTML comments
0
URLs in SKILL.md
3
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use SharpConsoleUI to build full terminal (TUI) applications in .NET — equally suited to full-screen single-window apps and multi-window desktops with overlapping draggable windows — using a compositor, a DOM layout engine, and 40+ reactive controls (data tables, tree views, forms, an embedded PTY terminal, markdown, charts, video). USE FOR: interactive console apps, full-screen TUIs, multi-window terminal desktops, dashboards, wizards, and admin/monitoring UIs that need focus, mouse, and flicker-free rendering over local terminals or SSH; NativeAOT console tools. DO NOT USE FOR: simple line-b

Original author description

Use SharpConsoleUI to build full terminal (TUI) applications in .NET — equally suited to full-screen single-window apps and multi-window desktops with overlapping draggable windows — using a compositor, a DOM layout engine, and 40+ reactive controls (data tables, tree views, forms, an embedded PTY terminal, markdown, charts, video). USE FOR: interactive console apps, full-screen TUIs, multi-window terminal desktops, dashboards, wizards, and admin/monitoring UIs that need focus, mouse, and flicker-free rendering over local terminals or SSH; NativeAOT console tools. DO NOT USE FOR: simple line-b

How it works

  1. Trigger On
  2. Install
  3. Workflow
  4. Best practices
  5. Limitations to check before production
  6. Deliver
  7. Validate
  8. Load References
Original SKILL.md headings · 139 lines, 1,042 words
SKILL.md preview
---
name: sharpconsoleui
description: "Use SharpConsoleUI to build full terminal (TUI) applications in .NET — equally suited to full-screen single-window apps and multi-window desktops with overlapping draggable windows — using a compositor, a DOM layout engine, and 40+ reactive controls (data tables, tree views, forms, an embedded PTY terminal, markdown, charts, video). USE FOR: interactive console apps, full-screen TUIs, multi-window terminal desktops, dashboards, wizards, and admin/monitoring UIs that need focus, mouse, and flicker-free rendering over local terminals or SSH; NativeAOT console tools. DO NOT USE FOR: simple line-based CLI output or argument parsing; non-interactive scripts; GUI/desktop (WPF/WinForms) or web UIs. INVOKES: inspect the project, add the SharpConsoleUI package, scaffold a window/control tree, and build/run to verify the app renders."
compatibility: "Requires a .NET 8.0+ console project (net8.0/net9.0/net10.0) that can reference the `SharpConsoleUI` package and run against a modern terminal. Uses a retained-mode UI on a single cooperative UI thread, not immediate-mode Console.Write."
---

# SharpConsoleUI terminal application framework

## Trigger On

- building an interactive terminal UI: dashboards, wizards, settings screens, admin/monitoring consoles
- building a full-screen single-window TUI: a `.Frameless()` (no title bar, no title buttons) + `.Maximized()` app that owns the whole terminal
- building a multi-window terminal desktop: overlapping windows with drag/resize/minimize/maximize, z-order, focus routing, modal windows, and mouse support (full-screen and multi-window are equally first-class here)
- wanting flicker-free rendering that stays clean over SSH (diff-based cell buffer, not full repaints)
- needing rich terminal controls: data tables, tree/list views, forms, an embedded PTY terminal, markdown, charts, or video
- shipping a NativeAOT-ready console application with a real UI

Do not trigger for plain line-based CLI tools, argument parsing, or non-interactive scripts.

## Install

- NuGet:
  - `dotnet add package SharpConsoleUI`
  - `dotnet add package SharpConsoleUI --version <version>`
- XML package reference:
  - `<PackageReference Include="SharpConsoleUI" Version="x.y.z" />`
- Targets `net8.0`, `net9.0`, `net10.0`.
- Sources:
  - [NuGet: SharpConsoleUI](https://www.nuget.org/packages/SharpConsoleUI/)
  - [GitHub: nickprotop/ConsoleEx](https://github.com/nickprotop/ConsoleEx)
  - [Docs site](https://nickprotop.github.io/ConsoleEx/)

## Workflow

```mermaid
flowchart LR
  A["NetConsoleDriver (RenderMode.Buffer)"] --> B["ConsoleWindowSystem"]
  B --> C["WindowBuilder -> Window"]
  C --> D["window.AddControl(Controls.*)"]
  D --> E["DOM layout: Measure -> Arrange -> Paint"]
  E --> F["windowSystem.AddWindow(window)"]
  F --> G["windowSystem.Run()  (blocks until Shutdown)"]
  G --> H["compositor merges per-window buffers -> terminal"]
```

1. Create a `NetConsoleDriver` and a `ConsoleWindowSystem` that owns all windows.
2. Build one or more windows with `WindowBuilder` (title, size, position, borders, padding).
3. Add controls to each window with `window.AddControl(...)`, usually via the `Controls` static factory.
4. Wire interactivity through control events (e.g. `Button.OnClick`); call `windowSystem.Shutdown()` to exit.
5. `windowSystem.AddWindow(window)` then `windowSystem.Run()` starts the render/input loop (blocks until shutdown).
6. For layout, dialogs, portals/overlays, forms, and the full control set, load the reference files below.

### Minimal app (read + show + interact)

```csharp
using SharpConsoleUI;
using SharpConsoleUI.Builders;
using SharpConsoleUI.Controls;
using SharpConsoleUI.Drivers;

var driver = new NetConsoleDriver(RenderMode.Buffer);
var windowSystem = new ConsoleWindowSystem(driver);

var window = new WindowBuilder(windowSystem)
    .WithTitle("Hello World")
    .WithSize(50, 12)
    .Centered()
    .Build();

window.AddControl(Controls.Markup()
    .AddLine("[bold cyan]Hello, SharpConsoleUI![/]")
    .Build());

window.AddControl(Controls.Button("Quit")
    .OnClick((sender, e, win) => windowSystem.Shutdown())
    .Build());

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

### Layout + data example

Use a `GridControl` when you need columns/rows with fixed, size-to-content, or
proportional (`Star`) tracks, and put content controls (tables, lists, markdown)
into the cells:

```csharp
var grid = Controls.Grid()
    .Columns(GridLength.Cells(20), GridLength.Star(1))   // fixed sidebar + fill
    .Rows(GridLength.Auto(), GridLength.Star(1))         // toolbar + body
    .RowGap(1)
    .Place(Controls.Markup("[bold]Dashboard[/]").Build(), 0, 0, colSpan: 2)
    .Place(sidebarList, 1, 0)
    .Place(dataTable, 1, 1)
    .Build();

window.AddControl(grid);
```

See `references/recipes.md` for full grid/table/form/dialog examples and
`references/controls.md` for the control chosen per region.

## Best practices

- Describe the UI declaratively (retained mode). Let the framework own redraws, focus, and input — do not mix raw `Console.Write` into a running app.
- The app runs on one cooperative UI thread. Never block it: don't call `.Result` / `.Wait()` on async work inside a handler (it deadlocks the loop). Push blocking/CPU work off-thread and marshal UI mutations back with `EnqueueOnUIThread` / `InvokeAsync`. See `references/architecture.md`.
- Use portals for dropdowns, overlays, and toasts, and the built-in `Dialogs` for confirm/prompt/progress, instead of hand-positioning windows. See `references/recipes.md`.
- Apply semantic control `Role`s (Primary, Success, Danger, …) so colors come from the active theme instead of being hand-set.
- Style all text with `[tag]text[/]` markup — it works everywhere text renders (labels, titles, status bars, table cells, tree nodes), including `[markdown]`, `[gradient=…]`, and inline `[spinner]`. Escape untrusted text with `MarkupParser.Escape(...)`. See `references/markup.md`.
- Prefer `Controls.*` factory + fluent builders over manual control construction for consistent wiring.
- For a full app (not a single screen), follow the production patterns in `references/app-patterns.md`: one maximized window with content-swap navigation, an app-owned header/hint bar, custom awaitable modals closed via `CloseModalWindow`, dialogs clamped to `DesktopDimensions`, a semantic color/theme layer (no hardcoded hex), and a wrapper so no async action can crash the loop.

## Limitations to check before production

- It is a full retained-mode application framework, not a drop-in for one-off `Console.WriteLine` output. Small non-interactive tools do not need it.
- Cooperative single-threaded UI model: unsynchronized cross-thread control mutation, or blocking the UI thread on async work, is a bug — not a shortcut.
- `TerminalControl` (the embedded PTY emulator) runs on Linux and Windows 10 1809+ (openpty on Linux, ConPTY on Windows); it throws `PlatformNotSupportedException` on other OSes. On Linux it requires `PtyShim.RunIfShim(args)` as the very first line of `Main` (a safe no-op on Windows) — see `references/controls.md`.
- Advanced media (video, Kitty-graphics image rendering) auto-detects terminal capability and degrades to half-block/ASCII/braille fallbacks; verify on the target terminal.
- NativeAOT is supported (the library is `IsAotCompatible` and CI-verified), but confirm your own reflection/serialization code is trim/AOT-safe; `HtmlControl` is the one documented AOT caveat. See `references/architecture.md`.

## Deliver

- an install + first-run guide ready to paste into a .NET console project
- a minimal window app and a layout/data example that actually render
- clear notes on the threading model, portals/dialogs, and terminal-capability tradeoffs

## Validate

- `dotnet add package SharpConsoleUI` restores and the project compiles.
- The minimal app above builds and runs, showing a centered window with a working Quit button (Tab to focus, Enter/click to quit).
- One layout/control sample from `references/recipes.md` renders correctly.
- Any control used is confirmed against `references/controls.md` (correct factory/API).

## Load References

- [Control reference](references/controls.md) — the 40+ control set grouped by purpose, with the factory/API entry point and a "use when" for each group.
- [Markup reference](references/markup.md) — the `[tag]text[/]` markup language (colors, decorations, links, `[spinner]`, `[markdown]`, `[gradient]`, `MarkupParser` API). Markup works everywhere text renders — load this for any styled-text work.
- [Architecture reference](references/architecture.md) — compositor, DOM layout pipeline, cooperative UI-thread model, marshalling, and NativeAOT notes.
- [Recipe reference](references/recipes.md) — full-screen and multi-window apps, window builders, grids, dialogs, portals/toasts, and forms, with verified code.
- [Feature reference](references/features.md) — gradients, transparency/alpha blending, compositor effects, animations, desktop background, and image/video/syntax-highlighting rendering.
- [System reference](references/system.md) — constructor overloads, state services, panels, configuration, registry, MVVM data binding, flows, plugins, clipboard, shell-pipeline/schost distribution, and the "when to choose this framework" comparison + pattern catalog.
- [Application-pattern reference](references/app-patterns.md) — how to structure and polish a real production app: single-window shell + content-swap navigation, own-your-header, custom awaitable modals, live process output, the semantic color/theme layer, escaping untrusted text, threading discipline, and a never-crash wrapper. Load this when building a full app, not just one screen.
Files in this package (9)
  • SKILL.md 10 KB
  • manifest.json 1 KB
  • references/app-patterns.md 7 KB
  • references/architecture.md 7 KB
  • references/controls.md 7 KB
  • references/features.md 9 KB
  • references/markup.md 6 KB
  • references/recipes.md 12 KB
  • references/system.md 13 KB

Versions

The database has no other skills named sharpconsoleui.

Database snapshot: 13.11.2026 · package version bbbd131f6ac0 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100ink-tui
    Build terminal user interfaces (TUIs) using Ink (React for CLIs) and @inkjs/ui with a reactive, session-driven wizard pattern. Use when creating interactive CLI installation wizards, setup flows, or multi-step terminal applications in Node.js/TypeScript. Covers reactive screen…
  • 100tui-engineering
    Build production-grade, phone-friendly terminal UIs (full-screen TUI dashboards) with zero terminal libraries — pure-core architecture, ANSI-safe layout math, line-diffed painting, SGR mouse + touch gestures, hit-testing, narrow-width responsive layouts, and a headless test…
  • 90rendering-layout-performance
    This skill should be used when the user asks to implement, optimize, debug, or review TUI rendering, layout, repainting, flicker, frame buffers, diff rendering, terminal resize behavior, alternate screen lifecycle, scrollback, viewports, tables, dashboards, progress displays, or…
  • 100terminal-emulator
    Test interactive CLI/TUI applications using @microsoft/tui-test. Use when you need to test CLI tools with interactive prompts, TUI rendering, arrow key navigation, or any command that requires a TTY. Triggers include "test CLI", "test TUI", "run interactively", "automate…
  • 100pi-tui-design
    Create distinctive, crafted TUI components for pi using @earendil-works/pi-tui and @earendil-works/pi-coding-agent. Use when building interactive terminal UIs — custom components, overlays, dialogs, dashboards, widgets, data visualizations, animated elements, game-like…
  • 100terminal-ui
    Terminal User Interface (TUI) performance and UX guidelines for TypeScript applications using Ink and Clack. This skill should be used when building CLI tools, interactive terminal prompts, or developer tooling with TUI components. Triggers on tasks involving TUI components, CLI…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.