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.
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 | bashThis 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.
Using brew
brew tap anistark/tools
brew install sotOr single line:
brew install anistark/tools/sotUpdate using:
brew update && brew upgrade sotUsing pipx
Install and run with pipx. Setup pipx before proceeding.
python3 -m pipx install sot
python3 -m pipx ensurepath
sudo pipx ensurepath --globalor in single line:
python3 -m pipx install sot && python3 -m pipx ensurepath && sudo pipx ensurepath --globalUsing DEB Package (Experimental - Debian/Ubuntu)
### Using DEB Package (Experimental - Debian/Ubuntu)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 -fUsing RPM Package (Experimental - RHEL/CentOS/Fedora)
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-*.rpmPyPI 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.whlInstall 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
sotUsing pipx:
# Clone the repository
git clone https://github.com/anistark/sot.git
cd sot
# Install from source using pipx
pipx install .
# Run from anywhere
sotRun with:
sot- CPU Usage
- Per Core and Thread level
- Processes with ID, threads, memory and cpu usage
- Interactive Order By: Press
oto enter order by mode, pick a column with←/→, toggle sort direction with Enter (DESC ↓ → ASC ↑ → OFF → cycle)
- Interactive Order By: Press
- Views:
1Overview,2Processes,3Disks,4System,5Bench,6Clean (or click the tabs in the header); each view keeps its state while you're elsewhere - Drill down:
Enteron an overview panel opens the matching view on that process or disk;Escgoes 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+Pjumps to any view, process or volume, acts on the selected process, and switches theme
- 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 --listprints every disk and partition as a static table (likedu, but with usage bars) - Disk Usage
- Per Read/Write
- Capacity
- Free
- Used
- Total
- Percent
- Memory Usage
- Capacity
- Free
- Available
- Used
- Swap
- 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
- Apple Silicon (via
- Local IP
- Upload/Download Speed
- Bandwidth
- Network Usage
- Select Interface: Use
--net/-Nto monitor a specific network interface
- Disk Selection: Use
--disk/-Dto monitor a specific volumesot --disk- Pick a volume from a list inside sotsot --disk /Volumes/External- Monitor specific volume
- Theme: Use
--theme/-Tto pick a color theme (classicorcyberpunk)sot --theme cyberpunk- Cyberpunk 2077 inspired neon theme- Set
SOT_THEME=cyberpunkto make it the default; also applies tosot psandsot disk - Switch live with
Ctrl+P→ Theme; graphs and selections are kept, and the choice is remembered
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 withCtrl+Pis remembered and used when nothing else sets one sot --keyslists every binding id with its default keys
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.
sot info ,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
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)
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
The sot disk command shows every physical disk with its partitions.
# 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.
The sot clean command performs a deep clean of your system by removing caches, logs, and temporary files.
# 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 ~/codeThe 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 CacheorGPUCachefolder - 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/tmpwith 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 (
/tmpover 3 days,/var/tmpover 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%, andC:\Windows\Tempas 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
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.
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.
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.
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.
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.
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- 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
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.
sot psThe 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
sotinterface) - 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
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 |
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
The sot bench command allows you to measure disk performance with comprehensive benchmarks including sequential throughput, random IOPS, and latency distribution.
sot benchThis 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 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.jsonThe benchmarking tool runs four comprehensive tests:
- Sequential Read - Measures sustained read throughput (MB/s)
- Sequential Write - Measures sustained write throughput (MB/s)
- Random Read IOPS - Measures random read operations per second
- 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
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 -Husage: 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 -husage: 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 -husage: 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:
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:

