Codex Elevated Windows Shell

Run Windows administrator commands from Codex without losing track of what happened.

codex-elevated-windows-shell is a Codex plugin that adds the elevated-shell skill. It helps Codex check whether PowerShell is elevated, use Windows Sudo when available, and capture administrator-command output into clear log/status files.

It is built for the awkward but common Windows case where sudo opens a separate elevated window after UAC approval. Instead of pretending that output will stream back perfectly, the plugin records proof, progress, and exit codes in files Codex can read.

What You Get

• Check whether the current shell is elevated.
• Verify Windows Sudo and UAC behavior.
• Run elevated PowerShell commands through sudo --new-window.
• Track long-running admin tasks with timestamped .log and .done files.
• Avoid Codex hanging while an installer or package manager runs in another window.
• Keep privilege escalation explicit, user-approved, and auditable.

Quick Start

Ask Codex to use the skill:

Use $elevated-shell to check whether this session can run elevated PowerShell.

Run a quick elevation check manually:

.\skills\elevated-shell\scripts\Test-Elevation.ps1

Run an elevated command with logging:

.\skills\elevated-shell\scripts\Invoke-ElevatedLoggedCommand.ps1 `
  -LogPrefix elevated-command `
  -CommandText 'whoami /groups' `
  -InitialWaitSeconds 10 `
  -TailLines 80 `
  -AsJson

For complex commands passed through powershell.exe -File, use -CommandBase64 instead of -CommandText.

Example: Chocolatey Upgrade

Chocolatey upgrades are a good example because they may require administrator rights and can run for several minutes.

Use:

choco upgrade all -y --no-progress

Not:

choco upgrade --all

With the launcher:

.\skills\elevated-shell\scripts\Invoke-ElevatedLoggedCommand.ps1 `
  -LogPrefix choco-upgrade-all `
  -CommandText 'choco upgrade all -y --no-progress' `
  -InitialWaitSeconds 15 `
  -TailLines 120 `
  -AsJson

The command creates files like:

choco-upgrade-all-YYYYMMDD-HHMMSS.log
choco-upgrade-all-YYYYMMDD-HHMMSS.done

The log shows progress. The .done file contains the final exit code.

How It Works

The plugin has two small PowerShell helpers.

Test-Elevation.ps1

Checks:

• current Windows user context;
• whether the token is in the Administrators role;
• whether the process is Medium Mandatory Level or High Mandatory Level.

High integrity means the current process is elevated. Medium integrity means it is not.

Invoke-ElevatedLoggedCommand.ps1

Starts an elevated command through Windows Sudo and records what happens.

The flow is:

1. Create timestamped .log and .done paths.
2. Start sudo --new-window.
3. Let UAC ask the user for approval.
4. Run the command in elevated PowerShell.
5. Write output to the .log file.
6. Write the final exit code to the .done file.
7. Let Codex read the files instead of waiting blindly on an elevated window.

This is the core design idea: files are the synchronization layer between Codex and Windows UAC.

Reading Results

Successful elevation is proven by log lines like:

{
  "IsAdmin": true,
  "Integrity": "Mandatory Label\\High Mandatory Level ..."
}

Status meanings:

• .log exists and .done does not: command is running, waiting for UAC, or stopped before completion.
• .done contains 0: command completed successfully.
• .done contains a nonzero value: command finished with an error; inspect the log.
• neither file exists: the elevated process probably did not start.

Tail a log:

Get-Content -Tail 120 -LiteralPath .\some-command.log

Installation In Codex

This repository is a Codex plugin.

Typical local layout:

C:\Users\User\plugins\elevated-shell

Personal marketplace entry:

C:\Users\User\.agents\plugins\marketplace.json

After registration, the plugin appears in:

Plugin -> Personal

Repository Layout

.codex-plugin/
  plugin.json
skills/
  elevated-shell/
    SKILL.md
    agents/
      openai.yaml
    scripts/
      Test-Elevation.ps1
      Invoke-ElevatedLoggedCommand.ps1
README.md
.gitignore
LICENSE

Tested Environment

The plugin was developed and tested on a non-personalized Windows environment with:

Operating system: Windows 10 Pro
Windows version: 2009
OS build: 26100
Architecture: 64-bit
PowerShell: Windows PowerShell 5.1.26100.8737
Windows Sudo: enabled, Force New Window mode
Chocolatey: 2.7.3
Git: 2.55.0.windows.2
GitHub CLI: 2.96.0
UAC EnableLUA: 1
UAC PromptOnSecureDesktop: 0
UAC ConsentPromptBehaviorAdmin: 0

The most important tested behavior is Windows Sudo Force New Window mode. Other sudo modes may expose output differently, but the log/done pattern remains the safest default.

Safety

This plugin does not bypass UAC. It does not collect credentials. It does not silently escalate privileges.

It only helps Codex:

• detect the current privilege level;
• request an elevated command through normal Windows Sudo/UAC;
• record the result in files;
• report what actually happened.

Troubleshooting

Sudo is disabled

Enable Windows Sudo in Windows Developer Settings, then run:

sudo --help
sudo config

UAC appeared but no log was written

The prompt may not have been accepted, or the command may have failed before the script body started. Retry with a very small probe command first.

Log exists but .done does not

The command may still be running or waiting for another installer window. Tail the log and check for visible installer prompts.

Chocolatey fails with "Package name is required"

Use:

choco upgrade all

not:

choco upgrade --all

Development Checks

Validate the skill:

py -3 C:\Users\User\.codex\skills\.system\skill-creator\scripts\quick_validate.py .\skills\elevated-shell

Validate the plugin:

py -3 C:\Users\User\.codex\skills\.system\plugin-creator\scripts\validate_plugin.py .

License

MIT