# 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

```bash
workrex setup
workrex sidebar on
```

Rex program status supplies activity for agents that report it. Other agents use
[status hooks](https://kong109.github.io/workrex/guide/status-tracking/). `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`:

```bash
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:

```bash
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:

```bash
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](https://kong109.github.io/workrex/guide/sidebar/customization/) 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:

```bash
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.

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

Toggle configured views with `V` in the sidebar or:

```bash
workrex sidebar view on
workrex sidebar view off
```

See [the command reference](https://kong109.github.io/workrex/reference/commands/sidebar/#named-views) 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:

```bash
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:

```bash
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](https://kong109.github.io/workrex/guide/dashboard/).