Skip to main content

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 venv or .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 (venv and .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 3 there

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 vol on Windows (installed automatically)
  • pactl, wpctl, or amixer for vol on Linux
  • Windows 10/11 and Windows PowerShell 5.1+ for killNotif

All other commands work on Windows, macOS, and Linux.

Contributing

Contributions are welcome.

  1. fork the repository
  2. create a feature branch
  3. make your changes
  4. run the relevant checks
  5. 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)

Source distribution for optforge 0.3.7
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)

Table of built distributions (wheels) for optforge 0.3.7
File Interpreter ABI Platform Actions
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 log

Release 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 log

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

Select from 2 files

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 log

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

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page