Sidebar

The sidebar is a Rex terminal block placed beside or above each window’s content in scope. It shows agent status, task identity, Git changes, and pull-request checks while you work in another block.

Enable the sidebar

workrex setup
workrex sidebar on

Rex program status supplies activity for agents that report it. Other agents use status hooks. workrex sidebar off removes the sidebar blocks; workrex sidebar toggles them.

Session scope

By default, sidebars appear in windows across the selected Rex server. Scope the operation to the caller’s session with --session:

workrex sidebar --session on
workrex sidebar --session off

Workrex uses the caller’s Rex session and block identity. A background agent’s session may differ from the session the user is viewing.

Position and size

The sidebar opens on the left. Set sidebar.width in configuration or pass a width when enabling it:

workrex sidebar on --width 30

Without a configured width, dragging a sidebar border saves the width for the other sidebars on that Rex server. An explicit command-line width remains in effect until the sidebar is turned off.

For a full-width bar above the content, use Rex’s vertical split layout:

workrex sidebar on --position top --height 3

Set sidebar.position: top and sidebar.height: "10%" to configure a relative height. Dragged heights are stored separately from left-sidebar widths. Switching positions preserves the content blocks and focus.

Layout

Use the tile layout for task details or the compact layout for more rows. The sidebar’s controls and templates determine what each row displays. Preferences are stored under ~/.local/state/workrex/sidebar/, separately for each Rex server.

Sorting

Sort by recent activity, project, or window order using the sidebar controls. Sorting changes display order; Workrex continues addressing agents by their recorded Rex block IDs.

Grouping

Group agents by project or Rex session:

workrex sidebar group project
workrex sidebar group session
workrex sidebar group --clear

The grouping preference is shared by sidebars on that server. Expanded groups are also shared, so the same group does not unexpectedly reopen in each tab.

Named views

Configure sidebar.views to give sidebars a named scope. A view can match session labels or project paths. sessions matches exact, case-sensitive Rex session labels; a repository directory does not imply a session label.

sidebar:
  views:
    - name: api
      sessions: [api-work]

Toggle configured views with V in the sidebar or:

workrex sidebar view on
workrex sidebar view off

See the command reference for view selection rules.

Mouse and keyboard

Click an agent row to show its session and focus its block. The sidebar handles its own terminal mouse events. Use the displayed key hints for filtering, grouping, sorting, and layout changes.

You can also navigate from a shell or Rex action:

workrex sidebar next
workrex sidebar prev
workrex sidebar jump 3

A cross-tab jump requires Remote Control in Rex Settings. When the app refuses a jump, the sidebar keeps focus and shows the reason. It never sends the keyboard to a block the app has not shown.

Filtering

Press f to restrict the sidebar to the current Rex session, or use:

workrex sidebar filter session
workrex sidebar filter all

Filters affect which rows are visible. Agents and their sessions keep running.

How it works

A daemon follows Rex events and observes agent state. Each eligible window gets its own sidebar block. The daemon adds sidebars to newly created windows without moving focus, and maintains the chosen width across layouts.

Closing one sidebar block leaves that window without a sidebar until the next workrex sidebar on. If the daemon exits, a later sidebar command or sidebar start launches it again. A busy or slow server is retried; an unavailable server is not treated as an empty list of agent terminals.

For the floating alternative, use the dashboard.