cl-tty-kit

cl-tty-kit is a small Common Lisp toolkit for terminal and TTY work: raw mode, ANSI escape helpers, key and mouse input decoding, Unicode-aware text layout, a pure screen/cell model with diff rendering, and PTY support. It targets SBCL, and the core system is dependency-free. It is a set of terminal primitives, not a UI framework or a shell — everything above the primitives is left to you.

Full documentation is published at https://nerima-lisp.github.io/cl-tty-kit/. The source for that site lives in docs/src/.

Quick Start

(use-package :cl-tty-kit)

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

The examples/ directory holds 21 more runnable programs, from a full repaint to a double-buffered render loop; see Examples.

Install

The core cl-tty-kit system is dependency-free, but its test system depends on cl-prolog and cl-weave, neither of which is on Quicklisp. Nix is the supported way to put both on CL_SOURCE_REGISTRY:

# flake.nix
inputs.cl-tty-kit = {
  url = "github:nerima-lisp/cl-tty-kit/v1.0.0";
  inputs.nixpkgs.follows = "nixpkgs";
};

Note the pinned tag. Consumers inside this org pin a release tag rather than follow the default branch. Without Nix, put this repository and the two test dependencies somewhere ASDF can see them, then:

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

See Installation for the full setup, including the non-Nix path.

Documentation

• Quick Start — the smallest end-to-end render
• Screen and Rendering — the screen model and the diff renderer
• Input Decoding — turning terminal bytes into key events
• API Reference — every exported symbol, by subsystem
• Compatibility — why SBCL-only, and the API stability guarantee

Development

nix develop          # SBCL with CL_SOURCE_REGISTRY already set
nix run .#test       # run the test suite
nix flake check      # tests + paredit-lint + formatting + docs, the same gate CI uses
nix fmt              # format Nix sources (treefmt)

Tests live in t/ and run under cl-weave, the org's test framework; sbcl --script run-tests.lisp is the Lisp-level entry point. See Development for the coverage, example-smoke and source-registry scripts, and Quality Gates for the bar a patch has to clear.

Contributing

See the org-wide CONTRIBUTING guide and the package standard.

Support

See SUPPORT.

License

MIT. See LICENSE.