SysMon 📊

A beautiful, lightweight system monitoring tool for your terminal

📸 Screenshots

Main Dashboard

Snapshot View

History View

✨ Features

🎨 Beautiful Terminal UI - Rich colors, progress bars, and organized layouts
⚡ Real-time Monitoring - Live dashboard with auto-refresh
💾 Data Persistence - Store snapshots in JSON or SQLite
📊 Historical Data - View and analyze past system metrics
🎯 Top Processes - Track resource-hungry applications
🔧 Highly Configurable - YAML-based configuration with sensible defaults
📦 Multiple Export Formats - JSON output for scripting and automation
🪵 Smart Logging - Rotating logs with configurable levels
🖥️ Cross-Platform - Works on Windows, macOS, and Linux
🚀 Lightweight - Minimal resource usage and dependencies

🎬 Demo

🚀 Installation

Windows

# Clone the repository
git clone https://github.com/OR-6/sysmon.git
cd sysmon

# Run the installation script
.\install.ps1

# Optional: Add to PATH for 'sysmon' command
.\install.ps1 -AddToPath

Linux / macOS

# Clone the repository
git clone https://github.com/OR-6/sysmon.git
cd sysmon

# Run the installation script
bash install.sh

# Optional: Add to system PATH
sudo ln -s $(pwd)/sysmon /usr/local/bin/sysmon

From PyPI

pip install sysmonitor

Requirements

Python 3.8 or higher
pip (Python package manager)
Works on Windows, macOS, and Linux

🎯 Quick Start

# Windows
python run.py monitor

# Linux/Mac
./sysmon monitor

# All platforms
python -m sysmon.cli monitor

That's it! Press Ctrl+C to exit.

📖 Usage

Monitor Dashboard

Start the live monitoring dashboard:

# Default settings (2 second refresh)
sysmon monitor

# Custom refresh interval
sysmon monitor -i 5

# Show per-CPU core usage
sysmon monitor --per-cpu

# Hide process list for cleaner view
sysmon monitor --no-processes

Controls:

Ctrl+C - Exit the dashboard

Take Snapshots

Capture a single system snapshot:

# Simple snapshot
sysmon snapshot

# JSON output (great for scripts)
sysmon monitor --json > snapshot.json

View History

View stored historical data (requires storage to be enabled):

# Show last 10 snapshots
sysmon history

# Show last 50 snapshots
sysmon history -n 50

# Export as JSON
sysmon history --json > history.json

Configuration

Manage your settings:

# View current configuration
sysmon config show

# Show config file location
sysmon config path

# Change settings
sysmon config set display.refresh_interval 5
sysmon config set storage.enabled true
sysmon config set storage.backend sqlite

# Reset to defaults
sysmon config reset

Export Data

Export your stored snapshots:

# Export to JSON file
sysmon export snapshots.json

# Export to specific location
sysmon export ~/backups/system-data-$(date +%Y%m%d).json

Clear Data

Remove all stored snapshots:

sysmon clear

⚙️ Configuration

Configuration is stored in ~/.config/sysmon/config.yaml

Default Configuration

display:
  refresh_interval: 2        # Refresh every N seconds
  show_per_cpu: false        # Show individual CPU cores
  show_processes: true       # Display top processes
  process_count: 5           # Number of processes to show
  progress_bar_width: 30     # Width of progress bars

storage:
  enabled: false             # Enable data persistence
  backend: json              # 'json' or 'sqlite'
  path: ~/.local/share/sysmon/data
  max_records: 1000          # Keep last N snapshots

logging:
  enabled: true              # Enable logging
  level: INFO                # DEBUG, INFO, WARNING, ERROR
  path: ~/.local/share/sysmon/logs
  max_size_mb: 10           # Max log file size
  backup_count: 3           # Number of backup files

Configuration Examples

Enable data storage:

sysmon config set storage.enabled true
sysmon config set storage.backend sqlite

Show more processes:

sysmon config set display.process_count 10

Change refresh rate:

sysmon config set display.refresh_interval 1

Enable per-CPU monitoring:

sysmon config set display.show_per_cpu true

📚 Commands Reference

Global Options

sysmon --version              # Show version
sysmon --help                 # Show help

Monitor Command

sysmon monitor [OPTIONS]

Options:
  -i, --interval INTEGER    Refresh interval in seconds
  --per-cpu                 Show per-CPU core usage
  --no-processes            Hide process list
  --json                    Output as JSON (single snapshot)
  --help                    Show help

Snapshot Command

sysmon snapshot              # Take a single snapshot

History Command

sysmon history [OPTIONS]

Options:
  -n, --limit INTEGER       Number of snapshots to show (default: 10)
  --json                    Output as JSON
  --help                    Show help

Config Commands

sysmon config show           # Display current configuration
sysmon config path           # Show config file location
sysmon config set KEY VALUE  # Set a configuration value
sysmon config reset          # Reset to defaults

Export Command

sysmon export OUTPUT_PATH    # Export stored data

Clear Command

sysmon clear                 # Clear all stored data

🛠️ Development

Setup Development Environment

# Clone the repository
git clone https://github.com/OR-6/sysmon.git
cd sysmon

# Create virtual environment
python -m venv venv

# Activate virtual environment
# Windows:
.\venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

# Install in development mode with dev dependencies
pip install -e ".[dev]"

Run Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=sysmon tests/

# Run specific test file
pytest tests/test_core.py

Code Quality

# Format code
black src/

# Check style
flake8 src/

