<p align="center">
<img width="300" src="https://raw.githubusercontent.com/orhun/ratty/refs/heads/main/website/assets/images/ratty-logo.gif" />
<br>
<br>
<b>Ratty: A GPU-rendered terminal emulator with inline 3D graphics</b> 🧀
<br>
<sup>
Inspired by TempleOS | Built with Rust & Ratatui
</sup>
<br>
<img src="https://img.shields.io/badge/Built_with-Ratatui-000?logo=ratatui&amp;logoColor=fff&amp;labelColor=201a16&amp;color=ffd970" alt="Built with Ratatui badge">
</p>

<div>
  <video src="https://github.com/user-attachments/assets/17eda86b-d00f-401b-9cf4-38343fa71386" alt="Ratty Demo"/>
</div>

["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 <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>Enter</kbd>!

<div>
  <video width="80%" src="https://github.com/user-attachments/assets/173971cc-b6bb-4897-857a-5db8e3c9e161"/>
</div>

## Installation

[![Packaging status](https://repology.org/badge/vertical-allrepos/ratty.svg)](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               |
| ----------------------------------------------- | -------------------- |
| <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>C</kbd>     | Copy selection       |
| <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>V</kbd>     | Paste clipboard      |
| <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>Enter</kbd> | Toggle 2D / 3D mode  |
| <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>M</kbd>     | Toggle Mobius mode   |
| <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>Up</kbd>    | Increase warp        |
| <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>Down</kbd>  | Decrease warp        |
| <kbd>Alt</kbd>+<kbd>PageUp</kbd>                | Scroll one page up   |
| <kbd>Alt</kbd>+<kbd>PageDown</kbd>              | Scroll one page down |
| <kbd>Alt</kbd>+<kbd>Up</kbd>                    | Scroll one line up   |
| <kbd>Alt</kbd>+<kbd>Down</kbd>                  | Scroll one line down |
| <kbd>Ctrl</kbd>+<kbd>=</kbd>                    | Increase font size   |
| <kbd>Ctrl</kbd>+<kbd>-</kbd>                    | Decrease font size   |
| <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>0</kbd>     | Reset font size      |

## 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

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:

<div>
  <video width="80%" src="https://github.com/user-attachments/assets/e955d09a-d0eb-4bad-b3b2-fc1331f49646"/>
</div>

#### [Document](widget/examples/document.rs)

TempleOS-inspired document demo with editable text and embedded inline 3D objects:

<div>
  <video width="80%" src="https://github.com/user-attachments/assets/f3a085b0-9e34-4b6f-92fb-90eff9f11776"/>
</div>

#### [Draw](widget/examples/draw.rs)

Split-pane drawing demo with a 2D canvas on the left and a live 3D preview on the right:

<div>
  <video width="80%" src="https://github.com/user-attachments/assets/8b53515b-b887-4d03-a54c-7e7aa7ea128c"/>
</div>

#### [Rubik's cube](widget/examples/rubiks_cube.rs)

Interactive 3D Rubik's cube demo:

<div>
  <video width="80%" src="https://github.com/user-attachments/assets/9c5828d5-890a-45ac-80f6-cbc0b22384e6"/>
</div>

### Apps

Here are some applications explicitly built around Ratty's Graphics Protocol:

#### [Ratscad](https://github.com/qewer33/ratscad)

Terminal CAD:

<div>
  <video width="80%" src="https://github.com/user-attachments/assets/7fe31947-b734-4d19-9fba-ef606cc7b975"/>
</div>

#### [Ratty-runner](https://github.com/ozzyocak/ratty-runner)

Endless runner built for Ratty:

<div>
  <video width="80%" src="https://github.com/user-attachments/assets/bf3b84a9-7f45-4fac-ae91-240c7ce7c70e"/>
</div>

#### [ComChan](https://github.com/Vaishnav-Sabari-Girish/ComChan)

A blazingly fast serial monitor with plotter TUI and 3D telemetry

<div>
  <video width="80%" src="https://github.com/user-attachments/assets/29ba6751-65d7-4103-86b3-705ef47dbbfd"/>
</div>

## Architecture

### Rendering pipeline

The terminal surface currently uses [`ratatui`](https://github.com/ratatui/ratatui) for the UI buffer,
[`parley_ratatui`](https://github.com/gold-silver-copper/parley_ratatui) for text shaping/rendering
and [Bevy](https://bevyengine.org/) for scene presentation.

Current workflow:

1. PTY output is parsed by `vt100` and drawn into a Ratatui buffer on CPU
2. `parley_ratatui` shapes the buffer with Parley and records it as a Vello scene
3. The scene is handed to Bevy's render world through a double-buffered
   exchange (scenes are recycled between frames, never cloned or re-recorded)
4. Vello renders the scene on Bevy's render-world device into a plain
   `Rgba8Unorm` storage texture, with no CPU readback in between
5. That storage texture is copied into an `Rgba8UnormSrgb` present texture
   (sampled through an sRGB view, so Vello's sRGB-encoded output is decoded on
   sample instead of re-encoded), which Bevy presents in the 2D and 3D scenes

The terminal image is fully GPU-resident: the only data crossing from the main
world to the render world each frame is the recorded scene, not pixels.

## 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)

<div>

<video width="80%" src="https://github.com/user-attachments/assets/76446086-0432-4b67-b768-1fe31134a2c1">

</div>

- _"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)

<div>

<video width="80%" src="https://github.com/user-attachments/assets/bdc55f35-64eb-4a14-8bb1-4f8719f14644">

</div>

## License

All code is licensed under <a href="LICENSE">The MIT License</a>.

<sup>
🦀 ノ( º \_ º ノ) - respect crables!
</sup>

## 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)

<sup>
The author does not have a rat under the hat!
</sup>
