Skip to content

usage.md

Latest commit

 

History

History
228 lines (195 loc) · 7.58 KB

usage.md

File metadata and controls

228 lines (195 loc) · 7.58 KB
Raw

Usage

Table of Contents

Keybindings

Key Action
q Quit application (saves configuration)
? Toggle help overlay
t Next color theme
T Previous color theme
l Next layout (cycles through the layout modes, the Detail presets, then custom layouts)
f Toggle full-screen mode for the current widget
F Cycle full-screen focus through all available widgets
/ Open process search / filter
Enter Confirm search filter
Backspace Delete character in search input
Esc Cancel search / close help overlay

Modules

  1. Header -- Shows system uptime, load average, current theme name, and active layout mode.

  2. CPU -- Horizontal usage bars for each CPU core. If hardware sensors are available, displays the maximum CPU temperature.

  3. Memory -- Gauges for RAM and Swap usage, plus a line chart showing RAM usage over a configurable history window.

  4. Storage -- Disk usage gauges per mount point showing capacity and used space.

  5. Network -- Total downloaded (RX) and uploaded (TX) data per interface, with current transfer rates.

  6. Disk I/O -- Read and write speeds per disk device in bytes per second.

  7. Processes -- Scrolling list of processes sorted by CPU usage (top 200 by default; override with XTOP_MAX_PROCESSES), with live search filtering by process name.

  8. GPU -- GPU usage gauges (available on supported hardware).

  9. Battery -- Battery charge level gauges (available on supported hardware).

Help Overlay

Press ? at any time to display a full list of available keybindings on screen. Press ? again or Esc to close the overlay.

Process Search

Search filters the process list in real time:

  • Press / to open the search bar at the top of the process list.
  • Type any query -- results filter instantly by process name.
  • Press Enter to confirm the filter, Esc to cancel, Backspace to delete characters.
  • A centered overlay with a /query_ indicator shows the current search input.

Command Palette

Press ctrl+p to open the command palette, a searchable list of actions (also reachable with the command_palette keybinding). The palette has three pages: Main (go to themes/layouts, toggle or cycle full-screen, search, help, cycle the process sort, random theme, exit), Themes (jump to any loaded theme) and Layouts (jump to any layout). Type to filter, use up/down to move, Enter to run the selected action and Esc to close.

Full-Screen Mode

  • Press f to toggle full-screen mode for the currently focused widget. The widget expands to fill the entire terminal area (minus the header bar).
  • Press F to cycle full-screen focus through widgets in sequence: CPU, Memory, Storage, Network, Processes, Disk I/O, GPU, Battery, then exit.

Responsive Layouts

The interface adapts automatically to the terminal size:

Terminal Size Behavior
Dashboard mode, 100+ cols and 28+ rows Full dashboard layout with 2 columns
Dashboard mode, 80–99 cols or under 28 rows Compact layout
Dashboard mode, narrower than 80 cols Vertically stacked layout
Other modes The requested mode layout (Vertical, Horizontal, CPU/Memory/Network/Process Focus)
Narrower than 60 cols or shorter than 14 rows Minimal layout: CPU, Memory, and Processes only
Smaller than 40 x 8 Warning message displayed (terminal too small)

Command-Line Commands

Besides the TUI, xtop ships management subcommands (run xtop --help for the same list):

CommandDescription
xtop mcpStart the MCP server (stdio transport) for AI agents
xtop plugin listList plugins wired into the kernel Cargo.toml
xtop plugin install <name|url>Install a plugin (self-edits the kernel manifest)
xtop plugin scaffold <name>Create a plugin crate template in plugins-dev/
xtop widget listList widget packs wired into the kernel (Cargo features + pack table)
xtop widget install <name|url|path>Install a widget pack (self-edits the manifest + pack table)
xtop widget scaffold <name>Create a single-widget pack crate template in widgets-dev/
xtop layout check <file>Validate a layout JSONC file
xtop layout install <name>Install a community layout from github.com/xtop-cli/layouts

Plugins and widget packs are compile-time: the commands register crates and feature flags in the kernel's sources; enable a feature in the [features] default list (or build with --features <name>) and rebuild to include it. Widget-pack details live in customization.md (“Widget Packs”), plugin details in plugin.md.

Back to README