Skip to content
anistarkPublic

About

Command-line System Obervation Tool

Resources

Contributing

Stars

61 stars

Watchers

2 watching

Forks

Repository files navigation

sot

Command-line system obervation tool.

sot is a Command-line System Obervation Tool in the spirit of top. It displays various interesting system stats and graphs them. Works on all operating systems.

PyPI - Version PyPI Downloads PyPI - Status Open Source Contributors maintenance-status License: MIT

Installation

Python

Quick Install (Recommended)

One-line installer for macOS and Linux - Automatically detects your environment and installs all dependencies:

curl -fsSL https://raw.githubusercontent.com/anistark/sot/main/install.sh | bash

This script will:

  • ✅ Detect your operating system
  • ✅ Check for Python 3.10+ (installs if missing)
  • ✅ Install pipx (if not present)
  • ✅ Install sot and configure PATH
  • ✅ Verify the installation

Note: This installation script does not work on Windows. Windows users should use one of the alternative installation methods below.


Alternative Installation Methods

Using brew
brew tap anistark/tools
brew install sot

Or single line:

brew install anistark/tools/sot

Update using:

brew update && brew upgrade sot
Using uv

Install and run with uv:

uv tool install sot
Using pipx

Install and run with pipx. Setup pipx before proceeding.

python3 -m pipx install sot
python3 -m pipx ensurepath
sudo pipx ensurepath --global

or in single line:

python3 -m pipx install sot && python3 -m pipx ensurepath && sudo pipx ensurepath --global
Using DEB Package (Experimental - Debian/Ubuntu) ### Using DEB Package (Experimental - Debian/Ubuntu)

⚠️ Experimental: DEB packages are experimental. Use uv or pipx for recommended installation.

Download the latest DEB package from the releases page and install:

# Download latest .deb file from releases
wget https://github.com/anistark/sot/releases/latest/download/sot-*.deb

# Install the package
sudo dpkg -i sot-*.deb

# Install any missing dependencies (if needed)
sudo apt-get install -f
Using RPM Package (Experimental - RHEL/CentOS/Fedora)

⚠️ Experimental: RPM packages are experimental. Use uv or pipx for recommended installation.

Download the latest RPM package from the releases page and install:

# Download latest .rpm file from releases
wget https://github.com/anistark/sot/releases/latest/download/sot-*.rpm

# Install the package
sudo rpm -ivh sot-*.rpm

Verifying Releases

PyPI releases are published from GitHub Actions with Trusted Publishing and carry PEP 740 attestations linking each file to this repository. To verify a release file:

uvx pypi-attestations verify pypi --repository https://github.com/anistark/sot pypi:sot-<version>-py3-none-any.whl
Install from source

For testing or installing the latest version from source directly on your system.

Using uv (Recommended):

# Clone the repository
git clone https://github.com/anistark/sot.git
cd sot

# Install from source (system-wide)
uv pip install --system .

# Run from anywhere
sot

Using pipx:

# Clone the repository
git clone https://github.com/anistark/sot.git
cd sot

# Install from source using pipx
pipx install .

# Run from anywhere
sot

Run with:

sot

sot-demo


Features

System

  • CPU Usage
    • Per Core and Thread level
  • Processes with ID, threads, memory and cpu usage
    • Interactive Order By: Press o to enter order by mode, pick a column with ←/→, toggle sort direction with Enter (DESC ↓ → ASC ↑ → OFF → cycle)
  • Views: 1 Overview, 2 Processes, 3 Disks, 4 System, 5 Bench, 6 Clean (or click the tabs in the header); each view keeps its state while you're elsewhere
  • Drill down: Enter on an overview panel opens the matching view on that process or disk; Esc goes back
  • Details: Enter (or a double-click) in a list opens a live detail drawer
  • Filter: / filters the focused list by name, PID, user or command
  • Command palette: Ctrl+P jumps to any view, process or volume, acts on the selected process, and switches theme

Disk

  • Interactive Disk TUI - View all physical disks with partitions
    • Real-time disk usage monitoring with accurate APFS container calculations
    • Visual usage bars and percentage indicators
    • I/O statistics (read/write counts and bytes)
  • Plain Listing - sot disk --list prints every disk and partition as a static table (like du, but with usage bars)
  • Disk Usage
    • Per Read/Write
  • Capacity
    • Free
    • Used
    • Total
    • Percent

