Show HN: Tattoy – a text-based terminal compositor

190 tombh 63 6/13/2025, 2:04:35 PM tattoy.sh ↗
Whereas this is mostly a terminal eye-candy project to get you street cred, it does have some serious aspects.

Firstly it solves the age-old problem of low-contrast text, like when you `ls` a broken symlink and the red background colour is too near your current theme's foreground colour. Tattoy solves this by using none other than the web's WCAG 2.1 contrast algorithm for accessible text.

Secondly, an explicit design goal is that Tattoy should be able to polyfill new terminal protocols, the `xwayland` of the TTY if you will. Say if we want to experiment with completely deprecating ANSI codes, then any application that uses a new protocol can be run in Tattoy which itself runs in any ANSI-standard terminal emulator as normal. You can read more about this idea here: https://tattoy.sh/news/an-end-to-terminal-ansi-codes/

But ultimately this has been something more akin to an art project, something to enjoy for the sheer aesthetic pleasure.

Comments (63)

tfsh · 1d ago
This looks really cool, I'd like to give it a go. The idea of taking a screenshot of the terminal and then parsing that to determine the true colour support is definitely novel, though perhaps so, because for me I can't get it to work. Are there any debug flags I can enable?

So far it was able to take the screenshot correctly (https://ibin.co/8kaRr8TIanv2.png), however the parsing of that fails with the non-descript "Palette parsing failed." error.

Edit: enabled tracing at got this: https://paste.ee/p/ZyNxG9FK

shiomiru · 1d ago
> The idea of taking a screenshot of the terminal and then parsing that to determine the true colour support is definitely novel,

A better way to do this is to send `OSC 1 0 ; ? ST` (query foreground color), `OSC 1 1 ; ? ST` (background color), then `OSC 4 ; {n} ; ? ST` where {n} is the nth XTerm color.

See: https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h4-O...

tombh · 1d ago
OMG really!? That link is blocked for me for some reason. If that OSC code is widely supported it's going to make things sooooo much easier.
ku1ik · 23h ago
It’s very widely supported from my experience. This is how asciinema captures terminal palette.
hnlmorg · 23h ago
It’s supported by any xterm compatible terminal emulator. But like with most things in this domain, expect plenty of edge cases where it should work but doesn’t.
tombh · 1d ago
Thanks for trying it out. It looks like either your terminal or screenshotter isn't faithfully rendering the pure red marker column (it's needed for calibration in the parser). The red should be #ff0000, but the screenshot is using #ea3323. I've made a Github issue to keep track https://github.com/tattoy-org/tattoy/issues/98 If you can add more details it'd really useful, I'm sure there'll be more people like you.
mkesper · 10h ago
Maybe that's night mode (or whatever your DE calls it)?
tombh · 8h ago
Interesting, I'd never thought of that.
sevensor · 7h ago
I especially like the idea of evolving the protocol. Just because the text first ui is a great idea doesn’t mean we achieved perfection with ansi escape codes.
pvg · 1d ago
b0a04gl · 5h ago
do you virtualise the terminal state fully or just overlay visual layers? like if a child process writes malformed escape sequences or resizes mid frame, who owns the state resolution : tattoy or the underlying tty?
TheSilva · 1d ago
I see you added then removed Windows from your Release plan:

https://github.com/tattoy-org/tattoy/issues/42

So, it is supported or not? Looks great by the way.

tombh · 1d ago
Thank you.

Windows is supported, I've tested it in Windows Terminal and Powershell. I removed it that issue from the release plan because not all the subtasks are finished yet. And more broadly speaking I just haven't had much feedback from Windows users. For example I haven't managed to get GPU passthrough working in my Windows VM so haven't actually been able to test shaders yet.

PeterStuer · 15h ago
On which hypervisor?
tombh · 8h ago
QEMU. I'm on Asahi Linux (Linux for M-series Macs) and we've only just got virtualisation support in the last few months.
em-bee · 1d ago
Tattoy manages its own scrollback buffer (like say `tmux` does), and so can therefore also provide its own scrollbar.

this raises two questions: doesn't every (gui) terminal do that?

what happens if i use tmux inside tattoy?

btw: do you have examples of light themes?

tombh · 1d ago
Yes, every GUI terminal manages its own scrollback buffer. The reason that Tattoy and tmux have their own buffers is because they are essentially terminal emulators themselves. For instance a terminal emulator may have 10 tmux panes and it should of course be possible to view the history of each one. Tattoy manages its own scrollback because that's the only way to make the scrollback available programatically to other processes, like the minimap for example.

