start
Launch an ordinary finite local workload as a durable detached process job, then release the assigning Codex turn instead of monitoring it. Use proactively for downloads, builds, test suites, evaluations, benchmarks, inference/model A/B runs, data jobs, and repairs whose underlying work may exceed 60 seconds or has uncertain duration. The user-visible parent must launch the job directly; never delegate local process execution or monitoring to a subagent.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 1.6k
- Forks
- 491
01 前言 Front Matter
- name
- start
- description
- Launch an ordinary finite local workload as a durable detached process job, then release the assigning Codex turn instead of monitoring it. Use proactively for downloads, builds, test suites, evaluations, benchmarks, inference/model A/B runs, data jobs, and repairs whose underlying work may exceed 60 seconds or has uncertain duration. The user-visible parent must launch the job directly; never delegate local process execution or monitoring to a subagent.
02 资源文件 1
- 参考文档agents/openai.yaml195 B
03 SKILL.md 正文
Start Process Job
Resolve <plugin-root> as two directories above this SKILL.md.
Never search memory for CPJ work; use validated CPJ state.
The user-visible parent owns every CPJ launch and completion. Never delegate local process execution, launch, waiting, monitoring, or CPJ ownership to a spawned subagent. A subagent can analyze independent material only.
Launch exactly once
Prefer direct argv:
node "<plugin-root>/scripts/job.mjs" start \
--name "<label>" --cwd "<working-directory>" --json -- \
<command> [args...]
Use fixed non-login Bash only for a validated shell composition:
node "<plugin-root>/scripts/job.mjs" start \
--name "<label>" --cwd "<working-directory>" --shell --json -- \
'<single finite foreground command>'
All controller options, including --json, MUST precede --; that separator
ends controller parsing. Shell mode requires exactly one command string after
it. Never use eval.
CPJ writes private durable state under
${CODEX_HOME:-$HOME/.codex}/process-jobs. Before the first controller call,
use the host permission context instead of probing the filesystem. If that
directory is not writable in the current sandbox, request
sandbox_permissions: "require_escalated" on the first call with a narrow
justification and, when supported, prefix
["node", "<plugin-root>/scripts/job.mjs"]. Do not waste a call on a
predictable EPERM, weaken the sandbox, or edit Codex configuration.
Route and compose
Use CPJ when the user asks to detach/background work, or when a finite local workload may exceed about 60 seconds, has uncertain duration, should survive a client exit, or merits later lightweight status checks.
Classify the underlying workload from context, not its executable name. A qualifying script, download, inference runner, or wrapper uses its original foreground payload through CPJ. Honor an explicit user request to keep work in the foreground.
Exclude quick commands, interactive stdin, servers/watchers, intentional daemons, remote/external services, and fire-and-exit launchers. The tracked process must remain in the foreground until the real workload ends.
Task-specific skills own command construction, preflight checks, arguments, and correctness gates. CPJ owns execution lifecycle for qualifying finite local workloads. Preserve a validated foreground argv or shell string. If a workflow emits a detached launcher, do not pass that launcher through CPJ unchanged: prefer its foreground payload, or a supported mode that remains alive until the workload finishes and propagates its terminal status. Otherwise leave it with its external lifecycle owner.
Required choices
- Require a concrete command and cwd; never invent consequential arguments.
- Default to direct argv. Use
--shellfor Bash features and--posix-shonly for intentionally portable POSIX syntax. - Add
--criticalfor repair, firmware, migration, destructive conversion, or any operation whose interruption could worsen state. - Add
--goal-modeonly when this command belongs to an explicitly active Codex Goal. If unclear andget_goalexists, check once; never inspect private Goal storage or infer Goal mode from repeated turns. - Optional controller flags before
--:--no-notify,--notify-user,--no-notify-user, and--json.
Detached work receives no interactive stdin. Resolve passwords, confirmations,
sudo, or Polkit in the foreground first and prefer non-interactive checks such
as sudo -n. --shell requires /bin/bash and must remain compatible with
macOS Bash 3.2. Never put secrets in argv or tracked logs.
For storage repair, preserve the evidenced target device, mount state, and flags. Never infer a device node from its name.
Hard turn boundary
Treat a successful controller return as a hard launch-turn release boundary.
Do not read the status skill or call status, tail, result, --wait,
write_stdin, sleep, ps, or another process probe in the launch turn.
Result-dependent work resumes through completion delivery, a later
user-initiated turn, or a later automatic continuation of an explicitly active
Goal. If the same user request includes independent work, continue only that
independent work.
This boundary has no same-turn wait exception. A request to report the final result when it finishes is an eventual-delivery request, not permission to keep the launch turn open. If the user explicitly requires foreground execution in the same turn, do not use CPJ for that command. State the tradeoff and run the foreground command only with the user's approval. Never substitute polling.
Report and stop
Name this workflow Codex Process Jobs, never a detached-job skill or workflow. Before launch, use at most one short sentence: say that Codex Process Jobs will run it in the background and hand back immediately. Do not narrate procedure, payload, argv, cwd, controller mechanics, metadata, or validation.
After success, use no more than two short sentences: identify the background job ID, then say that a completion notification and any requested summary should appear when it finishes; status is available on request. If delivery is unavailable or disabled, say completion is recorded and status/result is available. Never promise an immediate wake.
For --goal-mode, say the job is durably tracked under the Goal and will be
picked up by completion delivery or Goal continuation. Automatic
continuation is not permission to monitor: do independent work or apply the host
Goal blocked audit.
A job is machine-scoped and survives Codex App, IDE, or CLI exit. Never add
session-exit cleanup. Critical jobs later require explicit approval and
$cancel --force.
04 同仓库更多 Skills
worktable-review-with-annotations
Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.
worktable-find-and-synthesize-context
Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.
worktable-create-or-update-docs
Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.
worktable-create-or-manage-records
Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.
worktable-create-or-manage-interactive-html
Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.
worktable-collaborate-threads
Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.