teru
Health Warn
- License — License: MIT
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Low visibility — Only 7 GitHub stars
Code Pass
- Code scan — Scanned 12 files during light audit, no dangerous patterns found
Permissions Pass
- Permissions — No dangerous permissions requested
No AI report is available for this listing yet.
AI-first terminal emulator, multiplexer, and tiling manager. Written in Zig.
teru
A terminal emulator and a Wayland compositor, written in Zig. No GPU, no FreeType, no fontconfig.
Designed around an MCP control plane so AI agents and shell scripts can drive both as easily as a user can.
teru.sh
· install
· quickstart
· benchmarks
· architecture
· mcp api
Zig 0.17 · Linux · macOS · Windows · MIT · AI integration
What's in the box
| Binary | What it is | Size (stripped release) |
|---|---|---|
teru |
Terminal emulator, multiplexer, tiling manager, session daemon | 1.4 MB |
teruwm |
Wayland compositor (wlroots) built on libteru | 1.2 MB |
teruwmctl |
Shell CLI + MCP stdio adapter for the compositor | 0.37 MB |
One source tree (src/), three artifacts. All share the libteru library: VT parser, grid, SIMD software renderer,
layout engine, 60-tool MCP control plane. A full Wayland compositor in 1.2 MB — no GPU driver, no FreeType, no fontconfig.
Why
Most terminals, multiplexers, and tiling WMs are three programs glued with config files. Every layer
— tmux for panes, alacritty for pixels, sway for windows — speaks its own API, and none of them
let an external process reliably script "open a new pane running X on workspace 3, focus it, read
its output". teru bundles the three concerns into one codebase that exposes every capability over
a JSON-RPC socket, so a Python script or an AI agent can do things you'd otherwise need a
human with a keyboard for.
Concrete differentiators (things no other terminal or compositor has):
- MCP control plane. 22 tools for the terminal, 42 tools for the compositor. Every feature
that has a keybind also has a tool. docs/MCP-API.md. - Push widgets. External daemons register
{widget:name}entries in the bar and push updates
via MCP — event-driven, no polling. docs/AI-INTEGRATION.md. - Hot restart.
$mod+'re-execs a freshly compiled teruwm (re-resolving the on-disk path,
so it actually loads the rebuild); PTY fds survive the exec so your shells don't blink.
docs/ARCHITECTURE.md. - CPU-only SIMD renderer.
@Vector(4, u32)alpha blending. Works over SSH, in VMs, in
containers, on machines with no GPU driver loaded. docs/BENCHMARKS.md. - Process graph. Every pane, every agent, every child process is a node in a DAG the MCP
can query. OSC 9999 lets any process self-declare as an AI agent. - Single statically-linked binary per platform. No Python, no Node, no Electron.
Install
# Arch Linux (AUR) - terminal only; teruwm has no package, build from source below
paru -S teru
# macOS (tap is behind - 0.6.3; build from source for current)
brew install nicholasglazer/teru/teru
# Windows (bucket is behind - 0.11.0)
scoop bucket add teru https://github.com/nicholasglazer/scoop-teru
scoop install teru
# From source (any platform)
git clone https://github.com/nicholasglazer/teru.git && cd teru
zig build -Doptimize=ReleaseFast # → zig-out/bin/teru
zig build -Doptimize=ReleaseFast -Dcompositor # → zig-out/bin/teruwm (Linux only)
Details for every platform: docs/INSTALLING.md.
Quickstart
Running the terminal
teru # windowed, X11/Wayland auto-detected
teru -n work # named persistent session (auto-starts daemon)
teru --raw # over SSH — no windowing, full VT support
teru -e htop # run a specific command instead of the shell
teru --mcp-server # stdio MCP proxy (alias: --mcp-bridge)
Keybinds (Alt is the mod): Alt+Enter new pane, Alt+J/K focus, Alt+1..9 workspace,Alt+Space cycle layout, Alt+X close. Full list: docs/KEYBINDINGS.md.
Running the compositor
teruwm replaces sway/hyprland/river. It's a full Wayland compositor — you launch it from a
TTY, not from inside another session. It ships teru as its native terminal but also runs any
Wayland or XWayland client (Chromium, Emacs, Figma, etc. — all verified).
# From a TTY:
teruwm
# Inside teruwm, Mod defaults to Super (the Windows/Command key):
# Mod+Enter new terminal pane
# Mod+1..9 workspace
# Mod+B toggle top bar
# Mod+Shift+B toggle bottom bar
# Mod+Drag grab a tiled pane with the cursor → it becomes floating
# Mod+Shift+C close focused window
# Mod+Shift+R reload config
# Mod+' hot-restart compositor (PTYs survive, picks up rebuilds)
# Mod+Shift+' quit compositor
Keybinds: docs/KEYBINDINGS.md. Config: docs/CONFIGURATION.md.
Performance
Numbers measured on a Core Ultra 9 185H with ReleaseFast. Full methodology, distribution
(p50/p95/p99), and peer comparisons in docs/BENCHMARKS.md.
| Metric | Value |
|---|---|
teru binary size |
1.4 MB |
teruwm binary size |
1.2 MB |
teru --help startup (p50) |
0.73 ms |
VtParser throughput, dense_cells |
401 MB/s |
Full pipeline (parse + render), dense_cells |
391 MB/s |
Single-number marketing claims are explicitly avoided — see the BENCHMARKS doc for why and
what's not measured.
Docs
Everything user-facing lives in docs/. Concept-by-concept:
- docs/INSTALLING.md — platform-specific build + package manager install
- docs/KEYBINDINGS.md — every default keybind for teru and teruwm, prefix/scroll/vi modes, mouse
- docs/CONFIGURATION.md —
teru.conf,teruwm/config, bar widgets, thresholds, window rules - docs/AI-INTEGRATION.md — MCP protocol, CustomPaneBackend, OSC 9999, push widgets, session templates
- docs/MCP-API.md — 60-tool reference: both servers, every tool's schema and example
- docs/ARCHITECTURE.md — source tree, wlroots integration, scene graph, hot restart
- docs/BENCHMARKS.md — methodology, results, planned follow-ups
- docs/vr-station-mode-guide.md — power the panel off for VR: the headless mirror, why brightness/disable fail, the tool and the toggle
Status
| Area | Status |
|---|---|
| teru terminal, Linux (X11 + Wayland) | production; 570+ inline tests |
| teru terminal, macOS (AppKit) | feature-complete, needs hardware testing; US ANSI keyboard only |
| teru terminal, Windows (Win32 + ConPTY) | early port: window, shell, typing and resize work under Wine; untested on Windows; no sessions, MCP or config file yet |
| teruwm compositor, Linux (wlroots) | usable; XDG + XWayland verified with Chromium / Emacs / Figma |
Session persistence (-n NAME) |
production |
| MCP (61 tools) | production; E2E + audit suites exercise most tools |
| Hot restart | production; shells survive exec |
| Push widgets | production |
| Keypress-to-photon latency numbers | waiting on phototransistor rig — deliberately not published until measured in hardware |
Contributing
git clone https://github.com/nicholasglazer/teru.git && cd teru
zig build test # 584+ inline tests
zig build -Dcompositor # compositor build (Linux)
bash tools/run-bench.sh # regression benchmarks
One concern per commit; inline tests for new behavior; keep the benchmark numbers in
BENCHMARKS.md current if you change the hot path. Areas where help is most
useful: full Unicode (CJK + emoji + font fallback), macOS/Windows hardware testing,
wp_presentation_time export for compositor frame jitter metrics.
License
MIT.
Reviews (0)
Sign in to leave a review.
Leave a reviewNo results found