Getting started — traa.sh

00 — Download

Pre-built relocatable packages from GitHub Releases. Bundled libraries under lib/, Lua under share/traash/lua.

Linux x86_64 traash-0.2.0-linux-x86_64.tar.gz Download → macOS arm64 traash-0.2.0-macos-arm64.tar.gz Download →

All releases · checksums on the release page · or build from source below

tar xzf traash-0.2.0-*.tar.gz && cd traash-0.2.0-*
./bin/traash

00 — Agents

Agent-compatible from day one

traa.sh is designed for external automation: a JSON API on the mux socket, a headless CLI, and shell integration for reliable wait-for-command.

Typical flow: run traash --server, use traash agent state|send|wait|subscribe, source traash shell-init in your shell. No GUI window required.

traash --server --create dev &
traash agent state dev
eval "$(traash shell-init bash)"   # add to ~/.bashrc for wait/send
traash agent send dev --pane 1 --literal $'make test\n'
traash agent wait dev --pane 1
traash agent subscribe dev

Protocol details, message types, events, and security: Agent API guide. Machine-readable digest: llms.txt.

01 — Build

Build and run

Dependencies: CMake, Ninja, OpenGL, FreeType, HarfBuzz, Lua, Fontconfig, OpenSSL (libssl-dev), and libutil (pty on Linux). GLFW is fetched by CMake.

# Debian/Ubuntu
sudo apt-get install ninja-build pkg-config libfreetype6-dev libharfbuzz-dev \
  liblua5.4-dev libfontconfig1-dev libssl-dev libgl1-mesa-dev \
  libx11-dev libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev \
  libwayland-dev libxkbcommon-dev

# macOS
brew install cmake ninja pkg-config freetype harfbuzz lua fontconfig

cmake -B build -G Ninja
cmake --build build
./build/traash

Makefile wrappers:

make            # configure + build
make run        # ./build/traash
make test       # ctest
make demo       # ./build/traash --demo

Tests

ctest --test-dir build --output-on-failure
./build/traash --headless-test
./build/traash --headless-test --demo --auto

--headless-test initializes core subsystems and exits. It does not open a window. Tagged GitHub releases (v*) ship relocatable Linux and macOS tarballs.

02 — Install

Desktop install

Installs the binary, bundled Lua tree, and (on Linux) the .desktop file and hicolor icons. Default prefix is ~/.local.

make install
# system-wide:
make install PREFIX=/usr/local

X11

RGBA sizes are baked into the binary and applied with glfwSetWindowIcon. After changing assets/icons/traash.png, run make embed-icon.

Wayland / launchers

The desktop file maps Icon=sh.traa.traash. Install so the compositor can find hicolor icons.

03 — CLI

Command-line flags

Flag	Meaning
`traash`	Open the GUI and attach (or create) the default session
`--demo [--auto]`	Capability demo; `--auto` advances without waiting
`--server [--bind ADDR:PORT]`	Run the mux server headless (Unix socket + optional TCP)
`--list-sessions`	List sessions on the mux socket (encrypted sessions show a `*` suffix)
`--create NAME [--encrypt]`	Create a session; `--encrypt` prompts for write + read-only passwords
`--attach NAME`	Attach a session (client if a server is running, else local host)
`--read-only`	Force read-only attach (observer mode)
`--host HOST` / `--port PORT`	Attach over TCP (default port `9477`)
`--password-fd FD`	Read attach password from an open file descriptor (never pass passwords on argv)
`traash agent state SESSION`	Export pane text, cwd, cursor, busy flag as JSON (headless)
`traash agent send SESSION --pane N --literal BYTES`	Write bytes to a pane PTY
`traash agent wait SESSION --pane N [--timeout MS]`	Block until shell reports command finished (OSC 133;D)
`traash agent subscribe SESSION [--emit-output]`	Stream JSONL events until Ctrl-C
`traash shell-init bash\|zsh\|fish`	Print shell snippet for OSC 133 + OSC 7 integration
`--headless-test`	Init core and exit (CI)
`-h` / `--help`	Print usage

