byobu/tmux session support for terminal sessions (project → tmux session, task → tmux window), helps allow remote ssh access

[ahundt]

This is a suggestion to enable tmux so sessions can outlive slayzone restarts, allowing updates while keeping all the terminals intact, and would allow users to connect remotely to their terminal sessions.

Motivation

• Remote access & persistence: Many users run SlayZone on remote servers (SSH, cloud dev machines) or need long-lived sessions that survive local windowing. tmux/byobu provides well-understood session persistence and remote attach/detach semantics.
• Familiar workflows: Advanced users already rely on tmux for multi-window workflows, window naming, pane layouts, session sharing, and keybindings. Integrating tmux lets power users use the same tooling with SlayZone.
• Improved observability & manual intervention: tmux windows/panes map naturally to SlayZone concepts: session per project, window per task/terminal. This mapping simplifies inspecting agent output with native tmux tooling, sharing sessions, and running external watchers/debuggers.
• Byobu first-class option: Byobu is a friendly wrapper around tmux (and screen) offering improved keybindings and session management — supporting both increases accessibility.

Reference code for tmux integration in typescript can be found at:

1. https://github.com/slopus/happy/blob/main/packages/happy-cli/src/utils/tmux.ts
2. https://github.com/happier-dev/happier/tree/dev/apps/cli/src/integrations/tmux

Proposal summary

• Add an optional "tmux mode" for PTY / task terminals that is enabled automatically if available and disablable. When enabled (global or per-project):
  • SlayZone spawns terminals inside a tmux session (or byobu) instead of a raw PTY process, or attaches to an existing tmux session.
  • Mapping:
    • SlayZone → tmux session (session name prefix includes project id or slug)
    • Task → tmux window (window name uses task ID/slug)
    • Terminal tabs / multiple agents in a task → tmux panes or windows (configurable)
  • When SlayZone launches an agent/PTY for a task it either:
    • creates a new tmux session (for first task in a project), or
    • creates a new tmux window named for the task inside the session, and runs the configured CLI agent command inside that window (using tmux new-window -n ).
  • Support an optional byobu flag that runs commands with byobu wrapper command (byobu new-window -n ) to provide byobu behaviors.
  • If a tmux session already exists on disk for that project (e.g., remote session the user started), SlayZone can optionally attach rather than create — controlled by a project setting (attach-if-present: true/false).
  • Provide configuration options:
    • Global: enable/disable tmux mode, default backend (native tmux or byobu), tmux binary path, tmux args, default pane layout.
    • Project-level overrides: per-project enable/disable, session naming scheme, whether to auto-create or attach existing session.
    • Task-level flags: whether to create a pane or a new window, whether to use shell login args, whether to pass environment variables into tmux (and how).
  • Resume & conversationId handling:
    • Because many agents use --session-id / --resume when launched, SlayZone should pass the same flags when launching inside tmux windows and preserve provider_config.conversationId on tasks (current behavior).
    • On app restart, if tmux mode was used and the tmux session still exists, SlayZone should be able to:
      • detect windows corresponding to tasks (by name) and rebind its terminal view to attach to the tmux window (if desired), or
      • re-launch a new tmux window that resumes the provider using existing conversation IDs.variables).
  • UX:
    • GitPanel / TerminalPanel: indicate when session is tmux-managed, show session & window names, provide quick actions (attach via terminal, open external terminal showing tmux attach command, detach).
    • Provide a toggle when creating a worktree/task: “Open in tmux session” with more granular options.
  • Testing:
    • E2E tests verifying new-window creation, window naming, attach/detach, provider resume flags, and session cleanup (tmux kill-session) on task deletion.
    • Tests for byobu wrapper command presence and fallback to plain tmux when byobu not available.

Implementation sketch (files & places to change)

• New terminal adapter: packages/domains/terminal/src/main/adapters/tmux-adapter.ts
  • Responsible for building tmux commands and detecting tmux binary
  • Expose validate() function (like other adapters)
• pty-manager updates: packages/domains/terminal/src/main/pty-manager.ts
  • If tmux mode active, spawn tmux as the parent process or use shell commands to create tmux windows that run the agent CLI
  • Provide attach mode: instead of spawning, call tmux capture-pane to show output and use a pty that runs tmux attach (or spawn the user's terminal)
• UI adjustments:
  • Task Git/Terminal panel: show tmux flags, button “Open in external terminal (tmux attach )”
  • Project settings: WorktreesTab or Projects settings add new “Terminal backend” + per-project tmux toggle
• Persistent mapping:
  • Save mapping sessionName -> projectId and windowName -> taskId in tasks table (new columns or in terminal_tabs/ai_config) so reconnection/attach can be implemented on app restart
• Edge cases:
  • Windows support: check byobu/tmux availability on Windows (WSL) and provide fallbacks
  • Clean shutdown: on task close, optionally close tmux window; if sharing session for multi-tasks, only kill window, not full session

[debuglebowski]

I like this, makes a lot of sense. I'll start working on it :)