Ratty: A GPU-rendered terminal emulator with inline 3D graphics 🧀
Inspired by TempleOS | Built with Rust & Ratatui
["Rodent-obsessed developer creates Ratty to bring 3D graphics to the command line"](https://www.theregister.com/software/2026/05/11/ratty-terminal-emulator-brings-3d-graphics-to-the-command-line/5238299) - The Register
["This New Terminal is Absurd (But Totally Fun)"](https://itsfoss.com/ratty-terminal/) - It's FOSS
["10 weird OSS projects you need right now... "](https://www.youtube.com/watch?v=qPuzWFvRajk) - Fireship
["Your terminal can render in 3D now, and Rust made it surprisingly usable"](https://www.makeuseof.com/terminal-render-3d-rust-made-surprisingly-usable/) - MakeUseOf
## Features
- Spinning rat cursor ([customizable](#changing-the-cursor))
- Traditional 2D and [new 3D mode](#3d-mode)!
- [Inline 3D objects](#inline-3d-objects)
- [GPU-backed text rendering](#rendering-pipeline)
- Image support (via Kitty Graphics Protocol >:\()
▶️ [Watch the demo video here!](https://youtu.be/cY9AX5j-osY)
📚 [Read the behind the scenes blog post here!](https://blog.orhun.dev/introducing-ratty)
### 3D mode
Ever wondered what's _behind_ the terminal? Press Ctrl+Alt+Enter!
## Installation
[](https://repology.org/project/ratty/versions)
Requirements:
- A GPU / graphics stack supported by Bevy and wgpu
- Melted cheese (optional but recommended)
### [crates.io](https://crates.io/crates/ratty)
```bash
cargo install ratty
```
### [Arch Linux](https://archlinux.org/packages/extra/x86_64/ratty/)
```bash
sudo pacman -S ratty
```
### [Nix](nix/README.md)
See the [Nix packaging docs](nix/README.md) for flake, NixOS, and Home Manager usage.
```bash
nix run github:orhun/ratty
```
### Binary releases
Prebuilt binaries are available on the [GitHub releases page](https://github.com/orhun/ratty/releases) for direct download.
### From Git
Requirements:
- Rust toolchain with Cargo
- on Bazzite / Bluefin: `sudo rpm-ostree install gcc fontconfig-devel wayland-devel` (then reboot)
- on Debian / Ubuntu: `sudo apt-get update ; sudo apt-get install gcc pkgconf libfontconfig-dev libwayland-dev`
- on Fedora: `sudo dnf install gcc fontconfig-devel wayland-devel`
```bash
cargo install --git https://github.com/orhun/ratty
```
## Configuration
The default configuration file is available in [`config/ratty.toml`](config/ratty.toml).
You can copy this file to `$HOME/.config/ratty/ratty.toml` and customize it.
### Changing the cursor
```toml
[cursor.model]
path = "CairoSpinyMouse.obj"
scale_factor = 6.0
brightness = 0.5
x_offset = 0.5
plane_offset = 18.0
visible = true
[cursor.animation]
spin_speed = 1.4
bob_speed = 2.2
bob_amplitude = 0.08
```
For [`cursor.model.path`](config/ratty.toml), Ratty supports both `.obj`, `.glb`, and `.stl` assets.
Other useful cursor fields are:
- `scale_factor`: scales the model relative to the terminal cell size
- `brightness`: adjusts the cursor material brightness
- `x_offset`: shifts the cursor model horizontally inside the cell
- `plane_offset`: pushes the cursor away from the warped terminal surface in 3D mode
- `visible`: show the custom 3D cursor model instead of only the terminal cursor
## Key Bindings
| Key | Action |
| -------------------------------------------------------------- | -------------------- |
| Ctrl+Shift+C | Copy selection |
| Ctrl+Shift+V | Paste clipboard |
| Ctrl+Alt+Enter | Toggle 2D / ortho 3D |
| Ctrl+Alt+P | Toggle perspective |
| Ctrl+Alt+M | Toggle Mobius mode |
| Ctrl+Alt+Shift+0-9 | Activate camera slot |
| Ctrl+Alt+Up | Increase warp |
| Ctrl+Alt+Down | Decrease warp |
| Alt+PageUp | Scroll one page up |
| Alt+PageDown | Scroll one page down |
| Alt+Up | Scroll one line up |
| Alt+Down | Scroll one line down |
| Ctrl+= | Increase font size |
| Ctrl+- | Decrease font size |
| Ctrl+Alt+0 | Reset font size |
In custom configs, `ToggleOrtho3DMode` is the current action name for the
orthographic 3D toggle. The old `Toggle3DMode` action remains supported as a
backward-compatible alias.
Camera slot actions are named `ActivateCameraSlot0` through
`ActivateCameraSlot9`. The extra Shift modifier keeps slot 0 distinct
from the existing Ctrl+Alt+0 font reset.
## Inline 3D objects
Ratty uses its own protocol, the [Ratty Graphics Protocol](protocols/graphics.md),
to place inline 3D objects in terminal space.
RGP supports:
- registering `.obj`, `.glb`, and `.stl` assets by path
- placing them at terminal cell anchors
- animation, scale, color, depth and other attributes
- camera control for flat, orthographic, perspective and Mobius views
There is a Ratatui widget called `ratatui-rgp` available in
[`widget/`](widget/) if you want to build your own terminal applications that involve inline 3D objects.
### Examples
#### [Big rat](widget/examples/big_rat.rs)
Places a single oversized rat directly in your terminal. Press `v` in the demo
to cycle the Ratty camera protocol through flat, orthographic, perspective and
Mobius views.
#### [Document](widget/examples/document.rs)
TempleOS-inspired document demo with editable text and embedded inline 3D objects:
#### [Draw](widget/examples/draw.rs)
Split-pane drawing demo with a 2D canvas on the left and a live 3D preview on the right:
#### [Rubik's cube](widget/examples/rubiks_cube.rs)
Interactive 3D Rubik's cube demo:
#### [Mobius Chess](widget/examples/mobius_chess.rs)
A Mobius-strip chess demo:
### Apps
Here are some applications explicitly built around Ratty's Graphics Protocol:
#### [Ratscad](https://github.com/qewer33/ratscad)
Terminal CAD:
#### [Ratty-runner](https://github.com/ozzyocak/ratty-runner)
Endless runner built for Ratty:
#### [ComChan](https://github.com/Vaishnav-Sabari-Girish/ComChan)
A blazingly fast serial monitor with plotter TUI and 3D telemetry
## Agent Control
Ratty includes an optional MCP server for controlling a running terminal from a compatible MCP
client.
e.g. for Codex, register it with the following commands:
```bash
codex mcp add ratty -- /usr/bin/ratty-mcp
```
Enable it in `ratty.toml` as follows (or launch `ratty-mcp`):
```toml
[mcp]
enabled = true
```
The diagram of the control flow is as follows:
```text
MCP client (e.g. Codex)
| starts ratty-mcp (MCP over stdin/stdout)
v
ratty-mcp
| authenticated local control socket
v
Ratty GUI
|
v
Running terminal
```
Here are the available capabilities:
- `terminal_state`: inspect connection, grid, activity, camera and warp state
- `observe`: read visible terminal content, styles, cursor and input modes
- `type_text` / `press`: send text and mode-aware key presses
- `set_terminal` / `set_window`: change grid, font, window size, position, title and background
- `set_view` — change camera mode, pose and warp
- `set_cursor`: configure the rat cursor's visibility and motion
- `set_shape`: choose a built-in surface or define a custom lattice or mesh
Try these example prompts:
```text
Use the Ratty terminal MCP to turn my terminal into a cyberpunk data storm. Use a static custom 4×4 lattice with alternating peaks and valleys, reaching about 350 units deep near the edges while keeping the center nearly flat. Set a near-black background, use perspective view, and adjust the camera until the center text remains readable while the edges look dramatically warped.
```
```text
Use the Ratty terminal MCP to run a read-only project audit. Report the current Git branch and status; use GNU `find` and `wc` to count Rust source files, `grep` to find TODO/FIXME markers, and `du`, `sort`, and `head` to list the 10 largest paths, excluding `.git` and `target`. Then run `cargo fmt --check`, `cargo clippy --workspace`, and `cargo test --workspace` one at a time, waiting for each to finish. Summarize the results and relevant errors without changing files.
```
## Architecture
### Rendering pipeline
The terminal surface currently uses [`ratatui`](https://github.com/ratatui/ratatui) for the UI buffer,
[`bevy_terminal_ratatui`](https://github.com/gold-silver-copper/bevy_terminal) for text shaping/rendering
and [Bevy](https://bevyengine.org/) for scene presentation.
Current workflow:
1. PTY output is parsed by [`fux-vt`](https://github.com/gold-silver-copper/fux/tree/main/fux-vt), a bounded terminal engine shared with the [fux](https://github.com/gold-silver-copper/fux) multiplexer, and drawn into a Ratatui buffer on CPU
2. `bevy_terminal_ratatui` translates Ratatui's changed cells into a retained terminal surface
3. `bevy_terminal` shapes text with Bevy's font system and incrementally builds compact background,
decoration, cursor, and glyph quads
4. Bevy's render world draws those quads into a renderer-owned `Rgba8UnormSrgb` texture
5. Ratty presents that stable texture handle in its flat, plane, perspective, and Mobius scenes
The terminal image is fully GPU-resident: the only data crossing from the main
world to the render world each frame is compact scene data, not pixels.
## Touchscreen
In 3D mode, drag with one finger to rotate the terminal. Move two fingers together to pan, and
pinch them to zoom. Swipe diagonally from the bottom-left toward the top-right to enter Mobius mode.
## Endorsements
- _"This is like a legitimately cool project but also I just spent like 20 minutes adjusting the config for the rat spinning to see him spin faster and more erratically and it cracked me up"_ - [@vimlena.com](https://bsky.app/profile/vimlena.com/post/3mkoshbzpvs2y)
- _"These kinds of experiments are where creativity is born."_ - [@Coko7](https://github.com/Coko7)
- _"No comments. Just support."_ - [@Raphamorim](https://github.com/raphamorim/) (creator of Rio terminal)
- _"[tetro-tui](https://github.com/Strophox/tetro-tui) running in Ratty"_ - [@Strophox](https://github.com/Strophox)
## License
All code is licensed under The MIT License.
🦀 ノ( º \_ º ノ) - respect crables!
## Credits
Ratty logo designed by [@Strophox](https://github.com/Strophox) & [@Harunocaksiz](https://github.com/harunocaksiz)
## Copyright
Copyright © 2026, [Orhun Parmaksız](mailto:orhunparmaksiz@gmail.com)
The author does not have a rat under the hat!