Codex ChangeGuard

• 

  Safer self-service and cleaner evidence for maintainers.

Inspiration

What it does

How we built it

Challenges we ran into

Accomplishments that we're proud of

What we learned

What's next for Codex ChangeGuard

Inspiration

Codex evolves quickly. That is exciting—but when an update changes behavior, users can lose hours trying to answer a deceptively hard question: is the bug in my code, my configuration, the installed Codex build, or the environment around it?

Most support flows begin with symptom matching. A similar Issue or a confident model answer can be useful, but similarity is not proof. We built Codex ChangeGuard to turn update failures into evidence-backed diagnoses and safe, reversible recovery paths—inside Codex itself.

What it does

ChangeGuard is a Codex Plugin with one verified core exposed through a Skill, 19 MCP tools, and a reproducible CLI. It can:

• detect installed Codex instances, versions, surfaces, and environment drift;
• compare the installed Codex desktop app with a downloaded-but-not-installed update package before installation—even when no version-bound patch notes are available—using bounded named-artifact, Electron ASAR, stable-path, and native-module diffs;
• build a redacted local fingerprint from bounded files, hashes, AST signatures, and allowlisted probes;
• map official release evidence and compatible Issue candidates to the local machine without treating community reports as confirmed causes;
• preview an exact repair before mutation;
• apply a repair only inside a proven disposable target, verify the result, and restore the original bytes with hash evidence;
• prepare a structured, duplicate-aware upstream Issue preview when no verified fix exists, while refusing production writes when no trusted adapter is available.

The packaged judge demo performs the complete loop in roughly a tenth of a second: isolate, diagnose, explain, preview, apply, verify, rollback, test model refusal, test an unsafe crash repair, and clean up. All ten steps pass. It also proves that no network path was used, the live Codex profile was not mutated, and the temporary workspace was removed.

How we used Codex

Codex was the primary development and verification environment for the project. We used it to turn the product principles into a specification and ticketed implementation, build the Plugin/Skill/MCP/CLI surfaces, create adversarial fixtures, run boundary and packaging checks, test clean-profile installation, and inspect real platform receipts.

The Plugin is intentionally Codex-native. A user can invoke the guided Skill, call the structured MCP tools from an agent workflow, or run the same core from the CLI for a deterministic judge path. ChangeGuard does not require a separate dashboard to be useful.

How we used GPT-5.6

GPT-5.6 is used where model reasoning is valuable: compiling local facts into testable hypotheses, ranking compatible candidates after hard filters, and drafting an Impact Contract or Recovery hypothesis in language a user can understand.

It is deliberately not the source of truth. GPT-5.6 cannot create a Change-to-Local evidence edge, overwrite a probe result, promote a user report to an official cause, or authorize a repair. Deterministic code and allowlisted probes decide what becomes evidence. The demo includes five adversarial attempts to upgrade model output into evidence; all are refused and the evidence graph hash remains unchanged.

How we built it

The core is written in TypeScript on Node.js. JSON Schema defines stable public contracts. A local evidence graph separates observations, hypotheses, probes, and verdicts. Repair capsules bind the exact target, expected hash, allowed operation, verification plan, and rollback receipt. Security checks refuse symlink escapes, active profiles, protected roots, oversized inputs, unknown operations, and stale authorizations.

Packaging produces a prebuilt Plugin that can be installed and tested without rebuilding on the judge machine. The same demo function backs the CLI, MCP, and Skill surfaces so there is no separate “demo implementation” that can drift from the product.

Challenges we ran into

The hardest challenge was keeping AI assistance useful without allowing it to become evidence. We had to make every trust transition explicit and test the negative path—not just the happy path.

Another challenge was supporting a rapidly moving, multi-surface product across macOS, Windows, Linux, WSL, Desktop, CLI, Plugin, MCP, and browser control. We chose honest capability levels instead of a universal support claim: macOS can reach Full only with real-machine receipts, Windows is currently Preview, and Linux/WSL remain Limited or read-only until equivalent proof exists.

Finally, reversible repair required more than a backup button. We bind previews to hashes, refuse replay and time-of-check/time-of-use drift, verify the repaired state, automatically roll back failed verification, and prove restoration of the original bytes.

Accomplishments that we're proud of

• A working, prebuilt judge path with ten independently visible steps.
• A staged-update comparator that found a real newer local build, four changed named artifacts, four changed stable ASAR paths, and a newly added native module without installing or mutating either app.
• One implementation shared by Skill, MCP, and CLI instead of three demos.
• Model-refusal tests that prove hypotheses cannot silently become evidence.
• Explicit privacy receipts: no network use, no live-profile mutation, bounded disclosure, and deterministic cleanup.
• A repair lifecycle that treats preview, authorization, verification, and rollback as first-class product states.

What we learned

The best AI developer tool is not the one that sounds most certain. It is the one that knows which claims are hypotheses, which are observations, and what must be tested before a user should act.

We also learned that helping maintainers starts before an Issue is filed. A good support tool should redact sensitive data, detect likely duplicates, preserve negative evidence, and generate a reproducible report—reducing noise without hiding unresolved problems.

What's next for Codex ChangeGuard

Next we want to add real-machine Full receipts for Windows, expand the official release-evidence index, and connect the already implemented upstream preview engine to a production adapter with explicit user confirmation and idempotent writes. We also plan to use verified follow-up receipts to tell users when a previous workaround is no longer needed and when an upgrade is safe to retry.

Built With

• ai
• codex
• developer-tools
• github
• gpt
• json
• mcp
• node.js
• openai
• typescript