Session mode

Workrex creates one Rex session per worktree by default. A Rex session is a workspace with its own tabs and terminal block layout. Use window mode when a task should occupy a tab inside an existing session instead.

Enabling session mode

Session mode is the default. You can make the choice explicit in .workrex.yaml or ~/.config/workrex/config.yaml:

mode: session

To choose a mode for one command:

workrex add feature-branch --mode session
workrex open feature-branch --mode window

--session is shorthand for --mode session. Workrex stores the mode per worktree so later open, close, remove, and merge operations address the same kind of target. Existing worktrees keep their recorded mode.

How it works

add creates the Rex session and starts its configured terminal blocks. It leaves Rex.app showing the caller’s tab, because an agent may launch the command in the background. Open the new task from the dashboard or sidebar to show it in the app. Jumps across tabs require Remote Control in Rex Settings.

Workrex records session IDs, so renaming a session in Rex does not lose the worktree association. A session label, a session ID, a Git branch, and a worktree handle are different identifiers.

Returning to a default session

When close, remove, or merge closes the session Rex.app is showing, Workrex prefers the destination branch’s managed session when one is available. It then tries default_session, followed by the session the worktree was added from. An app showing another session stays where it is.

default_session: main

This value is an exact Rex session label. Workrex does not prepend window_prefix. Without a matching destination, Rex chooses its first session. See Rex session mode for navigation details.

Multiple windows per session

Use windows to create several tabs inside each task’s session. Each tab has its own block layout. This is mutually exclusive with top-level panes.

mode: session
windows:
  - name: editor
    panes:
      - command: <agent>
        focus: true
      - split: horizontal
        size: 20
  - name: tests
    panes:
      - command: just test --watch

name labels the Rex window, which Rex.app displays as a tab. Its panes use the same layout syntax as top-level panes. The last focus: true block in the configuration determines the session’s active block and window.

Window mode

For a tab in a known Rex session, set mode: window or pass it explicitly:

workrex add feature-branch --mode window --parent-session project-work

Inspect the desired session before choosing its label. Repository paths do not identify sessions. Native Rex commands target full session, window, and block IDs; see Rex concepts.

Limitations

Session mode creates one session per worktree. open --new needs window mode, where duplicate views use distinct managed window labels.