How Job IDs Are Generated and Tracked in the OpenAI Codex Plugin

The OpenAI Codex plugin generates unique job IDs using a base-36 timestamp and random suffix pattern defined in generateJobId, ensuring collision-resistant identifiers for every background task.

The openai/codex-plugin-cc repository manages background operations like code reviews and tasks through a robust job tracking system. Understanding how job IDs are generated and tracked is essential for debugging, monitoring, and extending the plugin's functionality.

The Job ID Generation Algorithm

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

• Prefix: A caller-defined string (e.g., "task", "review") indicating the job category
• Timestamp: Current epoch milliseconds converted to base-36 for compactness
• Random suffix: Six characters of pseudo-random base-36 entropy

Implementation Details

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

This structure produces strings like task-lk3j9c-5f1a2b or review-lyx2q0-9c7d4e. Because Date.now() always increases and the random component adds entropy, collisions are statistically impossible even with millisecond-level concurrency.

Job Creation and Tracking Pipeline

Job IDs are not generated in isolation—they are assigned during job instantiation through the companion job system.

The createCompanionJob Entry Point

In plugins/codex/scripts/codex-companion.mjs, the createCompanionJob function accepts a prefix parameter that determines the job type identifier:

const job = createCompanionJob({
  prefix: "task",                     // Determines ID prefix
  kind: "task",
  title: taskMetadata.title,
  workspaceRoot,
  jobClass: "task",
  summary: taskMetadata.summary,
  write
});
// job.id is generated internally via generateJobId

The Tracked Jobs Wrapper

The createCompanionJob function is further wrapped in plugins/codex/scripts/lib/tracked-jobs.mjs, which handles persistence and state management. This ensures every generated ID is immediately registered in the job tracking system before execution begins.

Practical Usage Examples

Creating a Task Job

When initiating a background task, the prefix propagates through the companion system:

// From codex-companion.mjs task handling
const job = createCompanionJob({
  prefix: "task",
  kind: "task",
  title: "Refactor authentication",
  workspaceRoot: "/path/to/project",
  jobClass: "task",
  summary: "Update login flow",
  write: outputWriter
});

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

Direct Helper Usage

For testing or custom implementations, import the generator directly:

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

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

Summary

• Algorithm: generateJobId in plugins/codex/scripts/lib/state.mjs combines prefixes, base-36 timestamps, and random suffixes
• Format: <prefix>-<base36-timestamp>-<random> (e.g., task-lk3j9c-5f1a2b)
• Collision resistance: Monotonic timestamps plus random entropy prevent ID conflicts
• Integration: createCompanionJob in codex-companion.mjs and tracked-jobs.mjs handle assignment and persistence
• Extensibility: Any job type can specify custom prefixes via the companion job API

Frequently Asked Questions

What file contains the job ID generation logic?

The generateJobId function is implemented in plugins/codex/scripts/lib/state.mjs. This module exports the helper used throughout the codebase to create unique identifiers for background operations.

How does the Codex plugin prevent job ID collisions?

The plugin uses Date.now() converted to base-36 (which always increases) combined with a six-character random suffix from Math.random(). This dual-entropy approach ensures unique IDs even when multiple jobs start in the same millisecond.

Can I customize the prefix for different job types?

Yes. When calling createCompanionJob in plugins/codex/scripts/codex-companion.mjs, pass a prefix parameter (e.g., "task", "review"). This string becomes the first segment of the generated job ID.

Where are generated job IDs stored and tracked?

After generation, job IDs are managed through plugins/codex/scripts/lib/tracked-jobs.mjs, which wraps createCompanionJob to handle persistence, state updates, and lifecycle management of background operations.

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