Memory

  • Memory Usage
  • Capacity
    • Free
    • Available
    • Used
    • Swap

GPU

  • Live GPU Widget - Real-time GPU stats in the main dashboard (shown automatically when a GPU is detected)
    • Utilization history graph with current percentage
    • Memory usage (used/total, or in-use/allocated on unified-memory systems)
    • Temperature and power draw, when exposed by the platform
  • Cross-platform detection
    • Apple Silicon (via ioreg, no sudo): utilization, memory, renderer/tiler breakdown, core count
    • NVIDIA (via nvidia-smi): utilization, memory, temperature, power
    • AMD (via rocm-smi): best-effort

Network

  • Local IP
  • Upload/Download Speed
  • Bandwidth
  • Network Usage
  • Select Interface: Use --net / -N to monitor a specific network interface

Options

  • Disk Selection: Use --disk / -D to monitor a specific volume
    • sot --disk - Pick a volume from a list inside sot
    • sot --disk /Volumes/External - Monitor specific volume
  • Theme: Use --theme / -T to pick a color theme (classic or cyberpunk)
    • sot --theme cyberpunk - Cyberpunk 2077 inspired neon theme
    • Set SOT_THEME=cyberpunk to make it the default; also applies to sot ps and sot disk
    • Switch live with Ctrl+P → Theme; graphs and selections are kept, and the choice is remembered

Configuration

sot reads an optional config file. sot --config-path shows where (by default ~/.config/sot/config.toml, following $XDG_CONFIG_HOME):

theme = "cyberpunk"          # classic, cyberpunk
default_view = "processes"   # overview, processes, disks, system, bench, clean
net = "en0"                  # network interface on the overview
disk = "/"                   # mountpoint on the overview

[refresh]                    # seconds
cpu = 1.0
processes = 2.0

[keymap]                     # binding id = keys
"sot.process.kill" = "ctrl+k"
"sot.view.processes" = "p"
  • Every key is optional; invalid values are reported and ignored
  • Command-line flags win over SOT_THEME, which wins over the config; a theme picked with Ctrl+P is remembered and used when nothing else sets one
  • sot --keys lists every binding id with its default keys

System Information

The sot info command displays comprehensive system information with a beautiful OS-specific ASCII logo.

Inside sot, the System view (key 4) shows the same facts as panels, with uptime, memory and battery kept live.

Usage

sot info

Example Output

                  ,MMMM.            Host        -  john@macbook.local
                .MMMMMM             Model       -  MacBook Pro
                MMMMM,              SKU         -  MK1E3LL/A
      .;MMMMM:' MMMMMMMMMM;.        Identifier  -  MacBookPro18,1
    MMMMMMMMMMMMNWMMMMMMMMMMM:      Serial      -  C02YX2QZMD6R
  .MMMMMMMMMMMMMMMMMMMMMMMMWM.
  MMMMMMMMMMMMMMMMMMMMMMMMM.        OS          -  macOS 14.5.0 Sonoma
 ;MMMMMMMMMMMMMMMMMMMMMMMM:         Kernel      -  23.5.0
 :MMMMMMMMMMMMMMMMMMMMMMMM:         Firmware    -  10151.121.3
 .MMMMMMMMMMMMMMMMMMMMMMMMM.        DE          -  Aqua
  MMMMMMMMMMMMMMMMMMMMMMMMMMM.      WM          -  Quartz Compositor
   .MMMMMMMMMMMMMMMMMMMMMMMMMM.     Shell       -  zsh
     MMMMMMMMMMMMMMMMMMMMMMMM       Terminal    -  iTerm.app (3.5.2)
      ;MMMMMMMMMMMMMMMMMMMM.
        .MMMM,.    .MMMM,.          Chip        -  Apple M1 Pro (8P + 2E cores)
                                    GPU         -  Apple M1 Pro (16 cores)
                                    Memory      -  8 GiB / 32 GiB

                                    Displays    -  2560 x 1600 Retina (Color LCD)
                                                   3840 x 2160@60.00Hz (Dell U2720Q)

                                    Uptime      -  12d 4h 23m
                                    Battery     -  87% & Discharging

