Stable

gartop

System Monitor

A modular system monitor daemon and interactive GUI for the gardesk environment. Real-time monitoring of CPU, memory, network, disk I/O, temperature, GPU, and processes with time-series graphs and an interactive process list.

View on GitHub Install

gartop CPU monitoring with per-core graphs

Features

Real-time CPU monitoring (overall and per-core)
Memory and swap usage tracking
Network interface statistics and rates
Disk I/O monitoring per device
Temperature sensors via hwmon
GPU utilization and VRAM usage
Interactive process list with tree view
Process detail overlay with per-process sparklines
Container detection (Docker, Podman, Kubernetes, LXC)
Per-process network socket tracking via netlink
Time-series graphs with Cairo rendering
Catppuccin Mocha color theme with per-metric colors
Background daemon with ring buffer history
Type-to-jump fuzzy process navigation
CLI control via gartopctl
Configurable collection intervals
systemd user service integration

Quick Start

What is gartop?

gartop is a system monitor consisting of a background daemon that collects metrics and an interactive GUI for visualization. It monitors CPU, memory, network, disk, temperature, GPU, and running processes.

The daemon maintains a ring buffer history of metrics that can be queried via gartopctl or displayed in real-time graphs.

Installation

Install gartop using the unified installer or build from source:

terminal

$ curl -fsSL https://gar.musicsian.com/install.sh | bash -s -- --component=gartop # Install via script

$ cd ~/.local/src/gardesk/gartop && cargo build --release # Or build from source

Running gartop

gartop can run as a standalone GUI or as a daemon with separate visualization. Running with no subcommand launches the GUI.

GUI Mode (Default)

terminal

$ gartop # Start interactive GUI

$ gartop gui --pane memory # Open to Memory tab

$ gartop gui --pane network # Open to Network tab

$ gartop --config ~/custom.toml # Custom config path

Daemon Mode

terminal

$ gartop daemon # Start background daemon

$ gartop daemon --foreground # Run in foreground (for debugging)

Querying with gartopctl

terminal

$ gartopctl status # Daemon version, uptime, intervals

$ gartopctl cpu # Current CPU stats

$ gartopctl memory # Current memory stats

$ gartopctl processes --sort cpu --limit 10 # Top 10 by CPU

systemd Integration

Run gartop as a systemd user service for automatic startup:

terminal

$ systemctl --user enable gartop # Enable on login

$ systemctl --user start gartop # Start now

$ systemctl --user status gartop # Check status

Configuration

gartop is configured via TOML at ~/.config/gartop/config.toml.

Full Configuration Example

~/.config/gartop/config.toml

$ [daemon] # Background daemon settings

$ sample_interval_ms = 1000 # Collection interval (1 second)

$ history_size = 300 # Ring buffer size (5 min @ 1Hz)

$ max_processes = 100 # Max processes to track

$ [gui] # GUI settings

$ width = 600 # Window width

$ height = 500 # Window height

$ refresh_rate = 30 # FPS (frames per second)

$ show_legend = true # Show graph legends

$ font_family = "sans-serif" # Font for text

$ font_size = 12.0 # Font size

$ default_pane = "cpu" # Start on CPU tab

Daemon Settings

Option	Default	Description
`sample_interval_ms`	1000	Metric collection interval in milliseconds
`history_size`	300	Number of samples to keep in ring buffer
`max_processes`	100	Maximum processes to track

GUI Settings

Option	Default	Description
`width`	600	Window width in pixels
`height`	500	Window height in pixels
`refresh_rate`	30	GUI refresh rate (FPS)
`show_legend`	true	Display legends on graphs
`font_family`	"sans-serif"	Font for GUI text
`font_size`	12.0	Font size in points
`default_pane`	"cpu"	Starting tab: cpu, memory, network, disk

Overview

gartop provides comprehensive system monitoring through three components:

gartop daemon - Background service collecting system metrics at configurable intervals
gartop gui - Interactive X11 window with graphs, process list, and real-time updates
gartopctl - Command-line tool for querying daemon and controlling processes

Data Sources

• /proc/stat - CPU statistics
• /proc/meminfo - Memory information
• /proc/net/dev - Network interface stats
• /proc/diskstats - Disk I/O statistics
• /sys/class/hwmon - Temperature sensors
• /sys/class/drm - GPU information
• /proc/[pid]/ - Per-process data

Keyboard Shortcuts

Key	Action
`q` / `Escape`	Quit application
`1` - `4`	Switch to CPU/Memory/Network/Disk tab
`Tab`	Cycle through tabs
`/`	Search/filter processes
`Alt+f`	Toggle freeze mode
`K`	Kill selected process (SIGTERM)
`T`	Toggle tree view
`?`	Show help overlay
`X`	Kill selected process (SIGKILL)
`r`	Refresh metrics
`Enter`	Process detail view
`Up` / `Down`	Navigate process list
`PgUp` / `PgDn`	Jump 10 rows
`Home` / `End`	Jump to first/last process
`a-z`	Type-to-jump (fuzzy match, 1.5s timeout)
`Backspace`	Clear last character in jump pattern
`Y` / `N`	Confirm/cancel kill dialog

IPC Protocol

gartop exposes an IPC interface via Unix socket. The gartopctl CLI provides easy access to daemon functionality.

Socket Location

socket

$ $XDG_RUNTIME_DIR/gartop.sock # Default location

$ /run/user/1000/gartop.sock # Typical path

gartopctl Commands

terminal

$ gartopctl status # Daemon version, uptime, intervals

$ gartopctl cpu # Current CPU stats

$ gartopctl memory # Current memory stats

