par-term 0.34.0

# Status Bar

par-term provides a configurable status bar with a widget system for displaying session information, system metrics, and custom text.

## Table of Contents
- [Overview](#overview)
- [Enabling the Status Bar](#enabling-the-status-bar)
- [Built-in Widgets](#built-in-widgets)
- [Layout](#layout)
  - [Three-Section Layout](#three-section-layout)
  - [Default Widget Placement](#default-widget-placement)
- [Custom Widgets](#custom-widgets)
  - [Variable Interpolation](#variable-interpolation)
- [Auto-Hide Behavior](#auto-hide-behavior)
- [System Monitoring](#system-monitoring)
- [Git Integration](#git-integration)
- [Styling](#styling)
- [Configuration](#configuration)
- [Settings UI](#settings-ui)
- [Related Documentation](#related-documentation)

## Overview

The status bar displays contextual information at the top or bottom of the terminal window:

```mermaid
graph LR
    Left["Left Section\nUser@Host | Directory | Git Branch"]
    Center["Center Section\nCurrent Command"]
    Right["Right Section\nBell | Clock | Update"]

    Left --- Center --- Right

    class Left active
    class Center data
    class Right external

    classDef active fill:#1b5e20,stroke:#4caf50,stroke-width:2px,color:#ffffff
    classDef data fill:#0d47a1,stroke:#2196f3,stroke-width:2px,color:#ffffff
    classDef external fill:#4a148c,stroke:#9c27b0,stroke-width:2px,color:#ffffff
```

## Enabling the Status Bar

The status bar is disabled by default. Enable it in Settings or config:

```yaml
status_bar_enabled: true
```

**Settings UI:** Settings > Status Bar > General > "Enable Status Bar"

## Built-in Widgets

par-term includes 10 built-in widgets plus custom widgets:

| Widget | YAML ID | Description | Default Section | Default State |
|--------|---------|-------------|-----------------|---------------|
| **Clock** | `clock` | Current time with configurable format | Right | Enabled |
| **User@Hostname** | `username_hostname` | Current user and machine name | Left | Enabled |
| **Current Directory** | `current_directory` | Working directory of active tab | Left | Enabled |
| **Git Branch** | `git_branch` | Branch name with ahead/behind/dirty indicators | Left | Enabled |
| **CPU Usage** | `cpu_usage` | CPU usage percentage with fixed-width formatting (e.g., "CPU 42.5%") | Right | Disabled |
| **Memory Usage** | `memory_usage` | Used/total memory with MEM prefix (e.g., "MEM 4.0 GB / 16.0 GB") | Right | Disabled |
| **Network Status** | `network_status` | Receive/transmit rates with arrows (e.g., "↓ 1.0 KB/s ↑ 2.0 KB/s") | Right | Disabled |
| **Bell Indicator** | `bell_indicator` | Bell emoji with count, shown when count > 0 (e.g., "🔔 3") | Right | Enabled |
| **Update Available** | `update_available` | Yellow up-arrow with available version (e.g., "⬆ v0.20.0") | Right | Enabled |
| **Current Command** | `current_command` | Currently executing shell command | Center | Enabled |
| **Custom Text** | `custom:<name>` | User-defined text with variable interpolation | Configurable | User-created |

### Clock

Displays the current time using a configurable strftime format string.

**Default format:** `%H:%M:%S` (24-hour time with seconds)

**Common format examples:**

| Format | Output |
|--------|--------|
| `%H:%M:%S` | `14:30:45` |
| `%I:%M %p` | `02:30 PM` |
| `%H:%M` | `14:30` |
| `%a %H:%M` | `Mon 14:30` |
| `%Y-%m-%d %H:%M` | `2026-02-13 14:30` |

**Settings UI:** Settings > Status Bar > Widget Options > "Time Format"

### Git Branch

Displays the current git branch name with optional status indicators:

- Branch name with Powerline symbol
- Ahead count (`↑3`) — commits ahead of remote
- Behind count (`↓2`) — commits behind remote
- Dirty indicator (`●`) — uncommitted changes

**Example output:** ` main ↑2 ↓1 ●`

Git status polling runs on a background thread with a configurable interval. Toggle ahead/behind/dirty display with:

```yaml
status_bar_git_show_status: true  # default: true
```

### System Widgets (CPU, Memory, Network)

System monitoring widgets are **disabled by default** to avoid unnecessary resource usage. Enable them individually in the Settings UI.

When any system widget is enabled, a background monitoring thread starts polling at the configured interval.

### UpdateAvailable

Displays a yellow up-arrow icon followed by the available version number when a newer version of par-term is detected.

**Example output:** `⬆ v0.20.0`

The widget auto-hides when no update is available, so it only appears when there is something to act on. Clicking the widget opens the update dialog overlay, which provides options to install the update or dismiss the notification.

## Layout

### Three-Section Layout

The status bar divides into three sections:

- **Left** — Left-aligned widgets, displayed in order
- **Center** — Center-aligned widgets
- **Right** — Right-aligned widgets

Widgets within each section are separated by a configurable separator character (default: ` │ `).

### Default Widget Placement

| Section | Widgets (in order) |
|---------|-------------------|
| **Left** | User@Hostname, Current Directory, Git Branch |
| **Center** | Current Command |
| **Right** | CPU (off), Memory (off), Network (off), Bell, Clock, Update Available |

Widgets can be moved between sections and reordered via the Settings UI.

## Custom Widgets

Create custom widgets with user-defined text and variable interpolation through the Settings UI.

**Creating a Custom Widget:**

1. Open Settings > Status Bar
2. Scroll to the **Widgets** section
3. Click **+ Add Custom Text Widget**
4. Enter a format string using `\(variable)` placeholders
5. Assign to a section (Left, Center, or Right)

> **Persistence:** Custom widgets persist to `config.yaml` under `status_bar_widgets` with the widget id `custom:<name>` (for example `id: custom: Build Stats`). They round-trip through the flattened status-bar config path on the next launch.

### Variable Interpolation

Custom widgets support these variables:

| Variable | Description | Example Output |
|----------|-------------|----------------|
| `\(session.hostname)` | Remote hostname | `prod-server` |
| `\(session.username)` | Current username | `deploy` |
| `\(session.path)` | Working directory | `/home/user/project` |
| `\(session.bell_count)` | Bell event count | `3` |
| `\(session.current_command)` | Currently running command | `make build` |
| `\(session.job)` | Current foreground job name | `vim` |
| `\(session.last_command)` | Last executed command | `cargo test` |
| `\(session.profile_name)` | Active profile name | `Default` |
| `\(session.selection)` | Currently selected terminal text | `selected text` |
| `\(session.tty)` | TTY device name | `/dev/ttys001` |
| `\(session.columns)` | Terminal columns | `120` |
| `\(session.rows)` | Terminal rows | `40` |
| `\(session.exit_code)` | Last command exit code | `0` |
| `\(session.tmux_pane_title)` | tmux pane title (when in tmux) | `my-session` |
| `\(git.branch)` | Git branch name | `main` |
| `\(git.ahead)` | Commits ahead of upstream | `2` |
| `\(git.behind)` | Commits behind upstream | `0` |
| `\(git.dirty)` | Dirty state (bullet if dirty, empty if clean) | `●` |
| `\(system.cpu)` | CPU usage percentage | `42.5%` |
| `\(system.memory)` | Memory usage (used / total) | `4.0 GB / 16.0 GB` |

**Example format strings:**

```
Host: \(session.hostname) CPU: \(system.cpu)
\(git.branch) [\(session.current_command)]
Profile: \(session.profile_name) TTY: \(session.tty)
```

> **Note:** The `format` field on any widget configuration (not only custom widgets) accepts the same `\(variable)` placeholders and overrides the widget's built-in formatting. The Settings UI only exposes this editor for custom widgets; for built-in widgets, set `format:` directly in `config.yaml`.

## Auto-Hide Behavior

The status bar can automatically hide in two scenarios:

**Fullscreen Auto-Hide:**

Hide the status bar when the window enters fullscreen mode.

```yaml
status_bar_auto_hide_fullscreen: true  # default: true
```

**Mouse Inactivity Auto-Hide:**

Hide the status bar after a period of mouse inactivity. Moving the mouse makes it reappear.

```yaml
status_bar_auto_hide_mouse_inactive: false  # default: false
status_bar_mouse_inactive_timeout: 3.0      # seconds, range: 1-30
```

## System Monitoring

When CPU, Memory, or Network widgets are enabled, par-term runs a background monitoring thread.

**Polling Interval:**

```yaml
status_bar_system_poll_interval: 2.0  # seconds, range: 0.5-30.0
```

Lower values provide more responsive updates but use more CPU. The default of 2 seconds provides a good balance.

**Metrics collected:**
- **CPU**: Global usage percentage (0-100%)
- **Memory**: Used and total memory in human-readable units
- **Network**: Receive and transmit rates calculated from deltas between polls

> **📝 Note:** The first CPU and network readings after enabling show 0% as the monitor needs two samples to calculate rates.

## Git Integration

The Git Branch widget polls the active tab's working directory for git status.

**Polling Interval:**

```yaml
status_bar_git_poll_interval: 5.0  # seconds, range: 1.0-60.0
```

**Displayed Information:**
- Branch name (from `git rev-parse --abbrev-ref HEAD`)
- Ahead/behind counts (from `git rev-list`)
- Dirty indicator (from `git status`)

Toggle the extended status display:

```yaml
status_bar_git_show_status: true  # Show ahead/behind/dirty indicators
```

## Styling

Customize the status bar appearance:

```yaml
# Position
status_bar_position: bottom       # top or bottom

# Size
status_bar_height: 22.0           # pixels, range: 16-40

# Colors
status_bar_bg_color: [30, 30, 30]    # RGB background
status_bar_bg_alpha: 0.95            # opacity, 0.0-1.0
status_bar_fg_color: [200, 200, 200] # RGB text color

# Font
status_bar_font: ""               # empty = use terminal font
status_bar_font_size: 12.0        # points, range: 8-24

# Separator between widgets
status_bar_separator: " │ "
```

## Configuration

Complete status bar configuration reference:

```yaml
# General
status_bar_enabled: false
status_bar_position: bottom     # top, bottom
status_bar_height: 22.0         # 16.0-40.0 px

# Styling
status_bar_bg_color: [30, 30, 30]
status_bar_bg_alpha: 0.95
status_bar_fg_color: [200, 200, 200]
status_bar_font: ""
status_bar_font_size: 12.0
status_bar_separator: " │ "

# Auto-hide
status_bar_auto_hide_fullscreen: true
status_bar_auto_hide_mouse_inactive: false
status_bar_mouse_inactive_timeout: 3.0   # 1.0-30.0 sec

# Data
status_bar_time_format: "%H:%M:%S"
status_bar_git_show_status: true
status_bar_system_poll_interval: 2.0     # 0.5-30.0 sec
status_bar_git_poll_interval: 5.0        # 1.0-60.0 sec

# Widgets (array of widget configurations)
# Widget IDs use snake_case format: clock, username_hostname, current_directory,
# git_branch, cpu_usage, memory_usage, network_status, bell_indicator,
# current_command, update_available. Custom widgets use `custom:<name>`.
# Each entry may also carry an optional `format:` override using \(variable)
# placeholders; when set, it replaces the widget's built-in formatting.
status_bar_widgets:
  - id: username_hostname
    enabled: true
    section: left
    order: 0
  - id: current_directory
    enabled: true
    section: left
    order: 1
  - id: git_branch
    enabled: true
    section: left
    order: 2
  - id: current_command
    enabled: true
    section: center
    order: 0
  - id: cpu_usage
    enabled: false
    section: right
    order: 0
  - id: memory_usage
    enabled: false
    section: right
    order: 1
  - id: network_status
    enabled: false
    section: right
    order: 2
  - id: bell_indicator
    enabled: true
    section: right
    order: 3
  - id: clock
    enabled: true
    section: right
    order: 4
  - id: update_available
    enabled: true
    section: right
    order: 5
  # Example: built-in widget with a format override (replaces built-in formatting)
  - id: git_branch
    enabled: true
    section: left
    order: 3
    format: \(git.branch) [\(session.current_command)]
  # Example: custom widget (user-defined text via variable interpolation)
  - id: custom: Build Stats
    enabled: true
    section: right
    order: 6
    format: CPU \(system.cpu) · \(git.branch)
```

## Settings UI

The Status Bar tab in Settings (`F12`) provides six sections:

**General:**
- Enable/disable toggle
- Position dropdown (Top/Bottom)
- Height slider

**Styling:**
- Background color picker and opacity slider
- Text color picker
- Font size slider
- Separator text input

**Auto-Hide:**
- Fullscreen auto-hide toggle
- Mouse inactivity auto-hide toggle with timeout slider

**Widget Options:**
- Time format input with expandable reference table
- Git status display toggle

**Poll Intervals:**
- System monitor interval slider
- Git branch interval slider

**Widgets:**
- Three-column layout showing Left, Center, and Right sections
- Click widgets to toggle enabled/disabled
- Right-click context menu for moving widgets between sections and reordering
- "Add Custom Text Widget" button for creating custom widgets with format strings

## Related Documentation

- [Window Management](WINDOW_MANAGEMENT.md) - Status bar positioning in the window layout
- [Profiles](PROFILES.md) - Session variables used by widgets
- [Keyboard Shortcuts](../guides/KEYBOARD_SHORTCUTS.md) - Complete shortcut reference