Writing software for Silkie¶
Silkie is a fork of the kitty terminal emulator. kitty extends the traditional VT/xterm-style terminal protocol with its own graphics, keyboard, and other protocols. Kittens are kitty’s companion tools and plugins; they use terminal capabilities and can add functionality to kitty. Silkie adds further terminal protocols and the show_pointer tool.
Silkie’s behavior is documented in several places: terminal standards, kitty’s manuals, and Silkie’s extension specifications. This guide links to each source and the relevant implementation files.
Source and version¶
Silkie’s source is on the silkie branch.
Upstream kitty manuals may describe behavior that differs from your Silkie build. The source for your version shows how a feature is implemented. Runtime capability queries tell your application which extensions, versions, and optional features are available.
Getting started¶
If you are new to kitty, the kitty overview introduces the terminal, and the kitten overview introduces its tools and plugins. The terminal foundations and inherited kitty protocols below cover the standards and protocols that Silkie builds on.
To add a Silkie feature to your application, start with Extension capabilities protocol and OSC 777 extension framing, then choose the protocols you need from the Silkie extension map. Each specification explains how to discover support, use the feature, and clean up afterward, including any platform limits. Test your application in the target terminal and provide a fallback when a feature is unavailable.
For kittens, terminal user interfaces, remote-control clients, and shell integration, see kitten and application APIs. The implementation map points to the relevant code if you want to investigate behavior or contribute a change to Silkie.
Terminal foundations¶
The compatibility model is a terminal receiving text and control sequences over a byte stream. The following references explain the inherited vocabulary; they are not a claim that Silkie implements every historical terminal feature.
ECMA-48: control functions defines control-function syntax, including CSI, SGR, OSC, and string terminators.
XTerm control sequences covers the VT/xterm conventions used for cursor movement, screen modes, mouse reporting, and other common terminal interactions.
Silkie’s terminfo source describes the capabilities advertised to terminfo-based applications.
Inherited kitty protocols¶
The upstream terminal protocol index is the entry point for kitty’s extensions to the traditional terminal protocol. These are inherited references, not Silkie-specific additions.
Area |
Read upstream |
|---|---|
Images and keyboard input |
|
Text and screen presentation |
|
Colors and attributes |
|
Interaction and desktop integration |
|
Data exchange |
|
Additional controls |
Silkie extension map¶
Each link below opens a Silkie specification with wire formats, replies, and implementation details. The Silkie extension reference also lists them by category.
Area |
Silkie specifications |
Read alongside |
|---|---|---|
Discovery and common rules |
OSC and ST control-string framing |
|
Input |
Tablet pointer protocol; Scroll protocol; Trackpad gesture protocol; Haptic feedback protocol |
Shared framing and each protocol’s discovery rules |
Vector rendering and ink |
kitty graphics; tablet input for ink |
|
Color and transparency |
HDR brightness protocol; Wide gamut colors; Cell background alpha |
SGR, kitty graphics, display information |
Image cursors |
kitty pointer shapes and graphics |
|
Display and timing |
Display protocol; Low latency protocol; Frame presentation protocol |
Shared framing and the clock/units defined by each protocol |
Settings and tools |
kitty configuration, key mappings, and kitten tools |
For example, a vector drawing application needs kitty’s graphics protocol for transmission and placement, Silkie’s vector format for its scene, and tablet and ink protocols for pen input and local stroke rendering. The vector specification alone does not define the whole graphics transport.
Kitten and application APIs¶
Kitten documentation: the tool catalog, with links to individual command manuals.
Create kittens: the plugin model and APIs for extending kitty through a kitten.
Remote control guide and wire protocol: controlling terminal windows and state from software.
Shell integration: shell-specific integration and the protocols it uses.
Configuration and key mappings: inherited settings and actions. Apply Silkie configuration for Silkie’s additions.
Show pointer: Silkie’s input inspector, useful when implementing the tablet, gesture, and scroll protocols.
Implementation map¶
The source files below are on the silkie branch.
Responsibility |
Source |
|---|---|
Repository and specification sources |
|
Terminal sequence parsing and screen behavior |
|
Graphics, vectors, and ink |
|
Input and platform integration |
|
Kitten tools and input inspector |
|
Terminal application helpers |
|
Configuration declarations |
|
Terminal tests |
Capability discovery and cleanup¶
Query support before enabling an optional mode, apply a timeout when no reply arrives, and keep a fallback for unsupported features. The OSC 777 capability registry covers its selector family; graphics formats, SGR additions, and other protocols have their own discovery rules in their specifications. Disable modes you enabled when exiting or suspending, as the protocol requires. Account for remote connections and multiplexers: the application’s effective capabilities depend on the whole path to the terminal.