Release: Wombat

Wombat is the current DocsHub architecture.

StaxSys usage and configuration

Keyboard controls

Key	Action
`t`	Toggle process sorting between CPU and memory.
`n`	Show the next network-interface page when more than four are monitored.
`/`	Enter process search; matches process name or PID.
`Enter`	Keep the active process filter.
`Esc`	Clear a filter, or exit when no filter is active.
`q` or `Ctrl+C`	Exit when not typing a search query.

Network-interface pages also advance automatically every ten seconds.

Configuration precedence

StaxSys resolves settings in this order:

defaults < configuration file < command-line flags

The default file is ~/.config/staxsys/config.json. If XDG_CONFIG_HOME is set, StaxSys uses $XDG_CONFIG_HOME/staxsys/config.json. Pass --config to use another file.

Command-line flags

Flag	Purpose	Default
`--interval <ms>`	Refresh interval in milliseconds.	`1000`
`--disk <paths>`	Comma-separated mount points.	`/`
`--iface <names>`	Comma-separated network interfaces.	Auto-detected
`--config <path>`	JSON configuration path.	Platform configuration directory
`--version`	Print the installed version and exit.	—
`-h`, `--help`	Print command help and exit.	—

Do not include spaces inside comma-separated flag values:

staxsys --disk /,/home --iface eth0,wlan0

STAX_DISK_PATH provides comma-separated disk targets when neither the file nor a CLI flag sets disks.

Configuration file

{
  "interval": 1500,
  "disks": ["/", "/home"],
  "networkInterfaces": ["eth0", "wlan0"],
  "processes": { "sort": "cpu", "limit": 8 },
  "alerts": { "cpu": 80, "memory": 85, "disk": 90 },
  "history": { "enabled": true, "maxSamples": 3600 },
  "theme": {
    "border": "cyan",
    "header": "cyan",
    "barNormal": "green",
    "barWarn": "yellow",
    "barCritical": "red",
    "spark": ["cyan", "magenta", "yellow", "green"]
  }
}

Field	Default	Notes
`interval`	`1000`	Refresh interval in milliseconds.
`disks`	`["/"]`	Mount points to monitor.
`networkInterfaces`	Auto-detected	Interfaces to monitor.
`processes.sort`	`"cpu"`	Accepts `"cpu"` or `"memory"`.
`processes.limit`	`6`	Visible processes; maximum `20`.
`alerts.cpu`	Unset	CPU alert percentage from 1–100.
`alerts.memory`	Unset	Memory alert percentage from 1–100.
`alerts.disk`	Unset	Per-disk alert percentage from 1–100.
`history.enabled`	`true`	Enables reading and writing metric history.
`history.maxSamples`	`3600`	Samples per metric, clamped to 60–259200.

Invalid flags and values produce an error and a non-zero exit code. Invalid alert thresholds are ignored. Unknown theme colours fall back to their slot’s default; accepted names are black, red, green, yellow, blue, magenta, cyan, white, gray, and grey.

Persisted history

CPU, memory, and first-disk percentages are stored in ~/.config/staxsys/history.json, respecting XDG_CONFIG_HOME. StaxSys writes roughly every ten seconds and once more during a clean exit. Writes use a temporary file and rename so an interrupted write does not leave truncated history.

The default 3,600-sample buffer is approximately one hour at the default interval and uses roughly 100 KB per metric. Set history.enabled to false to disable both loading and saving it.

Upgrade note from vibe-sysmonitor

StaxSys does not read ~/.config/vibe-sysmonitor/, and the old VIBE_DISK_PATH variable was replaced by STAX_DISK_PATH. Move or recreate the settings you still need after upgrading.