Interestingly Alacritty in the beginning didn't natively support scrollback because it wanted to hand-off that concern to multiplexers like tmux. So there's precedent for terminals emulators not having to support scrollback.

tmux should work fine in Tattoy, the only thing to be aware of is that Tattoy would then handle input, like for scrolling etc, so some events may not reach tmux, in which case you could make some custom tmux keybindings that Tattoy doesn't recognise. It's also worth noting that Tattoy recognises the so-called "alternate screen" state that tmux controls its host with. And in such cases Tattoy forwards scrolling events to the underlying process, like say the mouse scroll wheel.

I don't have any light theme examples yet. It should mostly just work though.

em-bee · 1d ago
my first attempt at using a light theme with gnome-terminal gets me white on white either in the prompt or on the commandline itself. don't have time to debug that now though.

what i was wondering is how the scrollback of tattoy and tmux would interact. normally when you use tmux the terminals scrollback remains unused (which is why alacritty devs thought they don't need their own). but from how tattoy uses the scrollback, i feared that tmux would actually interfere with some tattoy functionality. that's what i am curious about.

tombh · 1d ago
Oh white on white isn't good, sorry about that, I'll look into it.

I also have some ideas to make Tattoy into a multiplexer. I really like the idea of desaturating and fading unfocussed panes.

cb321 · 10h ago
Interesting project. You might check out Arcan (https://arcan-fe.com/) if you've never heard of it. (EDIT: I see author recently added a link: https://github.com/tattoy-org/tattoy/blob/main/website/conte... )

A couple of points related to contrast ratio management:

- The Mynex answer here is very informative: https://stackoverflow.com/questions/596216/formula-to-determ...

- The "limit/bound" on the contrast ratio has a "polarity" (a +- sense). At least for "text", in almost every font there are many more background pixels than foreground pixels. So, for example, your human eyes can tolerate a lower text cell fg-bg contrast with a dark background color for the text cell on an all-black background than they can for a dark foreground color on an all-black background. Part of this relates to "shared discrimination work" that the outside-the-text cell background pixels are doing. So, really "ratio" of just two things is somewhat of an oversimplification.

- XTerm OSC 4 may have a very limited ability to probe the color palette. At least on `st` I can only see default foreground, background and cursor colors, not the full 16-color palette. This mostly just amplifies the point elsethread by @hnlmorg.

- At least until more recent ssh's, default configs on Linux would pass through all "LC_*" environment variables. So, if you adjust your shell rc/configs to key off of, say, $LC_THEME having, e.g., "light" or "dark" in them, you can perhaps re-polarize everything with a much lower tech solution. I do this all the time as I like to run some terminals with a black background and some with a white background. (Paper white black & white displays were all the rage in the 90s, but these days "color hackers" seem to prefer dark backgrounds. I have theories as to why, but it's pretty off topic.) https://github.com/c-blake/lc configs have more fully fleshed out examples, and hey, you might also like that color-ls. (And I'm aware of the ancient & to my mind ugly 1980s ideas of "stuff everything into $TERM and parse it apart again". Security concerns may push us back that way.)

shiomiru · 6h ago
> XTerm OSC 4 may have a very limited ability to probe the color palette. At least on `st` I can only see default foreground, background and cursor colors, not the full 16-color palette. This mostly just amplifies the point elsethread by @hnlmorg.

What st version? For me, 0.9.2 prints the entire color cube with

    for n in `seq 0 255`; do printf '\033]4;%d;?\033\\' "$n"; done; read
(although unsurprisingly, it's subtly broken: I sent ST, but the responses are terminated with BEL...)
cb321 · 3h ago
You are completely right. It totally "works" now { scare quotes as per your termination comment.. ;-) . I guess xterm terminates in the answer back with whatever the client sends in the request. It's funny how now things began as DEC vtXX emulators and now things are "xterm emulators". }

Thank you for correcting the record, @shiomiru!

tombh · 8h ago
Wow thanks for all this insight. I'd never considered the idea that the ratio of foreground to background pixels impacts the visual perception of text readability. Of course that totally makes sense now that I think about it. Do you know if that's been considered anywhere in the WCAG standards?

I'm thinking that I'm going to support both palette screenshotting and OSC 4.

I've certainly seen those LC_* variables before but I don't seem to have them right now in my current shell. Are you saying that they can be another source of the true colour values of the palette indexes?

cb321 · 6h ago
AFAICT, this "number of pixels" (as well as the outside-the-cell pixels) effect is one of those "obvious as heck if you experiment on yourself with barely any science or even just contemplate it" things that somehow winds up ignored in standards. I'd love to be wrong, though.

The screenshotting is surely more portable.

I was not saying LC_* are a source of color values, though a terminal could surely do that as a way to export this data to its first shell without the clunky stdin/out protocols for OSC4. For example, I believe one variant of rxvt/urxvt used to export COLORFGBG. I would even say (LC_FG LC_BG LC_COLOR0..15 LC_CURSOR, etc) is an ok idea. One downside is a user could change the values since environment variables are very much not "read only", but that is sort of "on them" for fooling subprocesses "on purpose".

I was mostly lamenting that ssh server configs are moving toward making it hard(er) to "pass through" this kind of environment variable-driven setup. Something people often overlook in this general problem space is making whatever protocol they come up with also "work through to shells beyond one (or more) ssh hops". So, the LC_COLOR<N> idea would have been "more fabulous" 5..10 years ago when I would have anticipated "this will usually work". Maybe it could still be easier for some than OSC4.

Anyway, big topic with half century of history and hard to be brief.

nerflad · 1d ago
This is brilliant, thanks for making public and best wishes
otterpro · 1d ago
I'd probably run cmatrix for looks or maybe htop on the background. Also, Rick-rolled in the screenshot.
msgodel · 1d ago
It seems like what you really wanted was a streaming SVG renderer and not a VTE.

I kind of like that idea.

tombh · 1d ago
How do you mean? I'm actually not a fan of terminal image protocols like Sixel and Kitty's image protocol. I value the constraints of only being able to use text. I feel that in some ways when we venture into real graphics the soul of the terminal is lost.
msgodel · 1d ago
Maybe I'm confused, I guess this is more an aesthetic thing than a practical thing. I just see VTEs as a minimal UI API for software.
tombh · 1d ago
I'm curious about your minimal UI API idea.
grandma_tea · 1d ago
Oh wow, now I can finally have terminal that creates fire effects the faster I type! (if I ever get the time to make the plugin)

Is there anyway for plugins to interact with shaders?

tombh · 1d ago
Intenser flames the more you type, great idea!

Plugins can't currently get the shader pixels. But that's just because I haven't added them to the plugin protocol yet. But interestingly shaders actually have access to the terminal contents in the form of a pixelated version of the text. And the mouse and cursor position too. So maybe there's something you could do purely in a shader.

pacifika · 1d ago
Nice idea, I like the out of the box thinking on display.
MatthewPhillips · 1d ago
This looks amazing. Well done.
cenobyte · 1d ago
Because why shouldn't my terminal be the largest consumer of memory on my PC?
tines · 1d ago
I paid for 32GB, I’m gonna use 32GB.
ainiriand · 1d ago
Can it run doom?
tombh · 1d ago
There is actually a Shadertoy for Doom! https://www.shadertoy.com/view/lldGDr So in theory Tattoy could run it, the only thing is that it doesn't currently support extra buffers and that Doom shader needs 5 of them.
gfalcao · 1d ago
SUPER COOL
djaychela · 1d ago
Id probably have an easier time finding out about this project if it didn't full screen auto play videos as I scroll?
tombh · 1d ago
I didn't intend for the videos to be fullscreen. They need to be small in order to save bandwidth. They're certainly autoplaying (to replicate GIF behaviour), but maybe there's a bug with them going full screen. What browser are you using?
djaychela · 1d ago
Firefox on ios. They are full the screen and auto play as soon as I get to whatever part of the page they are on.

Tbh I think giving the user voice as to whether to play them would be a better experience anyway, but it's really unusable as is.

phatskat · 1d ago
I get the same experience on iOS using the OS web view - my guess is because iOS (and maybe android?) don’t typically play videos in “windowed mode” (for lack of a better term) outside of eg Google video snippets which seem to do some hacky stuff to keep you “in Google” while watching.

Regardless of the fullscreen aspect, and understanding you wanted something jiff-like, I also don’t care much for auto playing video. It doesn’t matter too much if it’s small (as this is intended), silent (as terminals typically are), and doesn’t hoist control of my browser.

Edit: forgot to say that this looks really cool, great work!

Editedit: also forgot to mention that the thumbnails are super blurry on my phone, and after the one video took control of the screen, all the other thumbnails went black.

tombh · 8h ago
Thank you!

Thanks to another commenter I've added `playsinline` to the video tag, so hopefully that fixes it.

What do you think a suitable size for all these video/gif assets is? I'd be totally happy to move to .gif or animated .webp but I can seem to get they're filesizes down to a reasonable size.

djaychela · 5h ago
Totally sorted the usability for me. TBH I'm not that fussed about data sizes provided it's not mental but most importantly I can now actually -read- what you've done!
eieio · 19h ago
I think you just need to add "playsinline" to your videos so that they play inline on mobile devices instead of fullscreening.

    <video autoplay loop muted playsinline>
instead of your current

    <video autoplay loop muted>
cool project :)
tombh · 8h ago
Thank you, I added it! Let's see if it helps.
eieio · 7h ago
looks good for me on mobile now!
ramon156 · 1d ago
This is like the pinnacle of term ricing, I love it
phatskat · 1d ago
Ricing?
efilife · 23h ago
Ricing means making your setup pretty with extensive customization.

https://www.reddit.com/r/unixporn/ https://github.com/fosslife/awesome-ricing

phatskat · 22h ago
Ah I see, but why that term?
emmelaich · 17h ago
A 'ricer' is a small Japanese sports car (e.g. Subaru WRX or Mitsubishi Evo) souped up or given fancy paint job and spoilers etc). Rice for the country of origin.
rhet0rica · 15h ago
To further elucidate, it's a contraction of "rice burner," suggesting the vehicle uses rice as fuel.

