shea

Shea (short for "shell apps") is a collection of modern Python-based shell utilities with colorful emoji icons. Currently includes:

• pyls - Directory listing with tree view (ls/tree replacement)
• pytop - Process viewer sorted by CPU/memory usage (top/htop alternative)
• pydisk - Disk usage viewer with interactive directory explorer (df/ncdu alternative)

Installation

You can install with pip (PEP 517 using Flit under the hood):

pip install .

Or directly with Flit:

python -m pip install flit
flit install

Usage

Directory Listing (pyls)

List current directory (folders first, then files):

shea

Tree view:

shea -t

Specify a path and a maximum depth:

shea --tree --depth 2 ~/projects

Process Viewer (pytop)

Launch the interactive process monitor:

pytop

Features:

• 🔥 Real-time CPU usage per core with visual bars
• 💾 Memory and swap usage with color-coded horizontal charts
• ⚙️ System information (uptime, process count)
• 📊 Process table showing top 50 processes by CPU usage
• 🔄 Click column headers to sort (CPU/MEM/TIME always descending, others toggle)
• Interactive TUI interface with live updates

Controls:

• q - Quit
• r - Force refresh
• Arrow keys - Navigate process list
• Click column headers - Sort by that column

Disk Usage Viewer (pydisk)

Show all disk partitions with usage information:

pydisk

Launch interactive directory explorer for a specific path:

pydisk /
pydisk /home
pydisk ~/projects

Features:

• 💾 Disk usage table showing all partitions with visual bars
• 📊 Color-coded usage percentages (green/cyan/yellow/red)
• 🔍 Interactive TUI to explore directory sizes
• 📁 Navigate directories to see which files/folders use the most space
• ⚡ Recursively calculates folder sizes

Interactive mode controls:

• q - Quit
• r - Refresh current directory
• u or Esc - Go up one directory level
• Click/Enter on a row - Enter directory or show file info
• Arrow keys - Navigate file/folder list

Output examples

Listing:

$ pyls
📁 dist
📁 shea
📁 tests
📄 pyproject.toml
📄 README.md

Tree view:

$ pyls -t
.
├── 📁 dist
│   ├── 📄 pyl-0.1.0-py3-none-any.whl
│   ├── 📄 pyl-0.1.0.tar.gz
│   ├── 📄 qwe-0.1.0-py3-none-any.whl
│   ├── 📄 qwe-0.1.0.tar.gz
│   ├── 📄 shea-0.1.0-py3-none-any.whl
│   ├── 📄 shea-0.1.0.tar.gz
│   ├── 📄 shea-0.1.1-py3-none-any.whl
│   └── 📄 shea-0.1.1.tar.gz
├── 📁 shea
│   ├── 📁 __pycache__
│   │   ├── 📄 __init__.cpython-310.pyc
│   │   ├── 📄 __main__.cpython-310.pyc
│   │   ├── 📄 _version.cpython-310.pyc
│   │   ├── 📄 main.cpython-310.pyc
│   │   └── 📄 pyls.cpython-310.pyc
│   ├── 📄 __init__.py
│   ├── 📄 __main__.py
│   ├── 📄 _version.py
│   └── 📄 pyls.py
├── 📁 tests
│   ├── 📁 __pycache__
│   │   └── 📄 test_basic.cpython-310-pytest-8.3.2.pyc
│   └── 📄 test_basic.py
├── 📄 pyproject.toml
└── 📄 README.md

License

MIT

Development

This project uses pre-commit with Ruff for linting and formatting.

To set up pre-commit hooks:

python -m pip install pre-commit
pre-commit install

Run on all files once:

pre-commit run -a

Ruff lint will auto-fix simple issues on commit; if it makes changes, the commit will fail so you can review and re-commit.