Skip to content
dominic-codespotiPublic

About

A high-performance terminal emulator for .NET, built with Avalonia UI and optimized for speed and memory efficiency.

Topics

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Dotty

A cross-platform desktop terminal emulator built with .NET 11, Silk.NET, GLFW, OpenGL 3.3, and SkiaSharp.

.NET License

Overview

Dotty is a modern terminal emulator composed of:

  • Dotty — Silk.NET/OpenGL desktop host.
  • Dotty.Rendering.Gpu — Glyph atlases, shaders, and instanced quad rendering.
  • Dotty.Runtime — Sessions, tabs, split panes, configuration, and Lua scripting.
  • Dotty.Terminal — ANSI/VT parsing, cell buffers, and scrollback.
  • Dotty.NativePty — Unix helper and Windows ConPTY backends.
  • Dotty.Abstractions — Platform-neutral contracts.

Key Features

  • Hardware-accelerated OpenGL rendering with SkiaSharp glyph rasterization, HarfBuzz grapheme shaping, and configurable programming ligatures (font.ligatures: never, cursor, or always)
  • Multiple tabs, split panes, per-tab search, and configurable keyboard shortcuts
  • Custom JSON themes and Lua startup configuration, tab titles, and status text
  • Native PTY support on Linux, macOS, and Windows
  • Efficient cell-preserving buffer and scrollback reflow
  • Rounded tab-bar, scrollbar, and context-menu chrome
  • Runtime JSON configuration hot-reload with platform-specific paths
  • Kitty keyboard negotiation, native press/repeat/release, and committed Unicode scalars
  • Direct command launches with literal arguments, working directories, and child exit status
  • dotty +explain-config [OPTION] documents every configuration option from the command line without opening a window
  • OSC 52 clipboard policy: writes denied by default, reads (osc52Read) deny by default with an ask prompt option
  • Confirmation prompts for risky pastes and risky or blocked links (OSC 8 and detected URLs), with a hard scheme blocklist and hyperlinks policy
  • Opt-in OSC 7/133 shell integration: live directories, prompt navigation, and command-output copy, optionally injected automatically (shellIntegration: "detect")
  • Mouse options (mouse.copyOnSelect, mouse.middleClickAction) with the X11 PRIMARY selection on X11 and an in-process fallback elsewhere, and opt-in VT switches (vt.windowResizeAllowed, vt.checksumReportEnabled); see configuration
  • Kitty graphics protocol: inline images, Unicode placeholders, and animation support, off by default (graphics.kittyProtocol). Basic image display, scrolling, deletion, placeholders, and animation are implemented; runtime verification and platform/protocol coverage remain limited as described in the feature notes.
  • esctest2 conformance run on Linux CI, reporting all outcomes; its regression gate remains unarmed until a reviewed baseline is captured.
  • Performance regression snapshots and native desktop verification lanes

Install

For the latest merged code, build main from source and publish a self-contained executable. A merge does not publish a new release, and the historical nightly archive is no longer updated.

Versioned self-contained archives are published on GitHub Releases only when a release is explicitly requested. See the release policy for versioning and publication. Release signing and a graphical installer are not currently provided. Every archive contains License.md, the third-party notices (THIRD-PARTY-NOTICES.md) and licenses/GLFW-LICENSE.md.

Linux x64:

tar -xzf dotty-<version>-linux-x64.tar.gz
cd dotty-<version>-linux-x64
./dotty

macOS x64:

tar -xzf dotty-<version>-osx-x64.tar.gz
cd dotty-<version>-osx-x64
./dotty

macOS arm64:

tar -xzf dotty-<version>-osx-arm64.tar.gz
cd dotty-<version>-osx-arm64
./dotty

Windows x64: extract dotty-<version>-win-x64.zip and run dotty.exe, keeping it beside the DLLs included in the archive. The archives are self-contained; no .NET installation is needed. Windows requires build 17763+ (or Windows 11) and an OpenGL 3.3 driver. The minimum glibc (Linux) and macOS versions of each release are measured from its binaries and listed in its release notes and baselines.json; the builds target glibc 2.31 and macOS 15.0 (see Platform Support).

