Download
# quick start after download
tar xzf traash-0.2.0-*.tar.gz
cd traash-0.2.0-*
./bin/traash --server --create dev
./bin/traash agent state dev
For automation
Built for agents
External scripts and AI agents attach to a running mux host — no GUI, no ANSI parsing. State is JSON; idle detection uses shell OSC 133; cwd and title come from OSC 7/0.
traash --server --create dev →
traash agent state dev →
eval "$(traash shell-init bash)" in your shell rc →
traash agent send + traash agent wait.
Read-only attach can query and subscribe but cannot send input.
traash --server --create dev & traash agent state dev traash agent send dev --pane 1 --literal $'make\n' traash agent wait dev --pane 1 --timeout 30000 traash agent subscribe dev --emit-output
Map
Guides
01 — Config
User configuration
Defaults load from lua/defaults/config.lua, then merge with
~/.config/traash/config.lua. Settings writes the same file.
config.lua →
optional leader / keys applied onto keymap defaults
(new actions keep shipping binds if an old save omits them).
-- ~/.config/traash/config.lua config = { theme = "tokyo-night", status_bar = "pills", default_layout = "", -- e.g. "dev"; empty = single pane font = "Hack Nerd Font Mono", font_size = 14, opacity = 1.0, cursor_style = 1, -- 0 block, 1 beam, 2 underline scrollback = 5000, plugins = { "git-status", "cwd-short", "battery", "ssh-hint", "notify-on-bell", }, leader = { key = 66, mods = 1 }, keys = { { action = "split_v", key = 53, mods = 2, prefix = 1 }, }, } return config
| Field | Type | Notes |
|---|---|---|
theme | string | Theme id without path |
status_bar | string | pills, tmux, minimal, powerline, dev, compact, centered |
default_layout | string | Applied on startup unless attaching to an existing session |
font | string | Fontconfig family; Settings lists monospace faces |
font_size | number | 8–48 px before content-scale |
opacity | number | 0.3–1.0 |
cursor_style | int | 0 block · 1 beam · 2 underline |
scrollback | int | History lines |
plugins | string[] | Max 16 ids under plugins/examples/<id>/ |
leader | table | { key, mods } — ctrl=1 shift=2 alt=4 super=8 |
keys | table[] | { action, key, mods, prefix } |
Action names
status_cycle and demo have no default chord (command palette). copy_mode is reserved (prefix [) and currently has no runtime handler.
02 — Layouts
Saved session layouts
Lookup: ~/.config/traash/layouts/<name>.lua then
lua/layouts/<name>.lua (user names override bundled).
Ctrl-Shift-L (action layout_picker).
Enter applies · s saves · Del deletes a user layout · Esc closes.
Apply recreates tabs/panes with fresh shells — geometry only.
default_layout is skipped when using --attach.
layout = {
name = "dev",
windows = {
{
name = "1",
active = 1,
panes = {
{ x = 0, y = 0, w = 1, h = 0.5 },
{ x = 0, y = 0.5, w = 1, h = 0.5 },
},
},
},
}
return layout
03 — Themes
Color themes
Lookup: ~/.config/traash/themes/<name>.lua then
lua/themes/<name>.lua.
Required shape
Hex #RRGGBB. Missing keys fall back. ansi[0..15] is the 16-color palette plus chrome keys (tab/pane/status).
Live reload
Enable autoreload-theme, or call traash.reload_theme() from a plugin.
04 — Status bars
Status bar styles
pills, minimal, powerline, dev, and tmux read plugin chips from ctx.seg.*. compact and centered ignore plugin segments.
| ctx field | Meaning |
|---|---|
session | Attached mux session name |
window | Active window id |
title | Active pane title (OSC 0/2) |
cwd | OSC-7 cwd when set |
host | Hostname |
time | HH:MM local |
seg.* | Plugin segment strings |
06 — Encrypted sessions
Dual-password access
Optional encrypted sessions store layout + terminal screen on disk at
~/.local/share/traash/sessions/<name>.tsn.
Two passwords control access: write (read + type) and
read-only (view only).
traash --server [--bind ADDR:PORT] runs a
persistent mux host. GUI --attach becomes a client when the Unix socket is
already up. See getting started → encrypted sessions.
| Flag | Role |
|---|---|
--create NAME --encrypt | Create encrypted snapshot; prompt for both passwords |
--attach NAME | Unlock with either password; role follows the password |
--read-only | Force observer mode even if you know the write password |
--host / --port | Attach over TCP (no TLS in v1) |
--password-fd FD | Password from fd instead of tty (never argv) |
Read-only clients show a status-bar badge. The server blocks PTY input and mutating mux actions for them. Copy, scroll, and local overlays still work.
07 — Lua plugins
Plugin API for coding agents
For terminal automation, use the Agent API and llms.txt. For Lua customization, see the plugin guide — do not invent host APIs.
run_action.
Desktop notifications are transient (3.5s) and replace the previous traa.sh notification.
on_bell fires only while the window is unfocused.
Do
Ship files under lua/ or ~/.config/traash/. Keep segment work cheap (~2 Hz). Restart after plugin code changes.
Do not
Assume a user plugin directory, plugin hot-reload, sandboxing, or that reload_config reloads plugins.