How the Codex Plugin Detects Verification Commands: tests, lint, and build

The OpenAI Codex plugin detects verification commands by parsing slash command arguments with a regular expression that matches keywords like test, lint, build, verify, or ci, then sets an isVerification flag that triggers automatic execution of those steps.

The openai/codex-plugin-cc repository implements a dynamic system to detect verification commands without hard-coding specific sub-commands. By scanning user arguments with regular expressions in the argument parsing module, the plugin automatically recognizes tests, linting, or build instructions embedded in any Codex slash command.

Argument Parsing and Regex Detection

The detection logic resides in plugins/codex/scripts/lib/args.mjs. This module processes raw command strings through a three-stage pipeline that extracts verification keywords from any position in the argument list.

Normalizing the Input String

First, the parser sanitizes the raw input by stripping the leading /codex: prefix, splitting tokens on whitespace, and expanding quoted sections. This ensures that arguments like "test:unit" or lint are processed as discrete tokens regardless of their position in the command.

Pattern Matching Verification Keywords

Next, the parser applies a case-insensitive regular expression—/\b(test|lint|build|verify|ci)\b/i—to each token. Any matching strings are collected into a verificationCommands array. This regex approach makes the system future-proof; new verification-style commands that follow standard naming conventions are automatically recognized without code modifications.

Setting the Verification Flag

Finally, the parser sets parsed.isVerification = verificationCommands.length > 0. This boolean flag propagates through the job control logic in plugins/codex/scripts/lib/job-control.mjs, signaling that the Codex task should include a verification phase.

From Detection to Execution

When isVerification evaluates to true, the plugin constructs a specialized task payload.

The verification step is sent to the app-server endpoint /turn/start with a kind: "verification" field. The app-server then executes the requested tool—such as npm test, npm run lint, or npm run build—inside the repository's workspace. Results stream back to the client through the standard job-log mechanism, integrating test failures or lint errors directly into the Codex output.

Practical Usage Examples

The flexible parser allows verification commands to appear anywhere in the argument list.

Background Review with Tests

/codex:review --background test

The parser extracts ["review", "--background", "test"]. Since "test" matches the verification regex, isVerification becomes true. The plugin launches a background review job that executes npm test after completing the code review, appending test results to the final report.

Adversarial Review with Linting

/codex:adversarial-review --base main lint

Here, "lint" triggers the verification flag. Following the adversarial review, the plugin runs npm run lint and surfaces any warnings or errors alongside the security analysis.

Core Implementation Files

The verification workflow spans four key modules:

• plugins/codex/scripts/lib/args.mjs – Parses command-line arguments and identifies verification tokens using regex filtering.
• plugins/codex/scripts/lib/process.mjs – Spawns the verification subprocess (e.g., npm test) and manages execution context.
• plugins/codex/scripts/lib/job-control.mjs – Wraps verification steps in the job payload and routes results to the UI.
• plugins/codex/scripts/codex-companion.mjs – Orchestrates the overall task flow, determining when to inject verification phases based on the isVerification flag.

Summary

• The Codex plugin uses regex pattern matching in args.mjs to detect verification keywords dynamically.
• Matching tokens trigger an isVerification flag that modifies the task payload sent to the app-server.
• Verification steps execute with kind: "verification" and return results through the job-log stream.
• The system supports any command matching the regex pattern, including custom scripts like test:unit or ci.

Frequently Asked Questions

What verification keywords does the Codex plugin recognize?

The plugin recognizes test, lint, build, verify, and ci through a case-insensitive regex bound by word boundaries. Any command argument matching these patterns triggers the verification workflow and sets the isVerification flag to true.

Can I use custom verification commands with the Codex plugin?

Yes. Because detection relies on a regex pattern rather than a hard-coded list, any argument matching the pattern /\b(test|lint|build|verify|ci)\b/i will be treated as a verification command. This includes variants like test:unit or build:prod without requiring code changes.

Where does the verification detection logic live in the codebase?

The detection logic is implemented in plugins/codex/scripts/lib/args.mjs, which normalizes input strings and applies the verification regex to populate the verificationCommands array before setting the boolean flag.

How does the plugin execute detected verification commands?

Once detected, the isVerification flag causes plugins/codex/scripts/lib/job-control.mjs to include a verification step in the payload sent to /turn/start. The app-server then spawns the appropriate subprocess via plugins/codex/scripts/lib/process.mjs, capturing output through the standard job-log mechanism.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}