https://en.wikipedia.org/wiki/Rice_burner

As Wikipedia relates, "rice burning" refers to a technique of clearing the roots of a rice paddy with fire after a harvest, a bit like slash-and-burn in forestry, and "rice burner" was indeed used as a slur against East Asian people in the second quarter of the twentieth century.

However, simlevesque is not wrong—the term is not usually used in the modding community in a bigoted manner, despite its obvious past association with bigotry. Rather, because Japanese cars were affordable, modding them was seen as cheap, so a car enthusiast with a modded Japanese car was considered a wannabe or imposter, especially if the modifications made their car superficially resemble traits associated with expensive American and European muscle cars, such as extra tailpipes or a louder engine. The ultimate vehicle for these modding jobs was the Honda Civic, which was plentiful and had lots of kits made for it; when Honda released the high-performance Type R edition street racers were quick to expand the "R" to "Rice" (only a mild alteration of the intended meaning, which was something like "Racetrack-worthy.")

In computing, the jargon of "ricing" or "being a ricer" carries a slight air of self-deprecation because front-end customization enthusiasts recognize their endeavors are shallow—many of them can barely administrate the Arch Linux installs they've set up, and almost none of them actually do any programming. The heart of this community remains 4chan's /g/ board, though arguably Reddit owes its entire existence to such people.

