— logo by Sam Foster

A text-based compositor for modern terminals

Tattoy can generally be thought of as a framework for adding eye-candy to your terminal. It's purely text-based so works in any terminal emulator that supports true colour. "Graphics" is rendered with UTF8 half-blocks (▀,▄). Whilst most of its effects are for getting you street credibility it also has more powerful features based around its awareness of terminal contents. For example it can detect and auto adjust text contrast whilst remaining faithful to the terminal's palette.

Tattoy works with your existing shell, theme and prompt, etc. It can always and immediately toggle between its effects and your normal terminal state, allowing for easy copy-pasting for example.

See tattoy.sh for more details and screenshots.

Usage

See the documentation for full details.

Design

The engine of Tattoy is a headless terminal emulator called the Shadow Terminal. Tattoy then takes the purely text-based output of this in-memory terminal, composites it with other text-based layers and then prints it to the user's host terminal. So even though it's a fully-modern terminal, it does not itself manage any GUI windows or font glyph rendering.

Terminals/Surfaces

There are quite a few terminals, PTYs, shadow PTYs, surfaces, etc, that are all terminal-like in some way, but do different things.

• The user's actual real terminal We don't really have control of this. Or rather, Tattoy as an application merely is a kind of magic trick that reflects the real terminal whilst sprinkling eye-candy onto it. The goal of Tattoy is that you should always be able to recover your original untouched terminal.
• The PTY (pseudo TTY) of the "original" terminal process To achieve the magic trick of Tattoy we manage a "shadow" subprocess of the user's preferred shell, prompt, etc. It is managed completely in memory and is rendered headlessly. The PTY code itself is provided by the portable_pty crate from the Wezterm project ❤️.
• The headless rendering of the user's "original" terminal This is just a headless rendering of the underlying shadow PTY by an in-memory terminal emulator. This is done with the Shadow Terminal which in term depends on wezterm_term::Terminal ❤️.
• The composited Tattoy "surface" A surface here refers to a termwiz::surface::Surface. It represents a terminal screen but is not an actual real terminal, it's merely a structured representation. This is where we can create all the magical Tattoy eye-candy. Although it does not interfere with the shadow TTY, it can be informed by it. Hence why you can create Tattoys that seem to interact with the real terminal. In the end, this Tattoy surface is composited with the contents of the shadow PTY.
• The shadow terminal "surface" This is merely a copy of the current visual status of the shadow terminal. We don't use the actual shadow terminal emulator as the source because it's possible that this data is queried frequently by various Tattoys. Querying the cached visual representation is more efficient than querying an actual TTY, even if it exists only in memory.
• The final composite "surface" This is the final composited surface of both the underlying shadow terminal and all the active Tattoys. A diff of this with the user's current real terminal is then used to do the final update to the user's live terminal.

Testing

We use cargo nextest, which you will need to install if you haven't already.

cargo build --all; cargo nextest run

In CI I use cargo nextest run --retries 2 because some of the end-to-end tests are flaky.

Debugging

• Set log_level = "trace" in $XDG_CONFIG_DIR/tattoy/tattoy.toml
• Detailed GPU logs are disabled by default, to enable them use something like TATTOY_LOG="tattoy_wezterm_term=off,tattoy=debug,wgpu=debug" tattoy.
• Default log path is $XDG_STATE_DIR/tattoy/tattoy.log.
• Log path can be changed with log_path = "/tmp/tattoy.log" in $XDG_CONFIG_DIR/tattoy/tattoy.toml
• Or log path can be changed per-instance with the --log-path CLI argument.