codex-patches

Use this when updating the codex submodule or when patch files in codex-patches/ need to be added, regenerated, or repaired.

⭐21stars🔀0forks📁View on GitHub🕐Updated Dec 19, 2025

When & Why to Use This Skill

This Claude skill provides a robust framework for managing Git submodules and patch-based development workflows. It streamlines the process of updating external dependencies, applying custom code modifications, and repairing broken diffs, ensuring high patch hygiene and codebase stability for complex software projects.

Use Cases

  • Submodule Synchronization: Efficiently update the codex submodule to specific commits and re-apply local patches to maintain custom functionality.
  • Patch Conflict Resolution: Systematically repair broken patches after upstream changes by rehydrating clean versions and manually resolving diff conflicts.
  • Maintenance of Stable Diffs: Regenerate patches against upstream trees to minimize context drift and ensure patches remain focused on single features.
  • Automated Quality Assurance: Execute 'Quick Smoke Tests' using tools like Turbo lint and typecheck immediately after patch application to verify code integrity.
namecodex-patches
descriptionUse this when updating the codex submodule or when patch files in codex-patches/ need to be added, regenerated, or repaired.

Codex Patch Workflow

Use this skill whenever you touch the codex submodule (codex/) or the patch series in codex-patches/.

Apply Patches After Submodule Update

  1. Update the codex submodule to the target commit:
cd codex
git checkout <commit>
cd ..
  1. Apply our patches:
scripts/apply_codex_patches.sh

If a patch fails, fix only that patch before moving on.

Repairing a Broken Patch

General approach:

  1. Rehydrate codex/ to clean upstream before re‑diffing:
git archive codex-upstream/main | tar -x -C codex
  1. Re‑apply the remaining patches that still work. Fix conflicts manually if needed.
  2. Regenerate the broken patch by diffing the upstream file(s) against our modified version.

Regenerating a Patch (stable diff style)

Prefer diffs against the upstream tree to reduce context drift. For the full example script, see references/regen_patch_example.md.

Patch Hygiene

  • Keep each patch focused on a single feature or concern.
  • Avoid bundling unrelated changes into the same patch.
  • Do not include upstream-only changes; patches should be fork-only deltas.

Quick Smoke Test

After applying patches, run:

turbo lint
turbo typecheck