DiffCI

Codex

Give Codex a measured CI validation step.

Published September 21, 2026 · Updated September 25, 2026 · By Aditya Kale, primary maintainer

DiffCI lets Codex explain the tests a change can reach, fall back when the evidence is incomplete, and compare the selected path with the full test command when both can run safely.

npx "@diffci.com/diffci@latest" init
npx "@diffci.com/diffci@latest" verify --changed --json

Install the repository policy

Run init from the repository root. It creates an AGENTS.md instruction that tells Codex to use DiffCI as a validation lens before PR-ready answers, while preserving the repository's required commands.

On Windows PowerShell, quote the scoped package if the shell parses the @ token:

npx '@diffci.com/diffci@latest' check

Existing instruction files are preserved. Review the generated policy before committing it.

What Codex should report

A useful completion answer names the DiffCI verdict, fallback reason, selected tests, commands that actually ran, and the report path. A selection count alone is not runtime evidence.

  • Paired commands passed: report measured timings with the stated checkout and command scope.
  • Full-run fallback: report that the change could not be narrowed safely.
  • REFUSED or ERROR: continue with the repository's normal test commands.

Test commands may create generated files. Use observe --no-send when the task calls for analysis without execution.

Optional MCP connection

Codex clients with stdio MCP support can run npx -p "@diffci.com/diffci@latest" diffci-mcp and call diffci_verify_changed for uncommitted work or diffci_verify for a clean commit range. Continue only when the structured receipt reports safe_to_continue: true.

If verification is blocked, preserve the diagnostic and run the repository's normal validation commands.

Verify the Codex setup

  • Confirm the applicable AGENTS.md includes the DiffCI instruction and is not shadowed by a more specific instruction file.
  • Run one direct check from the repository root and verify that Codex reports the verdict, executed commands, fallback evidence, and output path.
  • On PowerShell, keep the scoped package name quoted; on every platform, retain the repository's required validation after a refusal or error.