Metadata-Version: 2.4
Name: procclean
Version: 1.3.0
Summary: Interactive TUI for exploring and cleaning up processes - find orphans, memory hogs, and kill them
Keywords: cleanup,kill,memory,orphan,process,terminal,tui
Author: Kaj Kowalski
Author-email: Kaj Kowalski <info@kajkowalski.nl>
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Dist: psutil>=7.2.1
Requires-Dist: tabulate>=0.9.0
Requires-Dist: textual>=7.0.0
Requires-Python: >=3.14
Project-URL: Homepage, https://procclean.kjanat.com
Project-URL: Repository, https://github.com/kjanat/procclean
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.github.com/kjanat/procclean/master/logo/procclean-transparent.svg" alt="procclean" width="500">
</p>

<p align="center">
  <em>Interactive TUI for exploring and cleaning up processes - find orphans, memory hogs, and kill them.</em>
</p>

<p align="center">
  <a href="https://pypi.org/project/procclean/"><img src="https://img.shields.io/pypi/v/procclean" alt="PyPI"></a>
  <a href="https://github.com/kjanat/procclean/blob/master/LICENSE"><img src="https://img.shields.io/github/license/kjanat/procclean" alt="License"></a>
  <a href="https://procclean.kjanat.com"><img src="https://img.shields.io/badge/docs-mkdocs-blue" alt="Docs"></a>
  <img src="https://img.shields.io/badge/python-3.14%2B-blue" alt="Python 3.14+">
  <img src="https://img.shields.io/badge/platform-linux-lightgrey" alt="Linux">
</p>

## Features

- **Memory overview** - Real-time total/used/free/swap display
- **Multiple views** - All processes, Orphaned, Process Groups, High Memory
  (>500MB)
- **Orphan detection** - Finds processes whose parent died (PPID=1)
- **Tmux awareness** - Won't flag tmux processes as orphan candidates
- **Batch operations** - Select multiple processes and kill them at once
- **Process grouping** - Find duplicate/similar processes consuming resources
- **CLI mode** - Scriptable commands with JSON/CSV/Markdown output

## Installation

```bash
pip install procclean
```

Or with [uv](https://docs.astral.sh/uv/):

```bash
uv tool install procclean
```

Run without installing:

```bash
uvx procclean
```

## Usage

### TUI Mode (default)

```bash
procclean
```

### CLI Commands

```bash
procclean list                      # List processes (table)
procclean list -f json|csv|md       # Different output formats
procclean list -s mem|cpu|pid|name|cwd  # Sort by field
procclean list -o                   # Orphans only
procclean list -m                   # High memory only
procclean list -k                   # Killable orphans only
procclean list --cwd                # Filter by current directory
procclean list --cwd /path/to/dir   # Filter by specific cwd

procclean groups                    # Show process groups

procclean kill <PID> [PID...]       # Kill process(es)
procclean kill -f <PID>             # Force kill (SIGKILL)
procclean kill --cwd /path -y       # Kill all in cwd (skip confirm)
procclean kill -k -y                # Kill all killable orphans
procclean kill -k --preview         # Preview what would be killed

procclean mem                       # Show memory summary
```

## TUI Keybindings

| Key     | Action                  |
| ------- | ----------------------- |
| `q`     | Quit                    |
| `r`     | Refresh                 |
| `k`     | Kill selected (SIGTERM) |
| `K`     | Force kill (SIGKILL)    |
| `o`     | Show orphans            |
| `a`     | Show all                |
| `g`     | Show groups             |
| `w`     | Filter by selected cwd  |
| `W`     | Clear cwd filter        |
| `Space` | Toggle selection        |
| `s`     | Select all visible      |
| `c`     | Clear selection         |
| `1`     | Sort by memory          |
| `2`     | Sort by CPU             |
| `3`     | Sort by PID             |
| `4`     | Sort by name            |
| `5`     | Sort by cwd             |
| `!`     | Reverse sort order      |

## Views

- **All Processes** - All user processes sorted by memory usage
- **Orphaned** - Processes with PPID=1 (parent died)
- **Process Groups** - Similar processes grouped together
- **High Memory** - Processes using >500MB RAM

## Output Formats

CLI supports multiple output formats via `-f`:

- `table` - Human-readable table (default)
- `json` - JSON array for scripting
- `csv` - CSV for spreadsheets
- `md` - Markdown table

## Requirements

- Python 3.14+
- Linux (uses `/proc` filesystem)

## Development

```bash
git clone https://github.com/kjanat/procclean
cd procclean
uv sync
uv run pre-commit install
```

Run tests:

```bash
uv run pytest
```

## License

[MIT][license]

<!--link definitions-->

[license]: https://github.com/kjanat/procclean/blob/master/LICENSE "MIT License"

<!--markdownlint-disable-file MD033 MD041-->
