Codex Plugin Job ID Generation: How OpenAI's Codex Creates Unique Identifiers

The Codex plugin generates unique job IDs by concatenating a semantic prefix with a base-36 timestamp and a six-character random suffix, ensuring collision-resistant identifiers for every background operation.

The openai/codex-plugin-cc repository manages background operations like code reviews and tasks through a centralized job system. Codex plugin job ID generation relies on a deterministic helper function that combines temporal data with random entropy to produce distinct identifiers. This architecture ensures that every companion job receives a unique ID that encodes its creation time and operation type.

The generateJobId Implementation in state.mjs

The core logic resides in plugins/codex/scripts/lib/state.mjs, where the generateJobId function constructs identifiers using three distinct components:

export function generateJobId(prefix = "job") {
  const random = Math.random().toString(36).slice(2, 8);
  return `${prefix}-${Date.now().toString(36)}-${random}`;
}

Base-36 Timestamp Encoding

The function converts the current epoch milliseconds (Date.now()) to base-36 notation, producing a compact temporal string. This conversion reduces the typical 13-digit millisecond timestamp to a shorter alphanumeric representation while maintaining chronological sortability.

Random Entropy Component

To prevent collisions when multiple jobs initiate within the same millisecond, the algorithm appends six characters of pseudo-random base-36 data. The expression Math.random().toString(36).slice(2, 8) extracts characters from index 2 to 8, providing 36^6 possible combinations for additional uniqueness.

Job Creation Workflow

Job IDs materialize during the companion job instantiation process, specifically within the createCompanionJob function hierarchy.

The createCompanionJob Function

In plugins/codex/scripts/codex-companion.mjs (lines 66-78), the system calls createCompanionJob with a specified prefix that indicates the operation type:

const job = createCompanionJob({
  prefix: "task",
  kind: "task",
  title: taskMetadata.title,
  workspaceRoot,
  jobClass: "task",
  summary: taskMetadata.summary,
  write
});

The createCompanionJob wrapper in plugins/codex/scripts/lib/tracked-jobs.mjs (lines 67-73) invokes generateJobId internally, assigning the resulting ID to job.id before persisting the record.

Prefix Conventions and Job Types

The prefix parameter categorizes IDs by operation type:

• "task" – Background task executions
• "review" – Code review jobs
• "job" – Generic fallback prefix

This semantic tagging produces identifiable strings like task-lk3j9c-5f1a2b or review-lyx2q0-9c7d4e.

Collision Resistance and ID Structure

The final identifier follows the pattern <prefix>-<base36-timestamp>-<random-suffix>. Because Date.now() monotonically increases and the random suffix adds entropy, the probability of collision remains negligible even under high-concurrency scenarios where multiple jobs start simultaneously.

Practical Usage Examples

Direct Helper Invocation

For testing or custom implementations, import the generator directly from the state module:

import { generateJobId } from "./lib/state.mjs";

console.log(generateJobId("review"));
// Output: "review-lyx2q0-9c7d4e"

Accessing Job IDs in Production

When initiating jobs through the companion interface, the generated ID becomes available immediately on the returned job object:

const job = createCompanionJob({
  prefix: "task",
  kind: "task",
  title: "Refactor authentication",
  workspaceRoot: "/path/to/project",
  jobClass: "task",
  summary: "Update login flow",
  write: true
});

console.log(`Started job ${job.id}`);
// Output: "Started job task-lk3j9c-5f1a2b"

Summary

• The generateJobId function in plugins/codex/scripts/lib/state.mjs creates unique identifiers using base-36 timestamps and random suffixes.
• Job IDs follow the format <prefix>-<base36-timestamp>-<random-suffix>, combining semantic prefixes with temporal and entropy components.
• The createCompanionJob function in codex-companion.mjs and tracked-jobs.mjs orchestrates ID generation during job instantiation.
• Prefixes like "task" and "review" categorize jobs while the timestamp ensures chronological uniqueness.

Frequently Asked Questions

How does the Codex plugin prevent job ID collisions?

The algorithm combines a millisecond-precision timestamp (Date.now()) with a six-character random base-36 suffix. Because the timestamp increases monotonically and the random component provides 36^6 possible values, collisions are statistically impossible under normal operating conditions.

What file contains the generateJobId function?

The function is defined in plugins/codex/scripts/lib/state.mjs at lines 24-27. This module serves as the central utility for state management and identifier generation throughout the plugin.

Can I customize the job ID prefix?

Yes. When calling createCompanionJob, pass a custom prefix property in the configuration object. The default value is "job", but the system uses "task" and "review" for specific operation types, and you can specify any string to categorize your jobs.

Where is the job ID actually assigned to the job object?

The assignment occurs in plugins/codex/scripts/lib/tracked-jobs.mjs within the createCompanionJob wrapper function (lines 67-73). This function calls generateJobId with the provided prefix and attaches the resulting string to the job record's id property before returning.

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