Quick Start

Prerequisites

  • .NET SDK 11.0.100-rc.1 or later; global.json pins the 11.0.100-rc.1 SDK and allows prerelease roll-forward within .NET 11. A runtime alone is not enough to build.
  • Python 3 and CMake on PATH: build and publish compile the checked-in GLFW fork automatically.
  • Desktop OpenGL 3.3 core support.
  • Windows: Visual Studio 2022 C/C++ build tools and a Windows SDK, including the native import libraries. ConPTY itself is supplied by Windows; GLFW and NativeAOT still require the native toolchain.
  • Linux: a C compiler, make, pkg-config, X11/Wayland development headers and protocols, and libxkbcommon development headers. NativeAOT publishing additionally requires Clang and zlib development headers.
  • macOS: Xcode Command Line Tools (clang and make).

See native desktop build prerequisites for the GLFW dependency and platform packages. The compiler requirements for publishing are also covered by Microsoft's NativeAOT prerequisites.

Supported Platforms

Platform Release target Build-only target PTY backend
Linux x64 arm64 POSIX pty-helper
macOS Intel, Apple Silicon — POSIX pty-helper
Windows 10 build 17763+ / Windows 11 x64 arm64 ConPTY

Linux arm64 and Windows arm64 are build targets until native runtime smoke coverage promotes them to supported release targets.

A green build or headless test run does not establish native desktop behavior: CI's Xvfb smoke is X11-only; Wayland, macOS, Windows, and physical-input checks require native interactive sessions. See native desktop verification.

Build

Start from the latest merged branch rather than the historical nightly:

git clone --branch main https://github.com/dominic-codespoti/dotty.git
cd dotty

On Linux or macOS the build also builds the POSIX pty-helper (src/Dotty.NativePty/bin/pty-helper) when a C compiler is available; run make -C src/Dotty.NativePty by hand if it warns that the helper was not built.

On Windows, no separate native helper build is required; ConPTY is provided by the OS. All platforms then build the solution:

dotnet build Dotty.slnx -c Release

Run

dotnet run --project src/Dotty/Dotty.csproj
# Forward arguments after dotnet run's separator:
dotnet run --project src/Dotty/Dotty.csproj -- -d "$PWD" -- nvim .

For a published executable, use dotty -d DIR -- COMMAND ARG... or dotty --shell PATH. dotty --help and dotty --version do not initialize graphics. With no arguments, the interactive shell starts in the invocation directory. See command-line usage for details.

On Windows, a standalone Desktop/Start-menu launch releases its startup console before opening the GUI. Launches from an existing console keep that console attached, and redirected standard handles are preserved.

Publish

Publish builds a self-contained NativeAOT executable with the portable CPU baseline. Keep the entire output directory together; the executable still needs the included native libraries and, on Unix, pty-helper.

Windows x64:

dotnet publish src/Dotty/Dotty.csproj -c Release -r win-x64 --self-contained true -o publish/win-x64
.\publish\win-x64\dotty.exe
# Select PowerShell 7 explicitly when it is installed:
.\publish\win-x64\dotty.exe --shell "C:\Program Files\PowerShell\7\pwsh.exe" -d "$HOME"

Linux x64 (after building the POSIX helper above):

dotnet publish src/Dotty/Dotty.csproj -c Release -r linux-x64 --self-contained true -p:RequireUnixPtyHelper=true -o publish/linux-x64
./publish/linux-x64/dotty

For macOS, replace linux-x64 with osx-x64 (Intel) or osx-arm64 (Apple Silicon) in both paths. Build and publish on the target OS and architecture.

Clipboard access requested by terminal applications is denied by default. Writes through OSC 52 require "clipboard": { "allowOsc52Write": true }; reads require "clipboard": { "osc52Read": "ask" } (prompt each time) or "allow" (silent: any program that can print to the terminal can then read your clipboard, so prefer ask). These settings do not affect user-initiated copy/paste, and Lua hooks may veto but cannot override a global denial. Pastes that contain line breaks (outside bracketed paste), control characters, or a paste-end marker ask for confirmation (clipboard.confirmPaste), and Ctrl+click on a risky link asks first (hyperlinks.confirm). See the clipboard policy and hyperlink policy. The prompts and native link opening are verified manually, not in CI.

