https://github.com/lmorg/ttyphoon
The Next Generation Terminal Emulator
https://github.com/lmorg/ttyphoon
bash fish gui linux macos multimedia murex shell terminal-emulator tmux tui zsh
Last synced: 5 days ago
JSON representation
The Next Generation Terminal Emulator
- Host: GitHub
- URL: https://github.com/lmorg/ttyphoon
- Owner: lmorg
- License: gpl-2.0
- Created: 2023-12-17T11:59:37.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2026-07-02T10:11:40.000Z (11 days ago)
- Last Synced: 2026-07-02T12:09:11.449Z (11 days ago)
- Topics: bash, fish, gui, linux, macos, multimedia, murex, shell, terminal-emulator, tmux, tui, zsh
- Language: JavaScript
- Homepage:
- Size: 34.2 MB
- Stars: 38
- Watchers: 1
- Forks: 1
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
TTYphoon
- [Multimedia Terminal Emulator](#multimedia-terminal-emulator)
- [Screenshots](#screenshots)
- [Output Blocks](#output-blocks)
- [Structured Text](#structured-text)
- [Tables](#tables)
- [Images](#images)
- [Tmux Support](#tmux-support)
- [Highlighted Search Results](#highlighted-search-results)
- [Markdown Viewer](#markdown-viewer)
- [Vim-style Editor Keys](#vim-style-editor-keys)
- [Programming Language Tools (LSP)](#programming-language-tools-lsp)
- [Config Files](#config-files)
- [Swagger](#swagger)
- [Non-Intrusive AI](#non-intrusive-ai)
- [How It Works](#how-it-works)
- [Whats Left To Do](#whats-left-to-do)
- [Escape Codes](#escape-codes)
- [VT100](#vt100)
- [VT52 mode](#vt52-mode)
- [VT200 mode](#vt200-mode)
- [Tektronix 4014 mode](#tektronix-4014-mode)
- [Window management codes](#window-management-codes)
- [Extended features](#extended-features)
- [Common application support](#common-application-support)
- [Application Usability](#application-usability)
- [Supported Platforms](#supported-platforms)
- [Install Guide](#install-guide)
- [VT Debugging](#vt-debugging)
- [AI Tracing](#ai-tracing)
- [How To Support](#how-to-support)
## Multimedia Terminal Emulator
The aim of this project is to provide an easy to use terminal emulator that
supports inlining multimedia widgets.
Currently the project is _very_ alpha.
The idea behind this terminal emulator is that is can be used by any $SHELL,
however hooks will be built into [Murex](https://github.com/lmorg/murex) so
the terminal will be instantly usable even before wider support across other
shells and command line applications is adopted.
At its heart, TTYphoon is a regular terminal emulator. Like Kitty, iTerm2, and
PuTTY (to name a few). But where TTYphoon differs is that it also supports
inlining rich content. Some terminal emulators support inlining images. Others
might also allow videos. But none bar some edge case Electron terminals offer
collapsible trees for JSON printouts. Easy to navigate directory views. Nor any
other interactive elements that we have come to expect on modern user
interfaces.
The few terminal emulators that do attempt to offer this usually fail to be
good, or even just compatible, with all the CLI tools that we've come to depend
on.
TTYphoon aims to do _both well_. Even if you never want for any interactive
widgets, TTYphoon will be a good terminal emulator. And for those who want a
little more GUI in their CLI, TTYphoon will be a great modern user interface.
## Screenshots
### Output Blocks
Command output is grouped into blocks to make it easier to visually see the
separation between different command output.
Those blocks are coloured too, to help identify whether a command succeeded or
failed.
Those blocks can be highlighted by hovering over them
And even collapsed, hidden from view
### Structured Text
IDE-like tools for working with structured text, like JSON. Hover over a branch
to highlight its child nodes
Click to collapse that block of text
### Tables
Output can be presented as tables. Which can be sorted and even filtered using
SQL. All without having to rerun the commands that generated that output
### Images
Support for inlined images, where images are treated as images. for example
they can be copied to clipboard
### Tmux Support
Tmux support built in using tmux's control plane. This allows for the power of
tmux but with the easy of use and elegance of being fully integrated into the
terminal emulator
(in this screenshot, tmux's prefix key was rebinded to `F2` in `~/.tmux.conf`)
### Highlighted Search Results
Search terms can be highlighted to quickly find instances of that term
### Markdown Viewer
You can write notes in markdown alongside your terminal sessions. View readme's, have your documentation with you instead of switching between windows
And you can even execute the code blocks inline. Bringing you the flexibility of Jupyter Notebooks and the power of a full terminal emulator
### Vim-style Editor Keys
The Notes editor and Jupyter code blocks support Vim-style keyboard navigation. Press `Escape` to enter Normal mode; a mode indicator appears in the bottom-right corner of the editor. Press `i` (or any insert command) to return to regular editing.
#### Mode entry
| Key | Action |
|-----|--------|
| `Esc` | Enter Normal mode |
| `i` | Insert before cursor |
| `a` | Insert after cursor |
| `I` | Insert at first non-blank of line |
| `A` | Insert at end of line |
| `o` | Open new line below, insert |
| `O` | Open new line above, insert |
| `R` | Enter Replace (overtype) mode — all typed characters overwrite |
| `r{char}` | Replace single character under cursor, stay in Normal |
#### Navigation (Normal mode)
| Key | Action |
|-----|--------|
| `h` / `←` | Left |
| `l` / `→` | Right |
| `j` / `↓` | Down |
| `k` / `↑` | Up |
| `w` | Forward to start of next word |
| `b` | Back to start of previous word |
| `e` | Forward to end of word |
| `0` | Start of line (column 0) |
| `^` | First non-blank character of line |
| `$` / `End` | End of line |
| `gg` | First non-blank of file |
| `G` | Last non-blank of file |
| `{n}G` | Go to line *n* |
| `%` | Jump to matching bracket (`(` `)` `[` `]` `{` `}`) |
#### Operators (combine with a motion or double for whole line)
| Key | Action |
|-----|--------|
| `d{motion}` | Delete range covered by motion |
| `dd` | Delete current line |
| `D` | Delete to end of line |
| `c{motion}` | Delete range and enter Insert |
| `cc` | Change current line |
| `C` | Change to end of line |
| `y{motion}` | Yank (copy) range into internal register |
| `yy` / `Y` | Yank current line |
| `x` | Delete character under cursor |
| `X` | Delete character before cursor |
| `p` | Paste yanked text after cursor |
| `P` | Paste yanked text before cursor |
| `u` | Undo |
All operators and motions accept a **count prefix** (e.g. `3w`, `5dd`, `10j`).
### Programming Language Tools (LSP)
Notes can attach a language server when the current file type resolves to a configured entry in `Notes.LSP`.
Current Notes LSP support includes:
- diagnostics with gutter markers and inline squiggles
- hover and signature help
- completion
- go to definition
- workspace symbol
- inlay hints
- code lens actions
- semantic tokens
- document and range formatting
- code actions / quick fixes
- rename symbol
- document symbols
LSP servers are configured in the main config file under `Notes.LSP`. Keys are canonical language ids and values are the command argv used to start the server.
Example:
```yaml
Notes:
Languages:
go:
LSP: [gopls]
javascript:
LSP: [typescript-language-server, --stdio]
typescript:
LSP: [typescript-language-server, --stdio]
terraform:
LSP: [terraform-ls, serve]
TabSpaceIndent: 2
python:
LSP: [pylsp]
```
Notes resolves the language id from the same Jupyter language metadata used elsewhere in the project, so file extensions such as `.go`, `.js`, `.ts`, `.tf`, and `.py` map onto the configured LSP entries automatically.
Current Notes LSP behavior:
- enablement is automatic when a matching `Notes.LSP.` entry exists
- startup failures are surfaced to the UI instead of failing silently
- hover content supports markdown rendering and external links
- inlay hints render inline in the editor overlay when the server provides them
- code lens actions are available from the editor context menu when provided by the server
- semantic tokens render in the editor overlay when the server provides them
- completion and code actions are currently mouse-driven in the MVP UI
Current limitations:
- no dedicated LSP hotkeys in the MVP UI yet
- incremental sync is not enabled yet
### Config Files
Work with JSON and YAML config files more easily
### Swagger
Native support for Swagger and OpenAPI files. So you don't need to be a `curl` expert all of the time
### Non-Intrusive AI
AI is crammed everywhere - even where you don't want it. TTYphoon integrates AI but does so non-intrusively. It's there if you need to quickly debug something. Or want to quickly generate code. Or not there if you prefer. It isn't a clown constantly fighting you for your attention.
## How It Works
TTYphoon native code in the backend to provide fast computation and then pushes the last mile rendering to webkit.
This ensures that the terminal reuses performant existing technologies which have already been fine-tuned by larger organisations like Apple, Microsoft and Google. But without the _massive_ overhead of running Electron or other Chrome-based solutions.
The multimedia and interactive components will be passed from the controlling
terminal applications via ANSI escape sequences. Before groan, yes I agree that
in-band escape sequences are a lousy way of encoding meta-information. However
to succeed at being a good terminal emulator, it needs to support some historic
design decisions no matter how archaic they might seem today. This allows
TTYphoon to work with existing terminal applications _and_ for third parties to
easily add support for their applications to render rich content in TTYphoon
without breaking compatibility for legacy terminal emulators.
## Whats Left To Do
In short, _a lot_!! Some of what has been detailed above is still in a _very_
alpha state. And while there is lots of error handling and unit tests, test
coverage is still pretty low.
Below is a high level TODO list of features and compatibility. If an item is
ticked but not working as expected, then please raise an issue in Github.
### Escape Codes
#### VT100
- C1 codes
- [x] common: can run most CLI applications
- [x] broad: can run older or more CLI applications
- [ ] complete: xterm compatible
- CSI codes
- [x] common: can run most CLI applications
- [x] broad: can run older or more complicated CLI applications
- [ ] complete: xterm compatible
- SGR codes
- [x] common: can run most CLI applications
- [x] broad: can run older or more complicated CLI applications
- [ ] complete: xterm compatible
- [ ] extended underline: kitty compatible
- OSC codes
- [x] common: can run most CLI applications
- [x] broad: can run older or more complicated CLI applications
- [ ] complete: xterm compatible
- DCS codes
- [ ] common: can run most CLI applications
- [ ] broad: can run older or more complicated CLI applications
- [ ] complete: xterm compatible
- [x] Alt character sets
- [x] Wide characters
- [ ] vt100 (ASCII characters)
- [x] Unicode (eg logograph-centric languages and emoticons)
- Keyboard
- [x] Ctrl modifiers
- [x] Alt modifiers
- [x] Shift modifiers
- [x] special keys (eg function keys, number pad, etc)
- [ ] glitch free (some bugs still exist)
- [x] tmux support for modifiers
- Mouse tracking
- [ ] common: can run most CLI applications
- [ ] broad: can run older or more complicated CLI applications
- [ ] complete: xterm compatible
#### VT52 mode
- [ ] cursor movements
- [ ] special modes
#### VT200 mode
Some compatibility already exists. Detailed breakdown coming...
#### Tektronix 4014 mode
- [ ] graphics plotting
- [ ] text rendering
#### Window management codes
eg `xterm` and similar terminal emulators
- [x] titlebar can be changed
- [ ] ~~window can be moved and resized (WILL NOT IMPLEMENT)~~
- [ ] window can be minimized and restored
#### Extended features
- [ ] Hyperlink support
- [x] Auto-hyperlink files
- [x] Auto-hyperlink URLs
- [ ] ANSI escape sequence supported (rejected because of safety concerns)
- [ ] Bracketed paste mode
- [x] Inlining images
- [x] TTYphoon codes
- [ ] iterm2 compatible
- [ ] Kitty compatible
- [x] sixel graphics
- [ ] ReGIS graphics
- [x] Code folding
- [x] Table sorting
- [x] alpha: available but expect changes to the API
- [x] stable: available to use in Murex
#### Common application support
- [x] Supports `tmux`
- [x] usable from CLI
- [x] glitch-free from CLI
- [x] tmux control mode supported
- [x] Supports `vim`
- [x] usable
- [x] glitch-free
- [x] Supports `murex`
- [x] usable
- [x] glitch-free
### Application Usability
- [x] Terminal can be resized
- [x] Scrollback history
- [x] usability hints added
- [x] discoverability hints added
- [x] Typeface can be changed
- [x] Colour scheme can be changed
- [x] supports iTerm2 colour themes
- [ ] Bell can be changed
- [x] Default term size can be changed
- [x] Default command / shell can be changed
## Supported Platforms
Support for the following platforms is planned:
- [x] Linux
- [x] tested on Arch
- [ ] tested on Ubuntu
- [ ] tested on Rocky
- [ ] BSD
- [ ] tested on FreeBSD
- [ ] tested on NetBSD
- [ ] tested on OpenBSD
- [ ] tested on DragonflyBSD
- [x] macOS
- [ ] tested on 12.x, Monterey
- [ ] tested on 13.x, Ventura
- [x] tested on 14.x, Sonoma
- [x] tested on 15.x, Sequoia
- [ ] Windows
- [ ] PTY support implemented
- [ ] tested on Windows 10
- [ ] tested on Windows 11
## Install Guide
Currently TTYphoon can only be compiled from source.
To do so you will need the following installed:
- C compiler (eg GNU C)
- Go compiler
- [wails](https://wails.io/) command line tool
- GNU Make (available by default on POSIX systems)
Aside from that, it's as easy as running `make build` from the git repository
root directory.
### VT Debugging
The terminal emulator functions can provide verbose logging for debugging. To
enable this, build with `-tags debug` flag. Please note that this will add a
lot of noise to the stdout of the terminal used to launch TTYphoon.
### AI Tracing
The AI features, prompts sent to LLMs and messages between MCP tools can be
traced for debugging. To enable this, build with `-tags trace`. Trace messages
are sent to the stdout of the terminal used to launch TTYphoon.
## How To Support
Regardless of your time and skill set, there are multiple ways you can support
this project:
- **Contributing code**: This could be bug fixes, new features, or even just
correcting any typos.
- **Testing**: There is a plethora of different software that needs to run
inside a terminal emulator and a multitude of distinct platforms that this
could run on. Any support testing TTYphoon would be greatly appreciated.
- **Documentation**: This is possibly the hardest part of any project to get
right. Eventually documentation for this will follow the same structure as
[Murex Rocks](https://murex.rocks) (albeit its own website) however, for now,
any documentation written in markdown is better than none.
- **Architecture discussions**: I'm always open to discussing code theory. And
if it results in building a better terminal emulator, then that is a
worthwhile discussion to have.
- **Porting escape codes to other applications**: Currently [Murex](https://github.com/lmorg/murex)
is the pioneer for supporting TTYphoon-specific ANSI escape codes. However it
would be good to see some of these extensions expanded out further. Maybe
even to a point where this terminal emulator isn't required any more than a
place to beta test future proposed escape sequences.