Agent-compatible GPU terminal

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
traash agent send dev --pane 1 --literal $'make\n'
traash agent wait dev --pane 1 --timeout 30000
traash agent subscribe dev --emit-output

Full agent API reference

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/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,
  text_rendering = "natural", -- natural | legacy | linear
  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

Action names

status_cycle and demo have no default chord (command palette). copy_mode is reserved (prefix [) and currently has no runtime handler.

Rendering

Accurate colors, text you can tune

The renderer supports the full 256-color palette and RGB colors. Default foreground and background colors follow your theme, while explicit ANSI colors keep their own palette entries.

Open Preferences → Appearance → Font → Text rendering with Ctrl-Shift-, to compare modes. Apply updates the running terminal; Save also writes your choice to config.lua.

Text weight varies with your font, theme, and display. Terminal glyphs and Preferences fonts are rasterized at the framebuffer’s scale. Fractional font sizes are retained when saved, and long tab titles are shortened to fit.

Tabs, menus, Preferences, selections, and search highlights use the active theme. Both dark and light themes can customize these colors in a theme file.

02 — Layouts

Saved session layouts

Lookup: ~/.config/traash/layouts/<name>.lua then lua/layouts/<name>.lua (user names override bundled).

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.

foreground and background set the terminal defaults. selection_fg and selection_bg control selected text. Existing tab, pane, and status colors also style the surrounding interface.

04 — Status bars

Status bar styles

pills, minimal, powerline, dev, and tmux read plugin chips from ctx.seg.*. compact and centered ignore plugin segments.

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).

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.