A real-time terminal plotting application built with the Notty terminal library in OCaml.

Description

terminal-plotter is a powerful real-time terminal plotting application that monitors data files or command output and displays interactive charts. Built using the Notty terminal library, it provides live visualization of changing numeric data with high-resolution Braille histograms and advanced expression-based chart definitions.

Features

Core Capabilities

• Real-time data monitoring with configurable refresh intervals (default: 2.0s)
• Dual data sources: Monitor files or execute commands periodically
• Advanced expression parsing with mathematical operations (+, -, *, /, %, parentheses)
• Flexible data indexing: Use column syntax (c0, c1) or row,column syntax (r1c2)
• Custom chart definitions with optional labels and expressions
• Two chart types: Value charts and Counter charts (showing deltas between readings)
• Configuration profiles: Save and reuse chart configurations via ~/.terminal-plotter

Visualization

• Terminal graphics using Unicode Braille patterns (2x4 dots per character)
• Intelligent grid layout that optimizes chart arrangement based on terminal dimensions
• Dynamic scaling with automatic min/max detection and range adjustment
• Color-coded charts with distinct colors for each data series
• Real-time statistics showing current, minimum, and maximum values
• Responsive design that adapts to terminal resize events
• Memory-efficient circular buffers for historical data storage

Installation

Build and install using Dune:

opam switch create . 5.3.0 --deps-only
dune build
dune install

Usage

Basic Usage

terminal-plotter [OPTIONS] [PROFILE]
terminal-plotter --file FILE [OPTIONS]
terminal-plotter --exec COMMAND [OPTIONS]

Options

• --file FILE - Monitor a data file
• --exec COMMAND - Execute command and plot its output
• -i, --interval SECONDS - Refresh interval in seconds (default: 2.0)
• --value SPEC - Add a value chart with expression (can be used multiple times)
• --counter SPEC - Add a counter chart with expression (can be used multiple times)
• PROFILE - Load a saved profile from ~/.terminal-plotter config file

Chart Specifications

Chart specifications can include optional labels and expressions:

• "Load Average:c0" - Chart labeled "Load Average" showing first column
• "CPU Usage:r0c3*100" - CPU usage from row 0, column 3, multiplied by 100
• "Memory:c1/c2*100" - Memory percentage calculation
• "r1c0+r1c1" - Sum of two values from row 1

Supported expression syntax:

• Column indexing: c0, c1, c2... (first row columns)
• Row,column indexing: r0c0, r1c2, etc.
• Math operators: +, -, *, /, %, ()
• Percentage operator: % (converts to percentage)

Examples

Monitor system load average with default charts:

terminal-plotter --file /proc/loadavg

Monitor with custom value charts:

terminal-plotter --file /proc/loadavg --value "1min:c0" --value "5min:c1" --value "15min:c2"

Monitor with custom refresh interval:

terminal-plotter --file /proc/meminfo --value "Mem Free:r1c0" --value "Mem Available:r2c0" --interval 0.5

Use counter charts to show deltas:

terminal-plotter --file /proc/stat --counter "CPU ticks:c1+c2+c3"

Configuration Profiles

Save frequently used configurations in ~/.terminal-plotter:

loadavg --file /proc/loadavg --value "1min:c0" --value "5min:c1" --value "15min:c2"
memory --exec "free" --value "Used:r1c1" --value "Free:r1c2"
cpu --file /proc/stat --counter "CPU:c1+c2+c3+c4"

Then use with:

terminal-plotter loadavg
terminal-plotter memory

Data Format

The application supports various data formats:

• Whitespace-separated numeric values: 18.78 25.64 22.38
• Fractions: 2/1881 (automatically converted to percentages)
• Multi-row data: Each line becomes a row, accessible via rNcN syntax
• Mixed data types: Numbers, fractions, and text (non-numeric values ignored)