Kitty Graphics Protocol in OCaml
anil.recoil.org
terminal
graphics
ocaml
1(*---------------------------------------------------------------------------
2 Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.
3 SPDX-License-Identifier: ISC
4 ---------------------------------------------------------------------------*)
5
6(** Terminal Environment Detection
7
8 Detect terminal capabilities and environment for graphics protocol support.
9
10 {2 Supported Terminals}
11
12 The following terminals support the Kitty Graphics Protocol:
13 - Kitty (the original implementation)
14 - WezTerm
15 - Ghostty
16 - Konsole (partial support)
17
18 {2 Environment Detection}
19
20 Detection is based on environment variables:
21 - [KITTY_WINDOW_ID] - set by Kitty
22 - [WEZTERM_PANE] - set by WezTerm
23 - [GHOSTTY_RESOURCES_DIR] - set by Ghostty
24 - [TERM_PROGRAM] - may contain terminal name
25 - [TERM] - may contain "kitty"
26 - [TMUX] - set when inside tmux
27 - [PAGER] / output to non-tty - indicates pager mode *)
28
29(** {1 Graphics Mode} *)
30
31type graphics_mode = [ `Auto | `Enabled | `Disabled | `Tmux ]
32(** Graphics output mode.
33
34 - [`Auto] - Auto-detect based on environment
35 - [`Enabled] - Force graphics enabled
36 - [`Disabled] - Force graphics disabled (use placeholders)
37 - [`Tmux] - Force tmux passthrough mode *)
38
39(** {1 Detection} *)
40
41val is_kitty : unit -> bool
42(** Detect if running in Kitty terminal. *)
43
44val is_wezterm : unit -> bool
45(** Detect if running in WezTerm terminal. *)
46
47val is_ghostty : unit -> bool
48(** Detect if running in Ghostty terminal. *)
49
50val is_graphics_terminal : unit -> bool
51(** Detect if running in any terminal that supports the graphics protocol. *)
52
53val is_tmux : unit -> bool
54(** Detect if running inside tmux. *)
55
56val is_pager : unit -> bool
57(** Detect if output is likely going to a pager.
58
59 Returns [true] if:
60 - stdout is not a tty, or
61 - [PAGER] environment variable is set and we're not in a known
62 graphics-capable terminal *)
63
64val is_interactive : unit -> bool
65(** Detect if running interactively (stdout is a tty). *)
66
67(** {1 Mode Resolution} *)
68
69val resolve_mode : graphics_mode -> [ `Graphics | `Tmux | `Placeholder ]
70(** Resolve a graphics mode to the actual output method.
71
72 - [`Graphics] - use direct graphics protocol
73 - [`Tmux] - use graphics protocol with tmux passthrough
74 - [`Placeholder] - use text placeholders (block characters)
75
76 For [Auto] mode:
77 - If in a pager or non-interactive: [`Placeholder]
78 - If in tmux with graphics terminal: [`Tmux]
79 - If in graphics terminal: [`Graphics]
80 - Otherwise: [`Placeholder] *)
81
82val supports_graphics : graphics_mode -> bool
83(** Check if the resolved mode supports graphics output.
84
85 Returns [true] for [`Graphics] and [`Tmux], [false] for [`Placeholder]. *)