# Sequin: reading ANSI escape sequences as human readable text

> Sequin is a small Go utility from the Charm project that takes a stream of ANSI escape sequences and explains what each one does. You pipe program output into it, or use it to describe sequences you do not recognise, and it also ships a raw mode that highlights the sequences inline in otherwise plain text.

**charmbracelet/sequin** — Human-readable ANSI sequences 🪩

- Repository: https://github.com/charmbracelet/sequin
- Stars: 814 · Forks: 17
- Language: Go
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/charmbracelet-sequin

## A pretty printer for escape sequences

Sequin describes itself as human-readable ANSI sequences, and the README explains the intent with a short list of use cases.

It is a small utility to debug command line and terminal user interfaces. It is also good for describing escape sequences you might not understand, and for exploring what terminal applications are doing under the hood. There are more use cases beyond those, such as inspecting golden files, the reference output files used by test tooling to crystallise the output of a Bubble Tea program.

The mechanism is a filter. You pipe a stream into Sequin and it prints the same stream with each escape sequence replaced by a description of what that sequence does. That is a small idea, and it is the reason the tool is useful, because the alternative to reading an escape sequence is to look up its byte values in a table and reconstruct the meaning in your head.

The project comes from the Charm organisation, the group behind the Bubble Tea terminal application framework and the Lip Gloss styling library, and the code is Go with the MIT licence. The current release is v0.3.1.

## Installation, in more ways than most small tools offer

The installation section is longer than the feature list, and that is a statement about how much care the distribution side gets.

The package manager route covers macOS and Linux with brew, Arch Linux with yay, and Nix in two forms, one from the NUR repository and one from the standard channel.

```bash
brew install sequin
```

```bash
nix-shell -p sequin
```

There are dedicated instructions for Debian and Ubuntu, which add the Charm apt repository with a key in the keyrings directory and then install the package, and for Fedora and RHEL, which add a yum repository file and install from it.

```bash
echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | sudo tee /etc/apt/sources.list.d/charm.list
sudo apt update && sudo apt install sequin
```

Beyond the package managers there are Debian and RPM packages and binaries for Linux, macOS, Windows, FreeBSD, OpenBSD and NetBSD, all on the releases page, and a go install line for people who already have a Go toolchain.

```sh
go install github.com/charmbracelet/sequin@latest
```

Shell completions come with the packages and the archives, pre-generated for Bash, ZSH, Fish and PowerShell, and if you built from source you can generate them yourself with the completion subcommand.

## Describing sequences and reading program output

The first example sends sequences to Sequin directly with printf and gets an explanation back.

```bash
printf "\x1b[38;5;4mCiao, \x1b[1;7mBaby.\x1b[0m\n" | sequin
```

The second use is the one that comes up in practice, which is piping the output of another program into Sequin to see what it emitted.

```bash
ls -1 --color=always | sequin
```

```bash
git -c status.color=always status -sb | sequin
```

There is an important caveat in the README, and it is the thing most likely to make you think the tool is broken. Many programs render their output as plain text when the output is not a terminal, which is exactly what happens when you redirect to a file or pipe to a program such as Sequin. The README says this is a good thing in general, and the fix is that there are usually ways to force colour, such as setting the CLICOLOR_FORCE environment variable or using a flag that forces ANSI output. If you see no sequences, check what works for that specific program.

Both examples above show that in practice: the colour flag on ls, and the git configuration that turns status colour on regardless of the destination.

## Golden files and running commands under a fake terminal

The third use case is the test oriented one. Golden files for terminal applications contain ANSI sequences, and Sequin makes them legible.

```bash
cat ./testdata/MyCuteApp.golden | sequin
```

A golden file is the expected output that a test compares against, and in a TUI the expected output includes the escape sequences the program uses to move the cursor, clear the screen and colour the text. Reading one as raw bytes is close to useless, and reading one through Sequin tells you what the application intended to draw.

The README points at the golden and teatest helpers from the Charm experimental package for generating those files, so the workflow is generate a golden file with the test tooling, then read it with Sequin when the diff is not obvious.

The fourth use is the fake terminal. Sequin can execute a command itself, which means the program under inspection sees a terminal on the other end.

```bash
sequin -- ls -1 go.*
```

That solves the problem described a moment ago from the other direction. Instead of forcing a program to emit colour when its output is not a terminal, Sequin gives it a pseudo terminal to write to, and then describes what arrived. The dependency list confirms the approach, with a pseudo terminal package and a Windows console package among the indirect requirements.

There is also a raw mode, flagged with the raw option, which highlights the sequences inline instead of expanding them into descriptions.

```bash
git -c status.color=always status -sb | sequin -r && echo
```

That is the mode to use when you want the text around the sequences preserved exactly, with the sequences marked in place.

## What it supports, and what it does not

The README has a section titled asking whether it is done, and the answer is no.

Common sequences are implemented, but there is still plenty of work to do, and APC sequences are given as the example of something not supported yet. If you notice a missing sequence, or want to work on another area, the project asks for a pull request.