# Type checking
mypy src/

Building Distribution

# Build package
python -m build

# Install locally
pip install dist/sysmon-0.1.0-py3-none-any.whl

📁 Project Structure

sysmon/
├── src/
│   └── sysmon/
│       ├── __init__.py       # Package initialization
│       ├── cli.py            # Command-line interface (Click)
│       ├── core.py           # System monitoring logic
│       ├── display.py        # Rich terminal display
│       ├── storage.py        # Data persistence (JSON/SQLite)
│       ├── config.py         # Configuration management
│       ├── models.py         # Pydantic data models
│       └── utils.py          # Helper functions
├── tests/
│   ├── __init__.py
│   └── test_core.py          # Unit tests
├── examples/
│   └── config.example.yaml   # Example configuration
├── screenshots/              # Screenshots for README
├── run.py                    # Cross-platform launcher
├── sysmon                    # Unix/Linux/Mac launcher
├── sysmon.bat                # Windows batch launcher
├── install.sh                # Unix installation script
├── install.ps1               # Windows installation script
├── pyproject.toml            # Project metadata and dependencies
├── setup.py                  # Setup configuration
├── requirements.txt          # Python dependencies
├── README.md                 # This file
├── LICENSE                   # MIT License
└── .gitignore               # Git ignore rules

❓ FAQ

How do I enable data storage?

sysmon config set storage.enabled true

Can I export data to CSV?

Currently, export is JSON only. You can convert JSON to CSV using tools like jq or Python:

# Using jq (if installed)
sysmon history --json | jq -r '.[] | [.timestamp, .cpu.percent, .memory.percent] | @csv'

Why is my CPU showing 0%?

Make sure you're not running SysMon on a very fast refresh interval. CPU measurement needs at least 1 second to be accurate.

How do I uninstall?

pip uninstall sysmonitor

Does this work over SSH?

Yes! SysMon works perfectly over SSH connections as it's a pure terminal application.

Can I monitor remote systems?

Not directly. SysMon monitors the local system where it's running. For remote monitoring, SSH into the remote system and run SysMon there.

What's the difference between JSON and SQLite storage?

JSON: Simple, human-readable, easy to backup
SQLite: More efficient for large datasets, faster queries

How much disk space does storage use?

Each snapshot is approximately 1-2 KB. With default settings (1000 max records), you'll use about 1-2 MB.

🤝 Contributing

Contributions are welcome! Here's how you can help:

Reporting Bugs

Check if the bug has already been reported in Issues
If not, create a new issue with:
- Clear description of the bug
- Steps to reproduce
- Expected vs actual behavior
- Your system info (OS, Python version)

Suggesting Features

Open an issue with the enhancement label describing:

The feature you'd like to see
Why it would be useful
How it might work

Pull Requests

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Add tests if applicable
Ensure all tests pass (pytest)
Format your code (black src/)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Code Guidelines

Follow PEP 8 style guide
Add type hints to all functions
Write docstrings for public APIs
Include tests for new features
Update documentation as needed

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

psutil - Cross-platform system and process utilities
Rich - Beautiful terminal formatting
Click - Elegant CLI framework
Pydantic - Data validation using Python type annotations

Inspiration

Inspired by tools like:

htop - Interactive process viewer
btop - Resource monitor
glances - Cross-platform monitoring tool

🗺️ Roadmap

Version 0.2.0

Alert system with threshold notifications
Custom dashboard layouts
Network interface selection
Disk I/O monitoring

Version 0.3.0

GPU monitoring support (NVIDIA, AMD)
Docker container stats
Temperature sensors
Battery status (laptops)

Version 1.0.0

Web UI option
Prometheus exporter
Plugin system
Remote monitoring capability

📊 Stats

📧 Contact

Author: Numair Khan
Email: ornor6@gmail.com
GitHub: @OR-6
Issues: GitHub Issues

Made with ❤️ by developers, for developers

_{If you find this tool useful, consider giving it a ⭐ on GitHub!}

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
examples		examples
screenshots		screenshots
src/sysmon		src/sysmon
test		test
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
install.ps1		install.ps1
install.sh		install.sh
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
run.py		run.py
setup.py		setup.py
sysmon		sysmon
sysmon.bat		sysmon.bat

Folders and files

Latest commit

History

Repository files navigation

SysMon 📊

📸 Screenshots

Main Dashboard

Snapshot View

History View

✨ Features

🎬 Demo

📋 Table of Contents

🚀 Installation

Windows

Linux / macOS

From PyPI

Requirements

🎯 Quick Start

📖 Usage

Monitor Dashboard

Take Snapshots

View History

Configuration

Export Data

Clear Data

⚙️ Configuration

Default Configuration

Configuration Examples

📚 Commands Reference

Global Options

Monitor Command

Snapshot Command

History Command

Config Commands

Export Command

Clear Command

🛠️ Development

Setup Development Environment

Run Tests

Code Quality

Building Distribution

📁 Project Structure

❓ FAQ

How do I enable data storage?

Can I export data to CSV?

Why is my CPU showing 0%?

How do I uninstall?

Does this work over SSH?

Can I monitor remote systems?

What's the difference between JSON and SQLite storage?

How much disk space does storage use?

🤝 Contributing

Reporting Bugs

Suggesting Features

Pull Requests

Code Guidelines

📝 License

🙏 Acknowledgments

Inspiration

🗺️ Roadmap

Version 0.2.0

Version 0.3.0

Version 1.0.0

📊 Stats

📧 Contact

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages