orhun/ratty

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" - The Register
"This New Terminal is Absurd (But Totally Fun)" - It's FOSS
"10 weird OSS projects you need right now... " - Fireship
"Your terminal can render in 3D now, and Rust made it surprisingly usable" - MakeUseOf

Features

• Spinning rat cursor (customizable)
• Traditional 2D and new 3D mode!
• Inline 3D objects
• GPU-backed text rendering
• Image support (via Kitty Graphics Protocol >:()

▶️ Watch the demo video here!
📚 Read the behind the scenes blog post here!

3D mode

Ever wondered what's behind the terminal? Press Ctrl+Alt+Enter!

Installation

Requirements:

• A GPU / graphics stack supported by Bevy and wgpu
• Melted cheese (optional but recommended)

crates.io

cargo install ratty

Arch Linux

sudo pacman -S ratty

Nix

See the Nix packaging docs for flake, NixOS, and Home Manager usage.

nix run github:orhun/ratty

Binary releases

Prebuilt binaries are available on the GitHub releases page 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

cargo install --git https://github.com/orhun/ratty

Configuration

The default configuration file is available in config/ratty.toml.

You can copy this file to $HOME/.config/ratty/ratty.toml and customize it.

Changing the cursor

[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, 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

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, 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/ if you want to build your own terminal applications that involve inline 3D objects.

Examples

Big rat

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

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

Draw

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

Rubik's cube

Interactive 3D Rubik's cube demo:

Mobius Chess

A Mobius-strip chess demo:

Apps

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

Ratscad

Terminal CAD:

Ratty-runner

Endless runner built for Ratty:

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:

codex mcp add ratty -- /usr/bin/ratty-mcp

Enable it in ratty.toml as follows (or launch ratty-mcp):

[mcp]
enabled = true

The diagram of the control flow is as follows:

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:

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.

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 for the UI buffer, bevy_terminal_ratatui for text shaping/rendering and Bevy for scene presentation.

Current workflow:

1. PTY output is parsed by fux-vt, a bounded terminal engine shared with the 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

• "These kinds of experiments are where creativity is born." - @Coko7

• "No comments. Just support." - @Raphamorim (creator of Rio terminal)

• "tetro-tui running in Ratty" - @Strophox

License

All code is licensed under The MIT License.

Credits

Ratty logo designed by @Strophox & @Harunocaksiz

Copyright

Copyright © 2026, Orhun Parmaksız