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

> Discover how the OpenAI Codex plugin generates unique collision-resistant job IDs using timestamps and random suffixes. Learn about the generateJobId function for background task tracking.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: internals
- Published: 2026-07-10

---

**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

```javascript
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:

```javascript
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:

```javascript
// 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:

```javascript
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.