CodexProcessGuard

KO | EN

gitlite — search

#python #hacktoberfest #ai #go #rust #linux #docker #cli #vue #awesome-list #security #mcp #openai #open-source

CodexProcessGuard

(★ 18)

External Windows guard for the Codex Desktop taskkill/Git cancellation storm.

CodexProcessGuard Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Codex Process Guard

Emergency external containment for the severe Codex Desktop process-cleanup
storm on Windows.

This workaround was created after Codex Desktop repeatedly generated hundreds
of `taskkill.exe /PID <pid> /T /F` helpers, exhausted process/thread/handle and
WMI quotas, and made the machine appear out of memory despite substantial free
RAM. The upstream report and detailed bundle evidence are tracked in
[openai/codex#33776](https://github.com/openai/codex/issues/33776).

> [!IMPORTANT]
> This is an independent emergency guard, not an OpenAI product and not an
> upstream fix. It exists because a machine already inside the storm may be too
> unresponsive to let Codex repair itself.

## One-click installation

1. Download `CodexProcessGuard-v0.1.2-win-x64.zip` from the
   [latest release](https://github.com/BIOcanse/CodexProcessGuard/releases/latest).
2. Extract the ZIP.
3. Double-click `Install.cmd`.

No administrator rights or separate .NET installation are required. The bundle
contains a self-contained Windows x64 executable. Installation validates the
binary and configuration in a staging directory, atomically switches the app,
then registers and immediately starts a per-user scheduled task named
`Codex Process Guard` for future logons. A failed upgrade restores the previous
working installation.

The executable is not Authenticode-signed. Windows SmartScreen may therefore
show an unknown-publisher warning. Verify the release SHA-256 file before
running it; the installer deliberately does not bypass or remove that warning.

To remove the task and executable while preserving logs/configuration,
double-click `Uninstall.cmd`.

## What it contains

The incident has two distinct mechanisms and the guard handles both:

1. Codex Git live-query/repository-watch cancellation keeps producing new
   cleanup work and `taskkill.exe` helpers.
2. PID-only tree cleanup does not reliably converge under heavy churn and PID
   reuse, so the helper backlog can grow faster than it drains.

With `ImmediateTaskkillContainment` enabled, the guard drains each verified
Codex-owned `taskkill.exe` as soon as the polling loop observes it. This
helper-only fast path does not authorize Git termination. During a verified
multi-helper or rolling-birth storm, the guard can additionally stop only Git
processes that are direct children of the same affected Codex root. Git launched
through a terminal/app-server descendant is excluded so ordinary user `commit`,
`push`, `gc`, and `repack` operations are not targeted.

## Safety boundary

The runtime does **not** invoke PowerShell, WMI, `taskkill.exe`, or recursive
process-tree traversal. It uses Toolhelp snapshots and Win32 process handles.

Before every termination it verifies:

- PID and process creation time, rejecting stale/reused PIDs;
- full executable image path and image name;
- a bounded, cycle-checked parent chain;
- a root `ChatGPT.exe` under `\\WindowsApps\\OpenAI.Codex_*`;
- parent creation times older than their children.

Cleanup has hard ancestry, attempt-count, iteration-time, and history bounds.
It never targets `conhost.exe`. The default configuration uses a 50 ms idle
target period, starts in a 25 ms hot period, and remains hot for ten seconds
after observing a helper or completing storm containment. It removes a single
verified helper without waiting for a count threshold. Two live helpers or four
births in three seconds still define the stronger producer-storm boundary. It
does **not** close Codex. An opt-in persistent-storm fail-safe is additionally
gated by the severe residual threshold and can close only verified Codex roots
that still own those helpers in the final fresh snapshot.

The target period includes scan time: the guard delays only for the unused part
of the period and never overlaps scans. Batch containment reuses one fresh
process catalog instead of taking one system-wide snapshot per target; every
target is still reopened and identity-checked on its own handle immediately
before termination.

Upgrading through `Install.cmd` preserves custom configuration. Unchanged stock
v0.1.0 and v0.1.1 configurations migrate automatically to the v0.1.2 adaptive
immediate-containment defaults. A custom legacy configuration keeps storm-only
semantics unless `ImmediateTaskkillContainment` is explicitly enabled.

## Status and configuration

- Configuration: `%LOCALAPPDATA%\\CodexProcessGuard\\guardsettings.json`
- Current state: `%LOCALAPPDATA%\\CodexProcessGuard\\state.json`
- JSONL logs: `%LOCALAPPDATA%\\CodexProcessGuard\\logs`
- Installed executable: `%LOCALAPPDATA%\\CodexProcessGuard\\app`

The default configuration is in
[`config/guardsettings.json`](config/guardsettings.json). Set
`ImmediateTaskkillContainment` to `false` to restore storm-only helper cleanup.
Set `StopCodexOnPersistentStorm` to `true` only if you explicitly prefer closing
an unrecoverable Codex root over repeated bounded drain cycles.

## Command line

```text
CodexProcessGuard.exe run [--config PATH]
CodexProcessGuard.exe check-once [--config PATH]
CodexProcessGuard.exe contain-once [--config PATH]
```

- `run`: persistent watchdog mode.
- `check-once`: read-only live scan.
- `contain-once`: contains one or more verified helpers when immediate mode is
  enabled; otherwise it requires the live-count threshold.

## Build from source

Building requires the .NET 10 SDK:

```powershell
dotnet build .\CodexProcessGuard.slnx -c Release
dotnet run --project .\tests\CodexProcessGuard.Tests -c Release
.\scripts\package-release.ps1
```

Running `Install.cmd` from a source checkout automatically creates a
self-contained single-file build before installation.

## Compatibility and limitations

- Windows 10/11 x64.
- Current Microsoft Store Codex Desktop package layout using `ChatGPT.exe`.
- The guard intentionally fails closed: if the expected package ancestry cannot
  be verified, it does nothing and logs no termination.
- It does not repair Codex Desktop files or prevent the upstream producer bug;
  it limits the resulting resource storm.

See [`docs/design.md`](docs/design.md) for the design and
[`docs/incident.md`](docs/incident.md) for incident evidence.

## License

MIT. See [`LICENSE`](LICENSE).

CodexProcessGuard

CodexProcessGuard Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

CodexProcessGuard

CodexProcessGuard Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README