par-term renders thin overlay progress bars at the top or bottom of the terminal window, driven by standard escape sequences from running processes.
Progress bars provide visual feedback for long-running operations directly in the terminal window. They render as thin overlays that do not interfere with terminal content.
graph TD
Shell[Shell/Application]
OSC[OSC Escape Sequences]
Core[Core Library Parser]
Render[egui Progress Renderer]
Shader[Shader Uniforms]
Shell -->|OSC 9;4 / OSC 934| OSC
OSC --> Core
Core --> Render
Core --> Shader
Render --> Bar[Progress Bar Overlay]
Shader --> Effects[Shader Effects]
class Shell neutral
class OSC data
class Core primary
class Render active
class Shader external
class Bar,Effects primary
classDef primary fill:#e65100,stroke:#ff9800,stroke-width:3px,color:#ffffff
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
classDef neutral fill:#37474f,stroke:#78909c,stroke-width:2px,color:#ffffff
The standard protocol for simple progress bars. Supported states:
| State | Code | Description | Visual |
|---|---|---|---|
| Hidden | 0 |
Remove progress bar | Bar disappears |
| Normal | 1 |
Standard progress | Blue bar |
| Error | 2 |
Error occurred | Red bar |
| Indeterminate | 3 |
Unknown progress | Gray bar with an animated scrolling brightness wave |
| Warning | 4 |
Warning state | Yellow bar |
Sequence format:
ESC ] 9 ; 4 ; state ; percent ST
Examples:
# Show 50% progress
printf "\033]9;4;1;50\007"
# Show error state at 75%
printf "\033]9;4;2;75\007"
# Show indeterminate (animated)
printf "\033]9;4;3;0\007"
# Hide progress bar
printf "\033]9;4;0;0\007"Extended protocol for multiple concurrent named progress bars. Each bar is identified by a unique name and managed independently.
Sequence format:
ESC ] 934 ; action ; id [ ; key=value ... ] ST
Actions:
set— Create or update a named progress barremove— Remove a specific named barremove_all— Remove all named bars
Parameters (key=value):
state— Progress state:normal,error,indeterminate,warning,hiddenpercent— Progress percentage (0-100)label— Optional text label, drawn only inbarwithtextstyle and only whenprogress_bar_heightis at least 10 pixels
Examples:
# Start two concurrent progress bars with labels
printf "\033]934;set;download;percent=30;label=Downloading file.tar.gz\007"
printf "\033]934;set;compile;state=indeterminate;label=Compiling\007"
# Update one
printf "\033]934;set;download;percent=80;label=Downloading file.tar.gz\007"
# Mark compile as complete and hide
printf "\033]934;remove;compile\007"
# Remove all named bars
printf "\033]934;remove_all\007"Multiple concurrent bars stack vertically at the configured position (top or bottom of the terminal window), below the tab bar at the top or above the status bar at the bottom. The OSC 9;4 bar is drawn first, followed by named bars sorted by ID.
All progress bar settings are available in the Settings UI under Appearance > Progress Bar, which has a General section (enable, style, position, height, opacity) and a Colors section.
| Setting | Description | Default |
|---|---|---|
progress_bar_enabled |
Enable progress bar rendering | true |
progress_bar_style |
Display style: bar or barwithtext (lowercased, no underscore) |
bar |
progress_bar_position |
Position: top or bottom |
top |
progress_bar_height |
Bar height in pixels (text labels need 10.0 or more) | 4.0 |
progress_bar_opacity |
Opacity (0.0-1.0) | 0.8 |
progress_bar_normal_color |
Color for normal state (RGB) | [80, 180, 255] (blue) |
progress_bar_warning_color |
Color for warning state (RGB) | [255, 200, 50] (yellow) |
progress_bar_error_color |
Color for error state (RGB) | [255, 80, 80] (red) |
progress_bar_indeterminate_color |
Color for indeterminate state (RGB) | [150, 150, 150] (gray) |
Example configuration:
progress_bar_enabled: true
progress_bar_style: barwithtext
progress_bar_position: bottom
progress_bar_height: 4.0
progress_bar_opacity: 0.9
progress_bar_normal_color: [80, 180, 255]
progress_bar_warning_color: [255, 200, 50]
progress_bar_error_color: [255, 80, 80]
progress_bar_indeterminate_color: [150, 150, 150]The iProgress vec4 uniform exposes progress bar state to custom GLSL shaders, enabling shader effects that react to progress:
| Component | Description | Range |
|---|---|---|
iProgress.x |
State of the OSC 9;4 bar: 0=hidden, 1=normal, 2=error, 3=indeterminate, 4=warning | 0.0-4.0 |
iProgress.y |
Progress percentage of the OSC 9;4 bar | 0.0-1.0 |
iProgress.z |
Active flag (any bar visible) | 0.0 or 1.0 |
iProgress.w |
Active bar count (OSC 9;4 plus named bars) | 0.0+ |
Example shader usage:
void mainImage(out vec4 fragColor, in vec2 fragCoord) {
vec2 uv = fragCoord / iResolution.xy;
// Glow effect at screen edges during progress
if (iProgress.z > 0.5) {
float edge = smoothstep(0.0, 0.05, uv.x) * smoothstep(0.0, 0.05, 1.0 - uv.x);
float glow = (1.0 - edge) * iProgress.y * 0.3;
// Color based on state
vec3 color = vec3(0.0, 1.0, 0.0); // normal = green
if (iProgress.x > 1.5 && iProgress.x < 2.5) color = vec3(1.0, 0.0, 0.0); // error = red
if (iProgress.x > 3.5) color = vec3(1.0, 0.8, 0.0); // warning = yellow
fragColor += vec4(color * glow, glow);
}
}See Custom Shaders Guide for complete uniform documentation.
# Function to show progress for a loop
progress_loop() {
local total=$1
shift
for i in $(seq 1 "$total"); do
printf "\033]9;4;1;%d\007" $((i * 100 / total))
"$@"
done
printf "\033]9;4;0;0\007"
}
# Usage: progress_loop 10 sleep 0.5# Show progress during a download
printf "\033]9;4;3;0\007" # Indeterminate while starting
curl -O https://example.com/file.tar.gz
if [ $? -eq 0 ]; then
printf "\033]9;4;1;100\007" # Complete
else
printf "\033]9;4;2;0\007" # Error
fi
sleep 1
printf "\033]9;4;0;0\007" # Hide# Run multiple tasks with individual progress bars
printf "\033]934;set;lint;percent=0;label=Linting\007"
printf "\033]934;set;test;percent=0;label=Testing\007"
# Update as tasks progress
printf "\033]934;set;lint;percent=50;label=Linting\007"
printf "\033]934;set;test;percent=25;label=Testing\007"
# Complete
printf "\033]934;remove;lint\007"
printf "\033]934;set;test;percent=100;label=Testing complete\007"
printf "\033]934;remove;test\007"- Custom Shaders Guide -
iProgressuniform and shader development - Automation - Triggers and coprocesses for terminal automation
- Integrations - Shell integration for enhanced terminal features