Metadata-Version: 2.5
Name: macutility
Version: 0.1.1
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

<img width="1440" height="820" alt="Screenshot 2026-08-31 at 14 52 32" src="https://github.com/user-attachments/assets/d3fdaedf-14b1-4214-87bf-84c4f12eb7f0" />
<img width="1440" height="820" alt="Screenshot 2026-08-31 at 14 52 38" src="https://github.com/user-attachments/assets/c760b7af-28b8-41a3-be0a-7f71bbac746e" />


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

---

## Quick Start

MacUtility is available on PyPI and can be installed directly without cloning the repository.

The recommended installation method for end users is `pipx`.

### Install

```bash
brew install pipx
pipx ensurepath
```

Restart your Terminal if necessary, then:

```bash
pipx install macutility
```

Run MacUtility:

```bash
macutility
```

MacUtility should launch as a desktop application.

---

## 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

The Process Manager provides an overview of currently running processes, including CPU usage, memory usage, process status, protection status, and available actions.

### System Monitor

The system monitor displays current CPU and memory utilization and provides a lightweight overview of system resource usage.

---

## Installation

MacUtility can be installed directly from PyPI.

### Recommended: Install with pipx

For normal users, `pipx` is recommended because it installs MacUtility in an isolated Python environment while making the `macutility` command available globally.

### Requirements

- macOS
- Python 3.10+
- Homebrew
- pipx

### 1. Install pipx

If pipx is not already installed:

```bash
brew install pipx
```

### 2. Configure pipx

```bash
pipx ensurepath
```

Restart your Terminal after running this command if necessary.

You can verify that pipx is available with:

```bash
pipx --version
```

### 3. Install MacUtility

```bash
pipx install macutility
```

pipx will automatically create an isolated environment and install MacUtility together with its required dependencies.

The main dependencies are:

- PySide6
- psutil

### 4. Run MacUtility

```bash
macutility
```

MacUtility should open as a desktop application.

---

## Upgrade MacUtility

When a new version is released on PyPI, upgrade the installed application with:

```bash
pipx upgrade macutility
```

You can check the installed version with:

```bash
pipx list
```

---

## Uninstall MacUtility

To remove MacUtility:

```bash
pipx uninstall macutility
```

---

## Development Installation

If you want to contribute to MacUtility or run the project directly from source code, clone the repository and create a development environment.

### 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
```

### 5. Run the application

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

MacUtility should open as a desktop application.

---

## Running the Application

### Installed from PyPI

If MacUtility was installed with pipx:

```bash
macutility
```

### Running from source

If you are working from the Git repository:

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

---

## Tech Stack

MacUtility is built with:

- **Python 3** — application programming language
- **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
├── LICENSE
├── pyproject.toml
├── requirements.txt
└── README.md
```

---

## PyPI Package

MacUtility is published as the Python package:

```text
macutility
```

Current release:

```text
0.1.0
```

Install the latest published version with:

```bash
pipx install macutility
```

The package provides the following executable:

```bash
macutility
```

The PyPI package is intended to make installation simple for end users without requiring them to clone the source repository or manually configure a virtual environment.

---

## 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
- Protected applications

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.

Protected processes cannot be terminated through the application.

---

## 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>
```

MacUtility aims to provide these workflows through a graphical interface.

---

## Project Goals

MacUtility aims to become a practical toolbox for macOS developers.

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

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

The project is intentionally being developed incrementally, with the Process Manager and System Monitor forming the foundation for future utilities.

---

## Contributing

Contributions, suggestions, bug reports, and feature requests 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
```

For bug reports or feature requests, please provide as much relevant information as possible, including:

- macOS version
- Python version
- MacUtility version
- Steps to reproduce the issue
- Expected behavior
- Actual behavior
- Relevant error messages

---

## Building the Package

MacUtility uses `pyproject.toml` and Hatchling as its build backend.

Install the build and publishing tools:

```bash
python -m pip install --upgrade build twine
```

Build the package:

```bash
python -m build
```

The generated distributions will be placed in:

```text
dist/
├── macutility-0.1.0-py3-none-any.whl
└── macutility-0.1.0.tar.gz
```

Validate the distributions:

```bash
python -m twine check dist/*
```

Both the wheel and source distribution should pass the package validation check before publishing.

---

## Publishing a New Release

Before publishing a new release:

1. Update the version in `pyproject.toml`.
2. Update the documentation if necessary.
3. Test the application.
4. Build the package.
5. Validate the distributions.
6. Publish the package.
7. Commit and push the release changes to GitHub.

Example version update:

```toml
[project]
name = "macutility"
version = "0.1.1"
```

Clean previous build artifacts:

```bash
rm -rf dist build
rm -rf ./*.egg-info
```

Build the new package:

```bash
python -m build
```

Validate:

```bash
python -m twine check dist/*
```

Publish:

```bash
python -m twine upload dist/*
```

> **Important:** A version that has already been uploaded to PyPI cannot be uploaded again. Always increment the package version before publishing a new release.

---

## License

MacUtility is released under the MIT License.

See the [`LICENSE`](LICENSE) file for the full license text.

---

## Author

**Puji Ermanto**

MacUtility is developed as an open-source macOS developer utility project.

---

## Repository

MacUtility source code is maintained in the GitHub repository:

`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.