Features

The info command displays detailed system information organized into logical sections:

System Information

  • Host (user@hostname)
  • Model name (e.g., MacBook Pro)
  • SKU/Model number
  • Model identifier
  • Serial number

Software

  • Operating system with version name (e.g., macOS 15.6.1 Sequoia)
  • Kernel version
  • Firmware version
  • Desktop Environment (DE)
  • Window Manager (WM)
  • Shell
  • Terminal emulator

Hardware

  • Chip details with performance/efficiency core breakdown (e.g., Apple M1 Pro with 6P + 2E cores)
  • GPU model with core count
  • Memory (used / total)

Displays

  • All connected displays with resolutions, refresh rates, and display names
  • Screen brightness (when available)

Status

  • System uptime
  • Battery status (percentage and charging state)

OS-Specific Logos

The command automatically detects your operating system and distribution, displaying the appropriate ASCII logo:

macOS: Apple logo

Linux Distributions:

  • Ubuntu
  • Debian
  • Fedora
  • Red Hat / RHEL
  • Arch Linux
  • Manjaro
  • Pop!_OS
  • CentOS
  • Generic Linux/Tux (fallback)

Windows: Windows logo


Disk Viewer

The sot disk command shows every physical disk with its partitions.

Usage

# Disks view (key 3 inside sot)
sot disk

# Plain listing - print once and exit, pipe-friendly
sot disk --list
sot disk -l

--list prints one row per disk, with its partitions nested underneath: device, mountpoint, filesystem, size, used, free, and a colour-coded usage bar (green → yellow above 80% → red above 95%), followed by a total across all disks. On narrow terminals the filesystem column is dropped and the bar shrinks so mountpoints stay readable.


System Cleanup

The sot clean command performs a deep clean of your system by removing caches, logs, and temporary files.

Usage

# Clean view: pick targets with space, press c to clean after confirming
sot clean

# Dry run - print what would be cleaned without deleting
sot clean --dry-run

# Also clean data still in use, like the browser sessions that restore your open tabs
sot clean --force

# Also clear browser cookies, history and site data, and recent items
sot clean --privacy

# Also clear build output and dependencies of projects under a folder
sot clean --projects ~/code

What Gets Cleaned

The clean command detects your operating system and lists only what exists on your machine. A folder that holds another target's folder leaves it to that row, so every byte is counted and removed once.

Everywhere:

  • Browser caches for Chrome, Chromium, Edge, Brave, Vivaldi, Opera, Arc, Firefox, LibreWolf and Zen, including GPU, shader, code and on-device AI model caches
  • Free space inside browser databases, given back with VACUUM (quit the browser first)
  • Old browser session snapshots
  • Electron and other Chromium-based app caches (Slack, Discord, VS Code, Cursor, Claude, Obsidian…), found by their Code Cache or GPUCache folder
  • Developer tool caches: Homebrew, Go, pnpm, uv, Bun, Yarn, Cargo, Gradle, Android, Composer, pip, npm. Homebrew, Go, pnpm and uv are cleaned by their own command when installed
  • Coding agent caches (Claude Code, Codex, pi, opencode, Kilo Code) and old Claude Code and Cursor agent binaries that nothing runs

