SDOAT-sKILL-Codex

Technical reference for the autonomous Codex task lifecycle skill and CLI.

What this project provides

• npm-distributed CLI: sdoat-codex
• Codex skill bundle: skill/sdoat-codex
• Deterministic lifecycle commands:
  • install-skill
  • preflight
  • task-start
  • task-merge-clean
  • resume

Prerequisites

• macOS
• git available in PATH
• Node.js 20+ (tested with Node 24 runtime)
• A valid Codex home:
  • CODEX_HOME if set, else ~/.codex
  • Must exist and contain at least one of:
    • sessions/
    • archived_sessions/
    • worktrees/

Install dependencies and build

npm install
npm run build

Install the skill bundle

npx sdoat-skill-codex install-skill

Optional overwrite:

npx sdoat-skill-codex install-skill --force

Installed destination:

• $CODEX_HOME/skills/sdoat-codex (fallback base is ~/.codex)

Quick start

1) Start a task worktree

npx sdoat-skill-codex task-start \
  --repo-root /abs/path/to/repo \
  --parent-branch dev \
  --task-description "implement deterministic cleanup"

Optional flags:

• --task-branch codex/<kebab>
• --thread-id <id>
• --config /abs/path/config.json
• --log-file /abs/path/run.log
• --json

2) Merge, push, and cleanup

npx sdoat-skill-codex task-merge-clean \
  --worktree-path /abs/path/to/worktree \
  --test-command "npm test"

Alternative metadata input:

npx sdoat-skill-codex task-merge-clean \
  --meta-file /abs/path/to/worktree/.codex-task.json

Optional flags:

• --thread-id <id>
• --ui-hook-cmd "codex-app archive --thread {thread_id}"
• --config /abs/path/config.json
• --log-file /abs/path/run.log
• --json

3) Resume interrupted cleanup

npx sdoat-skill-codex resume --run-id <run_id>

Or:

npx sdoat-skill-codex resume --run-id <run_id> --run-file /abs/path/run.json

CLI command reference

preflight

Validates Codex home and optional repo path.

npx sdoat-skill-codex preflight --repo-root /abs/path/to/repo

task-start

• Validates parent and task branch policy.
• Fetches remote (origin by default).
• Checks out parent safely.
• Fast-forward syncs parent from remote if present.
• Creates task branch and dedicated worktree.
• Writes .codex-task.json.

task-merge-clean

• Requires --worktree-path or --meta-file.
• Auto-commits dirty task branch checkpoint.
• Performs merge with conflict matrix.
• Runs configured tests.
• Pushes parent branch.
• Runs merge gate before destructive cleanup.
• Performs git cleanup, session archive/purge, UI hook best-effort.

resume

• Reopens previous run state.
• Re-validates merge gate before destructive continuation.
• Continues idempotently from unfinished phase.

Configuration file (JSON)

Use --config /abs/path/config.json.

{
  "version": 1,
  "git": {
    "remote": "origin",
    "protected_branches": ["main", "master"]
  },
  "tests": {
    "commands": ["npm test"]
  },
  "conflicts": {
    "policy": "path-matrix"
  },
  "ui_removal": {
    "hook_cmd": null
  }
}

Safety and scope guarantees

• Task branches must match:
  • ^codex/[a-z0-9]+(-[a-z0-9]+){0,2}$
• Protected branches are blocked for destructive operations:
  • main, master
• Worktree cleanup is restricted to $CODEX_HOME/worktrees.
• Session purge scans JSONL lines and matches only:
  • type == "session_meta" and payload.id == thread_id
• Cleanup runs only after:
  • merge success
  • push success
  • merge-gate success
• Run state and locking:
  • lock: $CODEX_HOME/tmp/locks/<hash>.lock
  • run state: $CODEX_HOME/tmp/self_destruction_runs/<run_id>.json

Exit codes

• 0: success
• 2: invalid arguments
• 3: preflight failure
• 4: merge gate failure
• 5: merge or push failure
• 6: cleanup interrupted
• 7: UI removal best-effort only

Development

npm run typecheck
npm test
npm run pack:dry

If npm cache/permissions break packaging locally, fix ownership of ~/.npm and rerun.