The mux socket lives under $XDG_RUNTIME_DIR/traash/mux.sock (or ~/.traash/mux.sock if that env is unset).

04 — Config

Where files live

Path	Role
`lua/defaults/config.lua`	Shipped defaults
`~/.config/traash/config.lua`	User overlay; Settings writes this file
`~/.config/traash/themes/`	User themes (override bundled ids)
`~/.config/traash/layouts/`	User layouts (override bundled ids)
`~/.local/share/traash/sessions/`	Encrypted session snapshots (`<name>.tsn`, mode 0600)
`lua/themes/`, `lua/status/`, `lua/layouts/`	Bundled assets
`lua/plugins/examples/<id>/init.lua`	Only plugin location the host loads

Lua root: set TRAASH_LUA_PATH to point at a Lua tree (the directory that contains defaults/, themes/, plugins/). Otherwise traa.sh looks next to the binary, then the source tree.

-- ~/.config/traash/config.lua
config = {
  theme = "tokyo-night",
  status_bar = "pills",
  default_layout = "",
  font = "Hack Nerd Font Mono",
  font_size = 14,
  opacity = 1.0,
  cursor_style = 1,
  scrollback = 5000,
  plugins = {
    "git-status", "cwd-short", "battery",
    "ssh-hint", "notify-on-bell",
  },
}
return config

See the config schema for every field. Reload with Ctrl-Shift-R (action reload_config). That reloads theme, font-related fields, and keys from disk; it does not reload plugins — restart the app after plugin list or plugin-code changes.

05 — Sessions

Mux sessions

traa.sh is a terminal and a tmux-style multiplexer. A host process runs live PTYs; extra clients attach over the mux socket (local Unix or optional TCP).

A session holds numbered windows (tabs) of panes.
traash --server runs a headless host. Without it, the GUI process is the host and also listens on the Unix socket.
If a mux server is already running, traash --attach NAME opens a GUI client that mirrors the host session.
Prefix Ctrl-b then d detaches the GUI client; the host session keeps running.
default_layout is skipped on attach so you do not wipe the live layout.
Closing the last shell (for example Ctrl-D in the last pane) exits the window, same as other terminals.

Encrypted sessions

Create a password-protected session with two secrets: a write password (view + type) and a read-only password (view only). Snapshots are stored encrypted on disk; whichever password you enter determines your role.

# Create encrypted session (prompts for both passwords)
traash --create myvault --encrypt

# Run a persistent host (optional TCP for remote clients)
traash --server --bind 127.0.0.1:9477

# Attach locally (prompts for password)
traash --attach myvault

# Attach as observer, or over TCP
traash --attach myvault --read-only
traash --attach myvault --host 127.0.0.1 --port 9477

Security (v1): Passwords are never accepted on the command line — use the tty prompt or --password-fd. Encrypted files live at $XDG_DATA_HOME/traash/sessions/<name>.tsn (or ~/.local/share/traash/sessions/). Crypto: AES-256-GCM payload + PBKDF2-HMAC-SHA256 per-password key wraps. TCP attach has no TLS — the password is sent in the AUTH frame; use Unix socket or a trusted LAN. Shell processes are not restored after a host restart; layout, screen, and scrollback are.

Read-only clients see a READ-ONLY badge in the status bar. The server rejects keyboard input, paste, and mutating mux actions (splits, new windows, layout apply) for read-only attaches. Copy, scroll, search, and local UI overlays still work.

Startup layouts

If default_layout is a known layout id (single, h-split, v-split, dev, or a user layout), it is applied on a fresh session. Apply recreates tabs and panes with fresh shells — geometry only, not cwd/title/scrollback. Open the picker anytime with Ctrl-Shift-L.

Next: full agent API reference, keyboard, overlays, and mouse, then the plugin guide.

v0.2.0

Agent-compatible from day one

Build and run

Tests

Desktop install

X11

Wayland / launchers

Command-line flags

Where files live

Mux sessions

Encrypted sessions

Startup layouts