notnmeyer · 21h ago
Pretty sure it’s racist (or at least pejorative) in origin referring to the asian car customization / import scene.
simlevesque · 18h ago
It's the term used by the community.
hnlmorg · 23h ago
> Firstly it solves the age-old problem of low-contrast text, like when you `ls` a broken symlink and the red background colour is too near your current theme's foreground colour.

That’s already a solved problem. You use a terminal theme that produces high contrast against all the 16 terminal colours.

Plenty of good themes exist.

The bigger problem, in my opinion, is software that uses 8 bit or 16 bit colour ANSI codes and thus overrides your terminals theme. Personally I consider this rude behaviour but I know there is a subset of HN that disagrees with me here.

ku1ik · 22h ago
My understanding is it ensures proper contrast for all cells regardless of the type of fg/bg color (palette, 8 bit, 24 bit). So if a program uses 24 bit fg color and a bg from palette (or a default one) it would still preserve the contrast. (haven’t tested, just my impression from reading the docs)
hnlmorg · 11h ago
That’s my point though. People abuse the other palettes.

This is why we can’t have nice things.

tombh · 8h ago
I've never actually made a palette, but it just doesn't seem practical to me to expect theme creators to always find a contrast-safe 16 colour palettes. I would imagine that it even seriously restricts the range of themes that can be made. I can imagine that such a thing is possible for smaller palettes like say 3 colours though, but then that's not actually useful for UIs.

I think the fact is that small palettes come from the days of lower resources, not from efficient program design.

PeterStuer · 15h ago
Now we get Rickrolled in the terminal. Great! /s.