Metadata-Version: 2.5
Name: macutility
Version: 0.1.0
Summary: A lightweight macOS desktop utility for system monitoring and process management.
Project-URL: Homepage, https://github.com/codesyariah122/MacUtility
Project-URL: Repository, https://github.com/codesyariah122/MacUtility
Project-URL: Issues, https://github.com/codesyariah122/MacUtility/issues
Author: Puji Ermanto
License: MIT
License-File: LICENSE
Keywords: desktop,developer-tools,mac,macos,process-manager,system-monitor,utility
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.10
Requires-Dist: psutil>=7.2.0
Requires-Dist: pyside6>=6.11.0
Description-Content-Type: text/markdown

# MacUtility

A lightweight macOS desktop utility built with Python and PySide6 for monitoring system resources and managing running processes.

MacUtility is designed as a practical developer-oriented utility for macOS, with a focus on quickly identifying high CPU or memory usage and safely managing processes from a graphical interface.

> 🚧 **Project Status:** Early Development / Pre-release

---

## Features

### Process Manager

Monitor running processes directly from a desktop interface.

- View running processes
- Display PID
- Display process name
- Monitor CPU usage
- Monitor memory usage
- View process status
- Search processes by name or PID
- Sort processes by CPU usage
- Terminate processes
- Force kill processes
- Protected system processes

### System Monitor

Monitor basic system resources in real time.

- CPU usage
- Memory usage
- Automatic refresh
- Lightweight monitoring

### Protected Processes

MacUtility includes a protection layer to prevent accidental termination of important macOS processes.

Protected processes include system components such as:

- `kernel_task`
- `launchd`
- `WindowServer`
- `loginwindow`
- `systemuiserver`
- `Finder`
- `Dock`
- `SystemUIServer`
- `coreaudiod`
- `coreduetd`
- `mds`
- `mds_stores`
- `mdworker`
- `mdworker_shared`
- `cfprefsd`
- `opendirectoryd`
- `distnoted`
- `notifyd`

The application also protects selected applications that should remain available during development, including:

- Termius
- Visual Studio Code
- Code Helper

The protection system is intentionally conservative and may be expanded as the project evolves.

---

## Screenshots

### Process Manager

> Screenshot will be added as the UI evolves.

---

## Tech Stack

MacUtility is built with:

- **Python 3**
- **PySide6** — desktop GUI framework
- **psutil** — system and process monitoring

### Architecture

The project separates UI, process management, and utility logic:

```text
MacUtility/
├── app/
│   ├── __init__.py
│   ├── main.py
│   │
│   ├── services/
│   │   ├── __init__.py
│   │   └── process_service.py
│   │
│   ├── ui/
│   │   ├── __init__.py
│   │   └── main_window.py
│   │
│   └── utils/
│       ├── __init__.py
│       └── protected_processes.py
│
├── .gitignore
├── requirements.txt
└── README.md
```

---

## Requirements

- macOS
- Python 3.10+
- pip
- Virtual environment recommended

PySide6 provides the desktop GUI, while psutil is responsible for accessing system and process information.

---

## Installation

### 1. Clone the repository

```bash
git clone https://github.com/codesyariah122/MacUtility.git
cd MacUtility
```

### 2. Create a virtual environment

```bash
python3 -m venv .venv
```

### 3. Activate the virtual environment

```bash
source .venv/bin/activate
```

### 4. Install dependencies

```bash
pip install -r requirements.txt
```

---

## Running the Application

From the project root:

```bash
python -m app.main
```

MacUtility should open as a desktop application.

---

## Development

MacUtility is currently being developed incrementally.

The current development milestone is:

### V0.1.0

- Process monitoring
- CPU monitoring
- Memory monitoring
- Process search
- Process sorting
- Process termination
- Force kill
- Protected processes

Future releases will expand the application into a broader macOS developer utility.

---

## Roadmap

### V0.1.x — Process Manager

