Tmux Configuration

Sidequest uses tmux to manage persistent terminal sessions for every quest, supervisor and council. Each agent runs inside a tmux session, which allows sessions to survive app restarts, disconnects, and system sleep.

Why Tmux?

Without tmux, closing the Sidequest window or restarting the app would kill all running sessions. Tmux decouples the process from the terminal:

• Persistence. Agents keep running even if Sidequest is closed. Reopen the app and your sessions are still there.
• Reconnection. Sidequest attaches a PTY (pseudo-terminal) to the tmux session to stream output into the embedded terminal. If the PTY dies, it can reattach without interrupting the agent.
• Isolation. Each quest gets its own tmux session. Killing one does not affect others.

Session Naming

All Sidequest tmux sessions use the prefix sq-:

sq-<quest-uuid>                  # Quest session
sq-supervisor-<supervisor-id>    # Supervisor session
sq-council-<quest-uuid>          # Council review session
sq-profile-login-<profile-id>    # Temporary session for `claude auth login`

You can see them alongside any personal tmux sessions:

tmux list-sessions
# sq-a1b2c3d4-e5f6-... : 1 windows (created ...)
# sq-supervisor-s-platform : 1 windows (created ...)
# my-personal-session   : 3 windows (created ...)

Sidequest only manages sessions with the sq- prefix. Your personal tmux sessions are never touched.

How Sessions Work

When you activate a quest, Sidequest:

1. Creates a detached tmux session: tmux new-session -d -s sq-<quest-id> -c <working-dir>
2. Prepends ~/.sidequest/bin to PATH inside the session so the sidequest and sidequest-journal commands are available to the agent
3. Runs the agent through your login shell (zsh -ilc "claude ...") so PATH includes tools from node, nvm, mise, etc.
4. Attaches a PTY to stream output to the embedded terminal
5. Auto-accepts the agent’s trust/permission dialogs by detecting them and sending the appropriate keypress

The session runs with LANG=en_US.UTF-8 and LC_CTYPE=en_US.UTF-8 to ensure Unicode renders correctly. Without this, apps launched from Finder inherit a minimal locale that makes tmux replace Unicode with underscores.

Tmux Path Resolution

Sidequest auto-discovers your tmux installation by:

1. Querying your login shell (zsh -ilc "whence -p tmux" or equivalent)
2. Falling back to well-known paths if shell resolution fails:
   • /opt/homebrew/bin/tmux (Homebrew on Apple Silicon)
   • /usr/local/bin/tmux (Homebrew on Intel)
   • /usr/bin/tmux (system package manager)

You can override the tmux path in Settings > Tools if auto-discovery does not find the correct binary. Sidequest always resolves to an absolute path, because a bare tmux would fail when the app is launched from Finder.

Configuration

Server settings applied at startup

When Sidequest creates its first session it sets three options on the running tmux server. They are not written to any file, so they last until the server exits:

set-option -s escape-time 0          # no delay after Esc (agents use it to interrupt)
set-option -s focus-events on        # agents learn when the pane gains/loses focus
set-option -g default-terminal tmux-256color

Settings > Tools > Tmux Config Recommendations shows the same snippet with a Copy snippet button. Add it to ~/.tmux.conf to make the settings permanent for your own tmux sessions as well.

Scrollback Buffer

Sidequest caps each session’s scrollback to 1000 lines to prevent memory bloat when many quests run simultaneously:

set-option -t sq-<id> history-limit 1000

The embedded terminal keeps no scrollback of its own; scrolling in the UI scrolls tmux’s buffer.

Mouse Mode

Settings > Tools > Tmux Mode chooses how input is handled:

• Chill mode (default) — tmux mouse mode is on, and Sidequest translates your wheel and clicks into tmux mouse reports while keeping text selection and the right-click menu native. Typing automatically leaves tmux copy mode.
• Mouse mode — native tmux mouse mode; selection follows tmux and the right-click menu is unavailable.
• Raw tmux — mouse mode off; tmux receives raw input for users who want native tmux keybindings.

Changing the mode shows a toast asking you to reload so existing sessions pick it up.

Your Global Config

Sidequest does not read or modify your ~/.tmux.conf. Your global config still applies as the baseline for all sessions; the per-session options above take precedence for Sidequest sessions.

Installation

macOS

brew install tmux

Linux

# Debian/Ubuntu
sudo apt install tmux

# Fedora
sudo dnf install tmux

# Arch
sudo pacman -S tmux

Verify the installation:

tmux -V
# tmux 3.5a

Sidequest requires tmux to be installed. If tmux is not found, sessions cannot be created.

Troubleshooting

”tmux is not installed”

Sidequest could not find tmux on your system. Install it using the commands above, then restart Sidequest. If tmux is installed in a non-standard location, set the path manually in Settings.

Sessions survive after quitting Sidequest

This is by design. When you reopen Sidequest, it reconciles with existing sq- sessions and reattaches automatically. Sessions whose quest or supervisor no longer exists are listed under Settings > Storage > Orphaned Tmux Sessions; or from the shell:

# Kill a specific session
tmux kill-session -t sq-<quest-id>

# Kill all Sidequest sessions
tmux list-sessions -F '#{session_name}' | grep '^sq-' | xargs -I{} tmux kill-session -t {}

Unicode characters showing as underscores

This happens when tmux does not have a UTF-8 locale. Sidequest sets LANG=en_US.UTF-8 when creating sessions, but if your system does not have this locale installed, you may see garbled output. Ensure UTF-8 locales are available:

locale -a | grep UTF-8

Agent binary not found inside tmux

When launched from Finder, the app has a minimal PATH. Sidequest resolves the full path to both tmux and the agent before creating sessions, and runs commands via your login shell to source .zprofile and .zshrc. If the agent still is not found, set its explicit path in Settings > Agent.

Session appears dead but tmux is running

If the Sidequest UI shows a session as disconnected but tmux list-sessions shows it alive, the PTY attachment may have died. Click the quest to reattach. Sidequest will detect the stale PTY, clean it up, and create a fresh attachment.