termemu

termemu is a from-scratch, pure-std Rust terminal emulator. The repo builds both the termemu library crate and the termemu binary, with a single live interactive emulator plus a terminal-drawn, native-macOS-style multi-emulator window wrapper.

The emulator includes VT100-style deferred autowrap. That fixes the stray zsh % line caused by prompt redraws at the right edge, and prevents newline corruption in full-screen TUIs such as Claude Code when they paint full-width rows.

Install

curl -fsSL https://raw.githubusercontent.com/ngthluu/terminal-emulator/main/install.sh | bash

The installer downloads the matching macOS release asset and installs termemu to ${INSTALL_DIR:-$HOME/.local/bin}. Set INSTALL_DIR to choose another directory, or set VERSION to install a specific release version or tag:

curl -fsSL https://raw.githubusercontent.com/ngthluu/terminal-emulator/main/install.sh \
  | INSTALL_DIR=/usr/local/bin VERSION=0.1.0 bash

If you use the default install directory, make sure ~/.local/bin is on your shell PATH:

export PATH="$HOME/.local/bin:$PATH"

Build And Run

Run a single interactive emulator:

cargo run

Run the multi-emulator window wrapper:

cargo run -- --window
cargo run -- --grid

Render a captured ANSI/VT input file in batch mode:

cargo run -- <file>

With no arguments, termemu starts the single interactive emulator when stdin is a TTY; otherwise it renders stdin as batch input. The current binary does not define a separate --help flag.

Wrapper Controls

The wrapper uses Ctrl-G as its command prefix:

• Ctrl-G n: spawn an emulator
• Ctrl-G x: remove the focused emulator
• Ctrl-G h: focus left
• Ctrl-G j: focus down
• Ctrl-G k: focus up
• Ctrl-G l: focus right
• Ctrl-G q: quit the wrapper

The wrapper also enables SGR mouse mode. Click [+ Spawn emulator] to add a session, click a cell [x] to remove that session, or click the red traffic-light dot in the title bar to close and quit. The yellow and green dots are decorative.

Architecture

The core pipeline is:

reader -> parser -> terminal/screen -> renderer

• reader drains input bytes and feeds the parser.
• parser is an ANSI/VT state machine that emits terminal actions.
• terminal and screen maintain the cell grid, cursor state, attributes, scroll regions, alternate screen, and deferred autowrap behavior.
• renderer turns the screen model into ANSI repaint frames for live sessions.

wrapper.rs composites child emulator frames onto a Canvas, drawing rounded window chrome, a macOS-style traffic-light title bar, toolbar controls, and the grid of child sessions.

Tests

Run the Rust test suite:

cargo test

Run the repository verification gate:

.agentloop/verify.sh

The gate builds and tests the crate, checks install.sh syntax when present, and performs lightweight structural checks for GitHub Actions workflow files.

CI/CD

GitHub Actions CI runs on every push and pull request using a macOS runner, and executes cargo build plus cargo test.

Pushing or merging to the release branch starts the release workflow. It derives the version from Cargo.toml, creates the v<version> tag if it does not already exist, builds macOS release binaries for aarch64-apple-darwin and x86_64-apple-darwin, packages them as termemu-<version>-<target>.tar.gz, and publishes or updates the matching GitHub Release.