macOS:

  • Application caches (~/Library/Caches) and command line tool caches (~/.cache), keeping fonts, Spotlight, iCloud, Poetry virtualenvs, Playwright and Puppeteer browsers, JetBrains and LM Studio
  • Application logs (~/Library/Logs), and with sudo system logs over 7 days old and crash reports over 30 days old
  • Temp files over 3 days old ($TMPDIR, and /tmp with sudo)
  • Metal shader, clang module and app helper caches under /var/folders
  • Copies of Chrome-based browsers leaked under /var/folders/*/X/*.code_sign_clone, often tens of GB. The ones a running browser holds open are kept unless you pass --force
  • Xcode DerivedData, simulator caches, simulators for removed runtimes (xcrun simctl delete unavailable) and device support files beyond the newest two per platform
  • Mail downloads and Messages previews
  • Leftover macOS installer payload, Safari cache and Trash

Linux:

  • User cache (~/.cache) with the same exceptions, and thumbnails
  • Temp files (/tmp over 3 days, /var/tmp over 7), system logs over 7 days, the systemd journal (journalctl --vacuum-time=7d), disabled snap revisions and core dumps, with sudo
  • Package manager caches (APT, DNF, Yum) and Trash

Windows:

  • Temp files over 3 days old (%TEMP%, and C:\Windows\Temp as administrator)
  • Crash dumps and error reports, DirectX and GPU driver shader caches, Explorer thumbnails
  • As administrator: Prefetch, system crash dumps, downloaded Windows updates and the Delivery Optimization cache

Review Only

Some stores are big but expensive to get back or hold real work. They're measured and shown in their own table, and never deleted: Docker, OrbStack and Colima VM disks, iOS Simulator devices, Xcode archives, iOS backups, Claude desktop VM images, Ollama, LM Studio and Hugging Face models, the Maven repository, Android emulators, rustup toolchains, Node versions (nvm, fnm, Volta), Python versions (pyenv, uv) and Windows.old.

Privacy

sot clean --privacy (or p in the Clean view) adds rows per browser for cookies, history and site data (IndexedDB, local storage, service workers), plus recent items lists and macOS window state over 30 days old. Clearing cookies signs you out of every site. Quit the browser first, or it writes them straight back. Firefox keeps history and bookmarks in one database, so its history is left alone.

Projects

sot clean --projects DIR searches DIR for build output and dependencies: node_modules, .next, target, .venv, __pycache__, Pods, .build, Gradle build and more. A folder only counts when the file that rebuilds it sits beside it (target next to Cargo.toml, node_modules next to package.json), so a folder that happens to be called target is left alone. Projects touched in the last 14 days are skipped unless you add --force.

Browser Sessions

Browsers save your open windows and tabs to disk so they can bring them back after a restart or a crash. Only the newest save is ever read; the older ones pile up in every profile, often a few MB each. sot clean removes those and leaves the newest alone, so your tabs still come back.

sot clean --force (or f in the Clean view) removes the newest ones too. The browser starts with no tabs to restore and loses its recently closed windows. Quit the browser first: while it runs it holds the current session in memory and may write it straight back.

Browser Old snapshots Also removed with --force
Chrome, Chromium, Edge, Brave, Vivaldi, Opera, Arc All but the newest Session_*, Tabs_* and Apps_* in each profile's Sessions folder The newest of each
Firefox, LibreWolf, Zen sessionstore-backups/upgrade.jsonlz4-*, the copies taken on each upgrade sessionstore.jsonlz4 and the recovery and previous files in sessionstore-backups

Browsers are only listed when there's something to clean. Safari keeps a single session file, so there's nothing old to remove.

Coding Agent Caches

Agents are only listed when they're actually installed, so the table stays limited to what's on your machine. Only caches, logs and scratch directories are touched. Conversation history, sessions, credentials and config are left alone.

Agent Cleaned
Claude Code ~/.claude/{cache,paste-cache,debug,shell-snapshots,session-env,statsig}, ~/.cache/claude, ~/Library/Caches/claude-cli-nodejs
pi ~/.pi/{cache,logs}, ~/.cache/pi
opencode ~/.cache/opencode, ~/.local/share/opencode/{cache,log}
Codex ~/.codex/{.tmp,log}, ~/.cache/codex-runtimes
Kilo Code ~/.kilocode/cache, plus kilocode.kilo-code/{cache,checkpoints} under the VS Code, Cursor and VSCodium global storage directories

Notably left alone: ~/.claude/projects (session transcripts that claude --resume reads) and ~/.gemini/tmp (gemini-cli checkpoints and history). From ~/.local/share/claude/versions only binaries other than the newest, the one ~/.local/bin/claude links to and any that are running are removed.

If you've relocated a cache directory, sot picks it up from the environment rather than assuming the default. Exported variables are read from the shell you run sot in:

Variable Overrides
CLAUDE_CONFIG_DIR ~/.claude
XDG_CACHE_HOME ~/.cache
XDG_DATA_HOME ~/.local/share
XDG_CONFIG_HOME ~/.config
APPDATA / LOCALAPPDATA ~/AppData/Roaming, ~/AppData/Local
VSCODE_PORTABLE VS Code portable-mode user data (no default; paths are skipped when unset)
CARGO_HOME, RUSTUP_HOME, GOPATH, GOMODCACHE, GOCACHE, GRADLE_USER_HOME, NVM_DIR Their tools' default homes
UV_CACHE_DIR, BUN_INSTALL_CACHE_DIR, HF_HOME, OLLAMA_MODELS Their caches and model stores

Use sot clean --dry-run to confirm the resolved locations before deleting anything.

Permissions

Some cleaning targets require elevated privileges (sudo/administrator). The clean command will:

  • Show which items require elevated privileges in the summary
  • Skip these items during cleaning if not running with sudo
  • Provide clear notifications about what was skipped

To clean items requiring sudo:

sudo sot clean

Safety Features

  • Dry run mode: Preview what will be cleaned without making changes
  • In-use data needs --force: Browser sessions that restore open tabs, browser clones still open, the newest device support files and active projects are only removed when asked for
  • Age limits: Temp folders and logs only lose files older than a few days, and keep every folder, so running programs keep their sockets and log directories
  • Live data stays: Fonts, Spotlight, iCloud state, virtualenvs and downloaded browsers inside the cache folders are never touched
  • Review only: Models, VM disks, toolchains and backups are reported, never deleted
  • Symlinks aren't followed: A link inside a cache is removed, never what it points to
  • Interactive confirmation: Always asks before deleting files (in the Clean view and the printed flow)
  • Sudo-aware: Targets that need root are skipped unless sot runs with sudo
  • Clear reporting: Shows exactly what will be cleaned and how much space will be freed
  • Graceful error handling: Skips files that can't be accessed rather than failing

Process Viewer

The sot ps command opens SOT on its Processes view: three synchronized panels for processes, listening ports and development environments. Press 1 to 3 to switch between views.

Usage

sot ps

Features

The process viewer displays three interactive panels:

Process List:

  • All running processes with PID, name, memory usage, and CPU percentage
  • Navigate with arrow keys (↑/↓)
  • Sortable columns (same as main sot interface)
  • Real-time updates every 2 seconds
  • Shows up to 500 processes

Listening Ports:

  • All open ports listening for connections
  • Shows port number, bind address, process name, and PID
  • Useful for identifying which services are running on which ports
  • Updates every 3 seconds
  • Note: May require sudo on macOS for full port detection

Development Environment:

  • Automatically detects running development servers
  • Supports: Node.js, Python, Docker, Ruby, Go, Rust
  • Shows process count, listening ports, CPU and memory usage per environment type
  • Groups related processes (e.g., all Node processes together)
  • Updates every 5 seconds

Keys

The footer lists the keys for the focused panel; press ? for all of them.

Key Action
1 to 6 Overview, Processes, Disks, System, Bench, Clean
Tab / Shift+Tab Next / previous panel
↑ ↓ or k j Move
PgUp PgDn, Home End (g G) Page, first, last
Enter Details drawer (on the overview: open in the Processes or Disks view)
Esc Close the drawer, or go back after a drill-down
/ Filter the focused list
x / t Kill / terminate (asks first)
o Sort: process tables open a column picker (← →, Enter, Esc); ports and dev environments cycle the column, s flips direction
n Show or hide the I/O and connection columns
+ / - Overview zoom: taller graphs, or more process rows (remembered)
r Refresh
Click a column header Sort by it
Ctrl+P Command palette (views, processes, volumes, actions, themes)
? / q Help / quit

Example

The process viewer is particularly useful for developers who want to:

  • Monitor development server resource usage
  • Identify which process is using a specific port
  • Track multiple development environments running simultaneously
  • Debug port conflicts quickly

Disk Benchmarking

The sot bench command allows you to measure disk performance with comprehensive benchmarks including sequential throughput, random IOPS, and latency distribution.

Interactive Mode (Default)

sot bench

This opens the Bench view (key 5 inside sot): pick a disk and press Enter. Results fill in as each test finishes; +/- change the duration, e exports JSON, Esc cancels after the current test.

--disk or --output, or running outside a terminal, keeps the printed flow for scripts:

sot bench --disk disk3 --duration 5 --output results.json

Benchmark Options

# Benchmark with default 10 second duration per test
sot bench

# Specify custom duration (in seconds)
sot bench --duration 5     # Quick 5-second benchmark
sot bench -d 30            # Longer 30-second benchmark for more stable results

# Specify custom output file
sot bench --output results.json

# Combine options
sot bench --duration 20 --output bench_results.json

Benchmark Tests

The benchmarking tool runs four comprehensive tests:

  1. Sequential Read - Measures sustained read throughput (MB/s)
  2. Sequential Write - Measures sustained write throughput (MB/s)
  3. Random Read IOPS - Measures random read operations per second
  4. Random Write IOPS - Measures random write operations per second

Each test runs for the specified duration (default: 10 seconds) and provides detailed metrics:

  • Throughput/IOPS measurements
  • Min/Avg/Max latencies
  • p50, p95, p99 percentile latencies
  • Total test duration

Duration Parameter

The --duration flag controls how long each test runs:

  • Default: 10 seconds - Quick, reliable measurements for most use cases
  • Shorter durations (5s) - Very quick benchmarks for rapid testing
  • Longer durations (30s+) - More stable results, accounts for system variance better

For all options, see

sot -H
usage: sot [--help] [--version] [--log LOG] [--net NET] [--disk [DISK]] [--config-path] [--keys]
           [--theme THEME]
           {info,bench,disk,clean,ps} ...

Command-line System Obervation Tool ≈

commands: {info,bench,disk,clean,ps}
    info                Print system information (the System view is key 4)
    bench               Disk benchmarking view; flags run it without the TUI
    disk                Disks view; --list prints a table instead
    clean               Clean caches, logs and temp files; --dry-run only reports
    ps                  Processes view: processes, listening ports, dev environments

options:
  --help, -H            Show this help message and exit.
  --version, -V         Display version information with styling
  --log LOG, -L LOG     Debug log file path (enables debug logging)
  --net NET, -N NET     Network interface to display (default: auto-detect best interface)
  --disk [DISK], -D [DISK]
                        Disk mountpoint to display (use without value for interactive selection)
  --config-path         Print where sot reads its config file from
  --keys                List every key binding id, for the [keymap] config table
  --theme THEME, -T THEME
                        Color theme: classic, cyberpunk (default: $SOT_THEME, config, or classic)

For benchmark-specific options:

sot bench -h
usage: sot bench [-h] [--output OUTPUT] [--disk DISK] [--duration DURATION]

options:
  -h, --help            show this help message and exit
  --output OUTPUT, -o OUTPUT
                        Output file for benchmark results (JSON format)
  --disk DISK           Disk to benchmark, by id (disk3, /dev/sda) or mountpoint; skips the prompt
  --duration DURATION, -d DURATION
                        Duration for each benchmark test in seconds (default: 10s)

For clean-specific options:

sot clean -h
usage: sot clean [-h] [--dry-run] [--force]

options:
  -h, --help  show this help message and exit
  --dry-run   Show what would be cleaned without actually deleting
  --force     Also clean data still in use, like the browser sessions that restore open tabs

Main Theme:

Color Hex RGB
sky_blue3 #5fafd7 rgb(95,175,215)
aquamarine3 #5fd7af rgb(95,215,175)
yellow #808000 rgb(128,128,0)
bright_black #808080 rgb(128,128,128)
slate_blue1 #875fff rgb(135,95,255)
red3 #d70000 rgb(215,0,0)
dark_orange #d75f00 rgb(215,95,0)

All supported colors.


🏴 ≈ 🏴


sot uses:

Tested Systems:

macOS Ubuntu

If you use a system that's not listed above, feel free to add to the list. If you're facing any issues, would be happy to take a look.


Other top alternatives in alphabetical order:

About

Command-line System Obervation Tool

Resources

Contributing

Stars

61 stars

Watchers

2 watching

Forks

Releases

Packages

Used by

Contributors

Languages