$ gartopctl cpu-history --count 20 # Last 20 CPU samples

$ gartopctl memory-history --count 20 # Last 20 memory samples

$ gartopctl processes --sort cpu --limit 10 # Top 10 by CPU

$ gartopctl processes --sort memory --limit 5 # Top 5 by memory

$ gartopctl kill 1234 # Kill PID 1234 (SIGTERM)

$ gartopctl kill 1234 --signal 9 # Kill PID 1234 (SIGKILL)

$ gartopctl reload # Reload configuration

$ gartopctl quit # Shutdown daemon

JSON Protocol

Commands are sent as JSON lines over the Unix socket:

Request Examples

json

$ {"command": "status"}

$ {"command": "get_cpu"}

$ {"command": "get_memory"}

$ {"command": "get_cpu_history", "count": 10}

$ {"command": "get_network"}

$ {"command": "get_network_history", "count": 10}

$ {"command": "get_disk"}

$ {"command": "get_disk_history", "count": 10}

$ {"command": "get_temperature"}

$ {"command": "get_gpu"}

$ {"command": "get_processes", "sort_by": "cpu", "limit": 20}

$ {"command": "kill_process", "pid": 1234, "signal": 15}

Response Format

json

$ {"success": true, "data": {...}} # Success

$ {"success": false, "error": "message"} # Error

Event Subscriptions

Subscribe to real-time updates:

• cpu_update - CPU stats changed
• memory_update - Memory stats changed
• process_update - Process list changed
• network_update - Network stats changed
• disk_update - Disk stats changed
• temp_update - Temperature changed
• gpu_update - GPU stats changed

Troubleshooting

gartopctl: connection refused

The daemon is not running or socket doesn't exist.

• Start daemon: gartop daemon
• Check socket: ls $XDG_RUNTIME_DIR/gartop.sock
• Check systemd: systemctl --user status gartop

Missing temperature sensors

Temperature readings require hwmon kernel modules.

• Check sensors: ls /sys/class/hwmon/
• Load modules: modprobe coretemp or modprobe k10temp
• Install lm-sensors: sensors-detect

No GPU metrics

GPU metrics require DRM sysfs files (AMD/Intel).

• Check DRM: ls /sys/class/drm/card*/device/
• NVIDIA GPUs require separate tooling (nvidia-smi)
• Some integrated GPUs may not expose utilization metrics

High CPU usage from gartop itself

Reduce collection frequency or GUI refresh rate.

• Increase sample_interval_ms (e.g., 2000)
• Reduce refresh_rate (e.g., 15)
• Reduce max_processes (e.g., 50)

Process kill: permission denied

You can only kill processes owned by your user. Root processes require elevated privileges.

• Check process owner in the detail view (Enter on process)
• For system processes, use sudo kill from a terminal

No disk metrics

Disk metrics only track physical devices (sda, nvme0n1, vda). Partitions, loop devices, and device-mapper entries are filtered out.

• Check available: cat /proc/diskstats | grep -v loop
• Virtual machines may expose disks as vda, xvda

Missing network interfaces

gartop filters out loopback (lo), virtual Ethernet (veth*), and Docker bridge (docker*) interfaces by default.

• Physical interfaces (eth*, wlan*, enp*) should appear automatically
• Check available: cat /proc/net/dev

GUI window not appearing

gartop requires a running X11 display.

• Check DISPLAY: echo $DISPLAY
• Try daemon + GUI separately: gartop daemon & then gartop gui
• Verify gartk deps: pkg-config --modversion cairo pangocairo

Debug logging

Enable debug output to diagnose issues:

terminal

$ RUST_LOG=debug gartop daemon --foreground # Full debug

$ RUST_LOG=gartop=debug gartop # gartop only

cpu	CPU usage % (default, descending)
memory	Memory usage % (descending)
disk_read	Disk read rate (descending)
disk_write	Disk write rate (descending)
disk_total	Combined read+write (descending)
net_connections	Open network connections (descending)
net_tcp	TCP connection count (descending)
net_bandwidth	Combined RX+TX rate (descending)
pid	Process ID (ascending)
name	Process name (ascending)

CPU	Pink (#f38ba8)
Memory	Green (#a6e3a1)
Swap	Yellow (#f9e2af)
Network	Cyan (#94e2d5)
Disk	Purple (#cba6f7)
Temperature	Peach (#fab387)
GPU	Sky (#89dceb)

gartop

Features

Quick Start

What is gartop?

Installation

Running gartop

GUI Mode (Default)

Daemon Mode

Querying with gartopctl

systemd Integration

Configuration

Full Configuration Example

Daemon Settings

GUI Settings

Overview

Data Sources

Architecture

Project Structure

Daemon Mode

Collection Loop

Delta Calculations

GUI Mode

Layout

Header Bar Contents

System Metrics

CPU

Memory

Network

Disk I/O

Temperature

GPU

CPU Metrics

Available Data

Calculation

Memory Metrics

Network Metrics

Disk I/O Metrics

Temperature Metrics

GPU Metrics

Process Monitoring

Available Fields

Sorting Options

Collection

GUI Features

Metric Tabs

CPU Tab

Memory Tab

Network Tab

Disk Tab

Time-Series Graphs

Metric Colors (Catppuccin Mocha)

Process List

Detail View

Keyboard Shortcuts

IPC Protocol

Socket Location

gartopctl Commands

JSON Protocol

Request Examples

Response Format

Event Subscriptions

Troubleshooting

gartopctl: connection refused

Missing temperature sensors

No GPU metrics

High CPU usage from gartop itself

Process kill: permission denied

No disk metrics

Missing network interfaces

GUI window not appearing

Debug logging