- [x] CPU monitoring
- [x] Memory monitoring
- [x] Process list
- [x] Process search
- [x] Process sorting
- [x] Process termination
- [x] Force kill
- [x] Protected processes
- [x] Protected Termius
- [x] Protected Visual Studio Code

### V0.2.x — Dashboard

- [ ] Improved system dashboard
- [ ] Top CPU processes
- [ ] Top memory processes
- [ ] CPU usage indicators
- [ ] Memory usage indicators
- [ ] Process details
- [ ] Background monitoring worker

### V0.3.x — Disk Utilities

- [ ] Disk usage monitoring
- [ ] Large file finder
- [ ] Cache inspection
- [ ] Developer cache utilities
- [ ] Storage overview

### V0.4.x — Network Utilities

- [ ] Network status
- [ ] Network interface information
- [ ] IP information
- [ ] DNS utilities
- [ ] Ping utility
- [ ] Network diagnostics

### V0.5.x — Port Manager

- [ ] List listening ports
- [ ] Identify processes using ports
- [ ] Search ports
- [ ] Terminate process by port
- [ ] Port diagnostics

Example:

```text
Port 8000

PID       Process
1234      php

[ Kill Process ]
```

### V0.6.x — Developer Utilities

Planned utilities for common development environments:

- [ ] PHP process management
- [ ] Node.js process management
- [ ] Laravel utilities
- [ ] Composer utilities
- [ ] npm utilities
- [ ] Yarn utilities
- [ ] Flutter utilities
- [ ] Android SDK utilities
- [ ] Git utilities
- [ ] SSH utilities

### V0.7.x — Docker Utilities

- [ ] Docker container overview
- [ ] Container CPU usage
- [ ] Container memory usage
- [ ] Start/stop containers
- [ ] Docker cleanup utilities
- [ ] Docker resource overview

### V0.8.x — macOS Integration

- [ ] Menu bar application
- [ ] macOS notifications
- [ ] Launch at login
- [ ] Native macOS application icon
- [ ] Improved macOS permissions handling

### V1.0.0 — Stable Release

The goal for `1.0.0` is a stable, polished macOS developer utility with reliable system monitoring and a collection of useful developer-oriented tools.

---

## Safety

MacUtility interacts directly with running processes.

Process termination can cause:

- Unsaved data loss
- Application crashes
- Interrupted development processes
- Unexpected system behavior

For this reason, MacUtility includes protected processes and confirmation dialogs before terminating processes.

Use **Force Kill** only when a process is unresponsive and normal termination does not work.

---

## Why MacUtility?

macOS already provides tools such as Activity Monitor and Terminal for process management.

MacUtility aims to provide a simpler workflow for developers who frequently need to:

1. Identify a process consuming excessive CPU or memory.
2. Find its PID.
3. Determine whether the process is safe to terminate.
4. Stop it without opening Terminal.
5. Access additional developer-oriented utilities from one application.

For example:

```text
🔥 Firefox plugin-container

CPU: 88%

[ Kill ]
```

instead of manually running:

```bash
ps -Ao pid,pcpu,pmem,comm | sort -k2 -nr
```

and then:

```bash
kill -9 <PID>
```

---

## Project Goals

MacUtility aims to become a practical toolbox for macOS developers.

The long-term goal is to bring frequently used commands and diagnostics into one lightweight desktop application.

Instead of remembering multiple Terminal commands, developers should be able to perform common tasks through a single interface.

---

## Contributing

Contributions, suggestions, and issue reports are welcome.

Before submitting a pull request:

1. Fork the repository.
2. Create a feature branch.
3. Make your changes.
4. Test the application on macOS.
5. Commit your changes.
6. Open a pull request.

Example:

```bash
git checkout -b feature/my-feature
```

---

## License

License information will be added before the first public release.

---

## Author

**Puji Ermanto**

GitHub:

https://github.com/codesyariah122

---

## Repository

GitHub:

https://github.com/codesyariah122/MacUtility

---

## Status

MacUtility is currently an active development project.

The current version focuses on the foundation of the process manager and system monitoring functionality. APIs, architecture, UI, and features may change before the `1.0.0` stable release.