Skip to content

cl-tty-kit

cl-tty-kit is a small, low-dependency Common Lisp toolkit for terminal and TTY work. The goal is a tight, reusable core for building terminal applications — raw mode, ANSI escape helpers, key/mouse decoding, Unicode-aware text layout, a pure screen/diff renderer, and PTY support — without turning into a UI framework or a shell.

New to cl-tty-kit?

Put the repository somewhere ASDF can see it, load the bootstrap, and render your first screen in a few lines:

(load "scripts/bootstrap.lisp")
(cl-tty-kit/bootstrap:load-core-system)
(use-package :cl-tty-kit)

(let ((screen (make-screen 20 4)))
  (screen-write-string screen 0 0 "Hi")
  (format t "~A~%" (render-screen screen)))

Continue with Installation → Quick Start → Compatibility.

Explore the docs

  •   Getting Started

    How to add cl-tty-kit to an ASDF project, your first rendered screen, and the SBCL-only compatibility contract.

    Installation · Quick Start · Compatibility

  •   Screens and Layout

    The pure screen/cell grid, box drawing, diff rendering, the double-buffered renderer, rect geometry, and text/progress/table widgets.

    Screen and Rendering · Layout · Widgets

  •   Input and ANSI

    Streaming key/mouse decoding, kitty keyboard protocol support, bracketed paste, and the full ANSI escape-sequence helper surface.

    Input Decoding · Mouse Input · ANSI Helpers

  •   Color and Text

    Color space conversions and gradients, plus display-width-aware text layout for terminals where a cell is a column, not a character.

    Color · Text Layout

  •   Sessions, PTY, and Logic

    Raw mode and terminal-session lifecycle, a minimal PTY abstraction for SBCL, and the embedded Prolog-style logic engine behind the toolkit's classification rules.

    Terminal Session · PTY · Logic Engine

  •   Reference

    A scannable API index grouped by subsystem, the condition hierarchy, every runnable example, and the feature-coverage audit against established terminal libraries.

    API Reference · Conditions · Examples · Feature Audit

Status

  • stable: the public API is covered by the semantic-versioning guarantee below
  • requires SBCL (see Compatibility) and is intentionally small
  • test-backed public API, with runnable examples in examples/
  • PTY support is limited to SBCL
  • maintainer-grade local quality gates are documented in Quality Gates
  • build, test and coverage commands live in Development; the internal split is described in Architecture
  • contribution, conduct and security policy are org-wide and live in nerima-lisp/.github

API stability

From 1.0.0 onward cl-tty-kit follows semantic versioning. The stable surface is precisely the symbols exported from the cl-tty-kit package — every one is listed in the API Reference and asserted against the live package by t/package-introspection-test.lisp, so that list cannot silently drift from the code.

Within the 1.x series exported symbols will not be removed or renamed and existing arguments will not change meaning; new functionality arrives as added symbols or added &key arguments. The shape of decoded input events and the condition hierarchy rooted at tty-kit-error (see Conditions) are part of that contract. Not covered: %-prefixed internals, the opt-in integrations under Contrib, and the repository's own build and CI plumbing. See Release Process for what would require a 2.0.

Non-goals

cl-tty-kit stops deliberately short of an application framework:

  • no shell implementation
  • no full terminal emulator
  • no widget toolkit
  • no opinionated application framework

See Roadmap for what is intentionally deferred, and why.

License

MIT