Open-source community plugin
Codex Process Jobs
Detach the build. Keep the conversation moving.
A long local build can turn the active Codex thread into a progress monitor, narrating small checkpoints instead of returning control. CPJ launches ordinary macOS or Linux commands as durable detached background jobs—CMake builds, long test suites, inference A/B runs, data processing, and repair utilities that should not monopolize an active Codex turn.
Job state is durable. Automatic conversational completion is best-effort and depends on consent-gated hooks and the active Codex client.
- Hosts
- macOS and Linux
- Runtime
- Node.js 18+
- Clients
- Codex App, CLI, VS Code
- License
- Apache-2.0
Before and after
Why detach the process?
Without a detached process harness, Codex can spend a sequence of turns polling a build and narrating small progress changes. With CPJ, the assigning turn registers the ordinary OS process and returns.
The screenshots below show the behavior directly. The “before” image is a real CUDA build; the “after” image is a harmless synthetic CMake-style process used for a reproducible test.
Observed workflows · six frames
Inspect the handoff at full resolution.
Frame 01 shows the foreground polling behavior without CPJ. Frames 02–05 show detached launch and completion behavior with CPJ across macOS, Linux, and VS Code. The final marketplace frame is where to install it.
These are actual captures from two demonstrations, not one stitched sequence. The Linux and VS Code frames show a separate failed workload returning honestly with exit code 3.
On a pointer device, move across the selected frame for a 2.5× inspection lens. Open the full-resolution viewer on any device to read the original pixels.
What it does
A small lifecycle layer around an ordinary process.
- Tracks process identity, status, timestamps, exit status, and bounded stdout/stderr under the user's Codex home.
- Provides explicit status, bounded result retrieval, and process-group cancellation.
- Allows the assigning Codex turn to end while the finite local command continues.
- Uses sanitized completion notices containing validated terminal metadata—not process output.
Jobs are machine-scoped and survive Codex App, IDE, or CLI exit. CPJ is not a hosted execution service, daemon supervisor, or substitute for reviewing a command before running it.
Usage and token cost
A quality-of-life tool.
CPJ is intended to release the conversation while an ordinary local process runs. It does not promise token savings for every workload. The detached OS process itself consumes no model tokens; Codex usage comes from the launch, optional status requests, and completion or result turns.
The practical target is roughly token-neutral for comparable work, with savings when CPJ replaces repeated polling. A short command or a foreground process that would block once and return can cost slightly more through CPJ.
| Situation | Likely relative usage | Why |
|---|---|---|
| Codex would repeatedly poll and narrate progress | Lower | One detached launch and one completion can replace several status turns. |
| Several compatible jobs finish together | Lower or roughly neutral | Completion batching amortizes one sanitized turn across multiple jobs. |
| Foreground execution would block once and return without polling | Slightly higher | CPJ adds launch instructions, durable bookkeeping, and a completion turn. |
| A short command did not need detachment | Higher | Fixed CPJ overhead provides little benefit; run the command normally. |
Completion mode is report |
Lowest CPJ overhead | Codex reports terminal state without inspecting saved output. |
Completion mode is inspect, or proactive auto applies |
Higher than report |
Codex reads bounded output and interprets it. Compare this with a foreground workflow that also inspects the result. |
| The user repeatedly requests status | Higher | Each conversational status check still consumes an ordinary model turn. |
The job uses --no-notify and is retrieved later on demand |
Minimal automatic overhead | CPJ does not generate an automatic completion turn. |
| An active Goal already produces repeated continuations | Workload-dependent | Goal continuation behavior can dominate CPJ's own cost. |
report. This is a durable completion preference, not an installation flag; it reports
terminal state without automatically inspecting saved output.
Install
Install directly in Codex.
Open Codex Process Jobs in the Codex Plugins directory and choose Install.