Codex Speedup Proof

A Codex skill that finds a software performance hotspot, proposes one focused optimization, waits for explicit approval, and then proves whether the approved change worked with repeatable before-and-after benchmarks.

Unlike a static complexity report, Speedup Proof does not claim that code is faster because it looks better. It measures the same realistic workload before and after, runs correctness checks, accounts for benchmark noise, and returns one honest verdict: PROVEN, INCONCLUSIVE, or REGRESSION.

What it does

• Finds and ranks likely performance hotspots
• Shows the exact files, transformation, benchmark, tests, and risk before editing
• Requires explicit user approval for the displayed proposal
• Creates or reuses a representative benchmark
• Captures median, p95, range, and variability
• Applies one attributable optimization at a time
• Preserves outputs, ordering, errors, APIs, permissions, and side effects
• Runs tests, typechecks, and builds
• Rejects noisy, slower, or behavior-breaking changes
• Creates a Markdown report that opens directly in Codex and renders on GitHub
• Saves machine-readable JSON evidence for reproduction

Installation

npx --yes codex-speedup-proof@latest

This installs the skill into:

~/.codex/skills/speedup-proof

Restart Codex after installation.

Usage

Find, optimize, and prove a safe speedup:

Use $speedup-proof to find the slowest safe hotspot in this codebase, propose one optimization, and wait for my approval before changing files. After approval, run the relevant tests and prove the result with a before-and-after benchmark.

Analyze without changing code:

Use $speedup-proof in audit mode to rank measurable performance opportunities without modifying files.

Investigate a regression:

Use $speedup-proof in regression mode to compare this branch with main using the same workload and identify what became slower.

Approval gate

Calling $speedup-proof authorizes read-only inspection only. Before changing project files, creating a benchmark harness, installing dependencies, or generating artifacts, the skill must show:

1. The hotspot and supporting evidence
2. Every file it plans to change or create
3. The exact transformation
4. Behavior that must remain identical
5. The benchmark and test plan
6. The main risk

It then stops and asks for explicit approval. Approval covers only that one proposal; a different or additional optimization requires a new approval.

Evidence rules

A result is PROVEN only when:

1. Correctness checks pass
2. Before and after use the same representative workload
3. Measurements are stable
4. The improvement exceeds the observed noise threshold

Otherwise the skill reports INCONCLUSIVE or REGRESSION. It never invents a speedup percentage from a complexity estimate or a single run.

Output

outputs/speedup-proof-report.md
outputs/speedup-proof-results.json

The Markdown report includes the verdict, before/after table, benchmark protocol, complexity estimate, changed files, correctness evidence, reproduction commands, limitations, and residual risks.

Manual installation

git clone https://github.com/Kappaemme-git/codex-speedup-proof.git
mkdir -p ~/.codex/skills
cp -R codex-speedup-proof/speedup-proof ~/.codex/skills/speedup-proof

Restart Codex after installation.

License

MIT