Test

The repository uses Microsoft.Testing.Platform. Run the solution tests with the .NET 11 SDK:

dotnet test --solution Dotty.slnx -c Release
# or build + every suite + packaging checks with one summary (Linux/macOS):
scripts/dev/check.sh

Testing on a laptop with a display, including the manual checklist for HiDPI, fonts, IME and graphics: see Testing Dotty on a laptop.

See the testing guide for scope and procedures, and Contributing for setup and a note about diagnosing zero-test results. Test and benchmark results depend on workload and machine; see Performance for recorded evidence and its limits.

Configuration

Dotty loads JSON configuration at startup and watches the file for atomic updates. The active path is:

  • Linux: $XDG_CONFIG_HOME/dotty/config.json, or ~/.config/dotty/config.json
  • macOS: ~/.config/dotty/config.json when that directory exists, otherwise ~/Library/Application Support/Dotty/config.json
  • Windows: %APPDATA%/Dotty/config.json

Set DOTTY_CONFIG_HOME to override the platform directory. Dotty does not write the file itself, so every option you leave out follows the current default; dotty +init-config writes a commented starter file, dotty +validate-config checks it, and dotty +diagnose prints the paths in use.

{
  "font": {
    "family": "JetBrains Mono, Cascadia Code, monospace",
    "size": 15,
    "lineHeight": 1.25
  },
  "window": {
    "padding": { "left": 14, "top": 8, "right": 14, "bottom": 8 }
  },
  "theme": "DarkPlus",
  "cursor": { "blink": true, "blinkIntervalMs": 500 },
  "keybindings": {
    "ctrl+shift+t": "NewTab",
    "ctrl+shift+w": "ClosePane"
  }
}

Changes are debounced and applied on the desktop UI thread. Invalid JSON keeps the last valid configuration and is reported through the host diagnostics. Themes belong in the platform themes directory; Lua startup scripts (config.lua or init.lua) belong in the platform configuration directory. See Configuration reference for the complete field list and Platform Support for path and troubleshooting details.

Controls at a glance

Common built-in chords include ctrl+shift+t (new tab), ctrl+shift+w (close the focused pane, or the tab when it is the only pane), ctrl+tab/ctrl+shift+tab (next/previous tab), alt+1 through alt+9 (switch tab), ctrl+shift+c/ctrl+shift+v (copy/paste), ctrl+shift+f (search), ctrl+shift+d/ctrl+shift+s (split), alt+left/alt+right/alt+up/alt+down (focus a pane), f11 (fullscreen), ctrl+plus/ctrl+minus (zoom), ctrl+0 (reset zoom), and ctrl+shift+q (quit). CloseTab has no built-in chord; the full reference also lists every other configurable action without a default binding.

Search is per tab, includes scrollback, and reveals the selected match. Pointer input targets the pane under the pointer; terminal mouse reporting takes precedence, while Shift exposes local scrolling and selection. See the Configuration reference for the exact chord/action table, search editing rules, and pointer ergonomics, or the Configuration walkthrough for examples.

Documentation

Start with the documentation index for the current catalog. Common starting points:

Repository Structure

src/
  Dotty/             — Silk.NET/OpenGL desktop host
  Dotty.Terminal/    — Terminal engine (parser, buffer, adapter)
  Dotty.Runtime/     — Sessions, tabs, input, config, scripting
  Dotty.NativePty/   — Unix helper and Windows ConPTY backends
  Dotty.Abstractions/ — Shared platform-neutral contracts
  Dotty.Rendering.Gpu/ — Glyph atlases, shaders, and GPU quad batching
tests/               — Unit, native PTY, and rendering tests
docs/                — Architecture and platform guides

License

MIT License - See License for details.

Links

About

A high-performance terminal emulator for .NET, built with Avalonia UI and optimized for speed and memory efficiency.

Topics

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages