OptForge
Small developer CLI tools for inspecting listening ports, checking environment variables, monitoring disk usage, cleaning Python cache artifacts, controlling output volume, and clearing Windows toast notifications. Most tools are cross-platform; killNotif is Windows-only.
Built with Python, Typer, and Rich.
Overview
OptForge is a lightweight command-line toolkit for developers who want fast answers about the local runtime environment.
It helps you:
- inspect active TCP listeners and identify the owning process
- check whether a port is free or already in use
- test a host/port connection from the terminal
- review environment variables and runtime context
- monitor disk space and storage pressure
- remove stale Python cache artifacts from local projects, without scanning
venvor.venv - get, set, mute, and adjust the default output volume
- clear Windows toast notifications, optionally for a single app (Windows 10/11 only)
Why use OptForge?
Whether you're starting a local service, troubleshooting an app crash, checking for port collisions, or cleaning up a messy Python workspace, OptForge gives you quick terminal-based tools without opening a full IDE or browser.
Most tools are designed to be simple, fast, and cross-platform; killNotif is Windows-only.
Features
Port inspection
- list all listening TCP ports
- show the process associated with each port
- detect whether a port is free or in use
- test connectivity to a host and port
- wait until a port reaches the desired state
Environment checks
- inspect environment variables and runtime context
- useful for debugging app configuration issues
- helpful for local setup and deployment verification
Disk monitoring
- inspect filesystem usage and storage conditions
- identify when available disk space is running low
- support local development diagnostics
Volume control
- read and set the default output volume
- increase or decrease the volume by a custom step
- set 100% or 0% instantly
- mute, unmute, or toggle mute
- emit JSON or stay quiet for scripting
- works on Windows, macOS, and Linux
Python cache cleanup
- remove
__pycache__directories and stale Python bytecode files - skip virtual environments (
venvand.venv) instead of scanning them - help keep workspaces clean without walking dependency trees
Windows notification cleanup (Windows only)
- clear all toast notifications from the Windows Action Center
- clear notifications from a single app by AUMID
- emit JSON or stay quiet for scripting
- requires Windows 10/11 and Windows PowerShell 5.1+
- not available on macOS or Linux; the command exits with code
3there
Installation
Python 3.14.7 or newer is required.
Install from PyPI with pipx
The recommended installation method is pipx:
pipx install optforge
Install from PyPI with pip
python -m pip install optforge
Install from a local clone
git clone https://github.com/cmd-3324/OptForge.git
cd OptForge
pipx install --editable .
Quick start
After installation, the package exposes the following commands:
optforge --help
portcheck --help
envcheck --help
diskcheck --help
pycache-clean --help
vol --help
killNotif --help # Windows 10/11 only
optforge killNotif --help
Platform support
| Tool | Windows | macOS | Linux |
|---|---|---|---|
portcheck, envcheck, diskcheck, pycache-clean |
Yes | Yes | Yes |
vol |
Yes | Yes | Yes |
killNotif |
Windows 10/11 only | No | No |
vol uses the system mixer: Core Audio on Windows, osascript on macOS, and pactl/wpctl/amixer on Linux.
killNotif relies on the Windows Runtime toast notification APIs and Windows PowerShell 5.1, so it cannot run on macOS or Linux. The CLI reports a clear error and exits with code 3 instead of failing with a traceback.
Usage examples
Check ports
portcheck list
portcheck list --sort process
portcheck check 8000
portcheck find 5432
portcheck connect localhost 5432
portcheck wait 8000 --until free --timeout 60
Inspect the environment
envcheck
Check disk usage
diskcheck
Control output volume
vol get
vol status
vol on 50
vol up 10
vol down 10
vol full
vol none
vol mute
vol unmute
vol toggle
vol on <PERCENT> sets an absolute level, while vol up and vol down change it relative to the current level (default step: 5). Setting a level above 0 also unmutes the output.
Use --json for machine-readable output and --quiet to suppress output:
vol get --json
vol on 35 --json
vol toggle --json
Clean Python cache files
pycache-clean searches a project for __pycache__ directories and deletes them. Folders named venv or .venv are ignored so virtualenv bytecode is left alone and the scan stays fast. The legacy pycacheClean alias is also installed.
pycache-clean --dry-run
pycache-clean --recursive
pycache-clean --max-depth 2
Clear Windows notifications
killNotif clears toast notifications from the Windows Action Center. It requires Windows 10/11 and Windows PowerShell 5.1+; it does not work on macOS or Linux.
killNotif
killNotif --aumid "Microsoft.WindowsStore_8wekyb3d8bbwe!App"
killNotif --json
killNotif --quiet
Use --aumid to target one sender. --json prints {"aumid": ..., "cleared": ...}, and --quiet suppresses output. The command exits 0 on success, including when there was nothing to clear, and 3 when it cannot run.
Project structure
OptForge/
├── src/
│ └── optforge/
│ ├── core/
│ ├── diskcheck/
│ ├── envcheck/
│ ├── killNotif/
│ ├── portcheck/
│ ├── pycacheclean/
│ └── volume/
├── Makefile
├── README.md
├── pyproject.toml
├── uv.lock
├── .gitignore
└── .python-version
Development
The repository uses Python packaging and a modern CLI setup.
Common commands:
make install
make lint
make format
make test
Requirements
- Python 3.14.7+
- Typer
- Rich
- psutil
- pycaw for
volon Windows (installed automatically) pactl,wpctl, oramixerforvolon Linux- Windows 10/11 and Windows PowerShell 5.1+ for
killNotif
All other commands work on Windows, macOS, and Linux.
Contributing
Contributions are welcome.
- fork the repository
- create a feature branch
- make your changes
- run the relevant checks
- open a pull request
License
MIT. See LICENSE.
Summary
OptForge is a practical toolkit for developers working on local environments, especially when they need fast answers about ports, runtime configuration, storage health, output volume, Python project clutter, and Windows notification noise.
Metadata
Release files for optforge 0.3.7
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| optforge-0.3.7.tar.gz | 33.5 kB | With provenance | Details for optforge-0.3.7.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| optforge-0.3.7-py3-none-any.whl | Python 3 | none | any | Details for optforge-0.3.7-py3-none-any.whl |
Total release size: 77.2 kB
Release files / optforge-0.3.7.tar.gz
| Download URL | optforge-0.3.7.tar.gz |
|---|---|
| Size | 33.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a4e6e5e66345fb3b6874777b033b9f4fdb9e96c147daab3b8e8926fe83a1b18a
|
|
BLAKE2b-256 checksum How to use checksums |
5eec183475ae272cfe3fa96240ef9d26f4abaaeb96deae9c2da526ad783126d7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logRelease files / optforge-0.3.7-py3-none-any.whl
| Download URL | optforge-0.3.7-py3-none-any.whl |
|---|---|
| Size | 43.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
acebeaa53fc593e7874f3ba40502f50a8f690ee1d53e1ef6519eb1ff4006f6f7
|
|
BLAKE2b-256 checksum How to use checksums |
7d5523b9b87601b5f8a7da0524e22fd4179bd333cfbc0102b45963fe45047a25
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logSecurity for optforge 0.3.7
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for optforge-0.3.7.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.