The implementation depends heavily on the ansi package from the Charm experimental project, which the README describes as currently living in that repository. Sequin traverses the strings and pretty prints what the sequences are and what they are doing, so the parsing of the escape sequence grammar is not in this repository.

That is a sensible division of labour, and it has an obvious consequence for anyone reading the code or contributing to it. The knowledge of what a sequence means lives in the ansi package, so a change to the behaviour of a particular sequence is usually a change there, and the Sequin repository is about presentation.

The multiplexer caveat in the FAQ is worth understanding as well. The question asked is why Sequin is not using the terminal background colour, and the answer points at the multiplexer rather than at Sequin. Terminals expose the background colour through OSC 10 and OSC 11 queries, and support for those queries was added to tmux in version 3.4, and GNU screen needs version 4.99.0 or higher. On an older multiplexer the query never comes back and the background colour is simply unavailable, which is a terminal stack problem rather than a Sequin problem.

## Repository layout and how it is built

The top level of the repository is one Go file per family of sequences, which is the clearest statement of how the tool is organised.

There are files for the graphics rendition sequences, for cursor movement, for hyperlinks, for kitty keyboard protocol support, for termcap handling, for themes, for notifications, for pointer styles, for screen handling, for window titles and for the extended sequences. Then there are the behavioural files: clipboard, colour, working directory, execution, final terminal state and the handlers, plus the mode handling, the line handling and the main entry point.

That per-sequence-file layout is why the project can say that common sequences are implemented: adding support for a sequence family means adding a file, not editing a switch statement.

There are two directories of test material, a tapes directory for recorded terminal sessions and a testdata directory with the sample files, and a main test file at the root. The build is driven by GoReleaser, with the configuration at the root, which is what produces the binaries for the six platforms the README lists.

The module file lists the dependencies, and they are informative about the design. There is the ansi parser, a colour profile package for terminal capability detection, the xpty pseudo terminal package, the term package, the golden file helper, Cobra for the command line interface, Lip Gloss v2 for the output styling, and the fang package for the command line help output.

The module targets Go 1.24.2.

## Maintenance, licence and what to check

The release tags are v0.3.1 from 2025-01-27, v0.3.0 from 2024-12-09 and v0.2.0 from 2024-11-25, and the last push was on 2026-10-01.

So the version line is pre-1.0 with patch releases, and the branch is being worked on more recently than the last tag. The CHANGELOG is not in the repository root, so the releases page is where the change history lives.

The licence is MIT, with the LICENSE file at the root of the repository.

Three checks before you make Sequin part of a workflow.

Whether the program you want to inspect can be made to emit colour when its output is not a terminal, either through a flag or through an environment variable, because otherwise the pipeline produces plain text and nothing to explain.

Whether your multiplexer is recent enough for the background colour queries, which means tmux 3.4 or higher and GNU screen 4.99.0 or higher.

And whether the sequence types you care about are in the implemented set, since APC sequences are named as unsupported and the project is explicit that coverage is incomplete. For a tool whose value is being complete about what it does not handle, that is the right thing to check first.

## Conclusion

Sequin suits a developer who works with terminal applications and wants to know what a program is actually emitting, since it turns unreadable byte soup into a description of what each sequence does and works on any stream you can pipe into it, including golden files from TUI test suites. It is the wrong tool if you need a full terminal emulator, since it describes sequences rather than rendering them, and the wrong choice for a protocol it does not cover, since APC sequences are not supported yet. Verify first that the program you want to inspect emits colour when its output is not a terminal, because the README points out that most tools strip ANSI in that case, and check that your multiplexer is recent enough to answer the background colour queries the tool relies on.

## FAQ

### What does the Sequin tool do?

It takes a stream containing ANSI escape sequences and prints them as human readable text, describing what each sequence does. It can be used on sequences you do not recognise, on the output of other programs, and on golden files from TUI test suites.

### How do I install Sequin?

Through Homebrew, yay on Arch, Nix, the Charm apt repository on Debian and Ubuntu, the Charm yum repository on Fedora and RHEL, prebuilt binaries for Linux, macOS, Windows, FreeBSD, OpenBSD and NetBSD, or with go install github.com/charmbracelet/sequin@latest.

### Why does piping a program into Sequin show no escape sequences?

Because most programs render plain text when their output is not a terminal. The README explains that you usually have to force colour, for example with the CLICOLOR_FORCE environment variable or a program specific flag.

### Does Sequin support every escape sequence?

No. The README says common sequences are implemented but there is still work to do, and names APC sequences as not supported yet. The project asks for pull requests covering missing sequences.

## Sources

- [charmbracelet/sequin on GitHub](https://github.com/charmbracelet/sequin)
- [Issues](https://github.com/charmbracelet/sequin/issues)
- [License: MIT](https://github.com/charmbracelet/sequin/blob/main/LICENSE)
- [README](https://github.com/charmbracelet/sequin/blob/main/README.md)
- [Releases](https://github.com/charmbracelet/sequin/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/charmbracelet-sequin