Python Guardian for Windows 11

Current-user Explorer commands for every .py and .pyw file on this machine.

Project home and releases: https://github.com/gaoptimize/PythonGuardian

The repository also contains a submission-ready skills-only PyGuard plugin for Codex under plugin/pyguard.

Use

Right-click a Python file, choose Show more options, then Run Python with arguments….

For an observed run, choose Run under Codex supervision…. A single resident Python Guardian broker queues all launches; it does not create a new Codex for every script. Guardian performs a read-only preflight, launches the target in its selected interpreter, injects its dependency-free PANIC crash observer into that child only, and opens a copyable Markdown postmortem after a failure. Guardian also observes unhandled worker-thread, asyncio-loop, and unraisable exceptions even when the Python process itself later returns exit code zero.

The crash window offers two response paths:

• Try a bounded repair — Codex plans read-only, edits only isolated copies of at most twelve project files, and Guardian compile-checks and checkpoints the result before applying it. The user chooses whether to retry and can undo.
• Work with Codex — opens an interactive Codex console in the project with the evidence path and a discuss-before-editing handoff prompt.

Preflights are cached by script content. Codex threads are durable per project, and duplicate crash fingerprints reuse an existing diagnosis. Jobs, evidence, and reports live under %LOCALAPPDATA%\PythonGuardian.

PowerShell and automation

The installer adds PyGuard to the current user's command path:

PyGuard .\program.py
PyGuard --yes .\program.py --input data.csv
PyGuard --no-preflight --detach .\long_job.py

The default command shows a preflight and asks before launching. --yes makes that approval non-interactive for scripts and other AI agents. pyguardian is provided as an equivalent alias. Run PyGuard --help for all controls.

The launcher parses source with Python's ast module; it does not import the selected script. Conventional argparse fields become text inputs, checkboxes, or choice lists. Dynamic parsers, Click, Typer, and hand-written sys.argv parsing remain available through Additional/raw arguments.

Interpreter selection prefers a nearby .venv, venv, or <project>_venv, then falls back to the Python installation hosting the launcher.

File and directory Browse dialogs start in the selected script's directory. When a retained console finishes, its recent screen transcript is saved under %LOCALAPPDATA%\PythonFileLauncher\logs. Press C (or Ctrl+C at the post-run prompt) to copy that transcript, or O to open the log.

Install or remove

.\Install-PythonGuardian.ps1

The Guardian uses a dedicated virtual environment. The runtime installer pins the tested SDK/CLI pair and does not change any global Python installation. The default program location is %LOCALAPPDATA%\Programs\PythonGuardian.

Guardian lifecycle/status:

guardian_venv\Scripts\python.exe guardian_ctl.py status

Uninstall from Windows Settings → Apps → Installed apps → Python Guardian. Crash evidence is retained unless the user removes it separately.

Registration is under HKCU\Software\Classes\SystemFileAssociations\{.py,.pyw}\shell, so no administrator rights are required and changing the default Python editor does not remove the verb.

Limits

• Static inspection cannot fully reconstruct arguments assembled dynamically.
• The Windows 11 primary context menu requires a packaged IExplorerCommand extension. This lightweight registry verb appears under Show more options.
• The selected program still owns final validation of all arguments.
• Guardian diagnosis is advisory. Preflight and postmortem analysis are read-only. A bounded repair occurs only after explicit user confirmation.

Author and license

Copyright (c) 2026 Thomas M. Schaefer (Tom@6NowPossibleThings.ai).

Built with OpenAI Codex.

Python Guardian is released under the MIT License. OpenAI Codex and other dependencies remain subject to their respective terms and licenses.

Building from source

Requirements: Windows 11, Python 3.10+, PowerShell, and internet access for the isolated PyInstaller build environment.

.\Build-Release.ps1

Artifacts are written to dist\. The build creates a portable ZIP, a self-contained setup EXE, and SHA256SUMS.txt. See SECURITY.md, PRIVACY.md, and THIRD_PARTY_NOTICES.txt.