Workflow durability for Codex CLI.
Resume cleanly. Plan with evidence. Execute without losing the thread.

The Problem · How It Works · Demo · Quick Start · Which Skill · Benchmarks · CLI

Codex is strong at focused execution. It weakens when the task outlives a single session.

Without Quick Codex                    With Quick Codex
─────────────────────────────          ─────────────────────────────────────
Turn 1  clarify the task               Turn 1  create run artifact: goal,
Turn 2  start researching                      affected area, risks, plan
Turn 3  begin implementation           Turn 2  execute one verified wave
Turn 6  context crowded, session       Turn 3  checkpoint → deliberate
        compacts at wrong moment               carry-forward handoff
Turn 7  next step unclear,             Turn 6  resume from file state,
        thread is lost                         not from stale chat memory

The core pain points Quick Codex addresses:

Quick Codex installs two skills into Codex's skill directory:

YOUR TASK
  │
  ├─ qc-flow   ──→  discuss → affected area → research → gray area register
  │                 → delivery roadmap → verified plan → execute waves
  │                 → checkpoint with carry-forward handoff
  │                        │
  │                        ▼ (when scope is fully understood)
  └─ qc-lock   ──→  preflight → plan → lock → execute → verify → fix
                    (strict loop, no drift, file-state first)

State lives in files, not chat:

.quick-codex-flow/
  STATE.md              ← active run pointer
  <run>.md              ← full artifact: goal, plan, waves, ledger, handoff
  PROJECT-ROADMAP.md    ← milestone and cross-run dependency state
  BACKLOG.md            ← parked work, deferred decisions, future seeds

Six continuity layers keep work resumable across sessions:

Recover the active run, next gate, and exact prompt to paste — from local file state, not chat memory.

Clarify → surface affected area → clear gray areas → build a delivery roadmap with a verified phase plan.

Preflight → lock → execute one step → verify output → done. No drift, no guessing.

npx quick-codex install

Installs qc-flow and qc-lock into ~/.agents/skills. Restart Codex.

For non-trivial tasks (unclear scope, multi-turn, research needed):

Use $qc-flow for this task: <your task here>

For tightly scoped execution (known scope, strict verification needed):

Use $qc-lock for this task: <your task here>

quick-codex init --dir ./my-project

Creates STATE.md, PROJECT-ROADMAP.md, BACKLOG.md, and a sample run artifact.

quick-codex status --dir ./my-project
quick-codex resume --dir ./my-project

# Local checkout via npx
npx --yes ./quick-codex install

# Direct CLI
node bin/quick-codex.js install

# Dev symlinks
mkdir -p ~/.agents/skills
ln -s /path/to/repo/qc-flow ~/.agents/skills/qc-flow
ln -s /path/to/repo/qc-lock ~/.agents/skills/qc-lock

When to switch from qc-flow to qc-lock:

• Clarify, affected-area discussion, research, and plan-check are done
• Scope is narrow enough for locked step-by-step execution
• No active gray-area triggers remain

Quick Codex is judged on workflow reliability, not feature count. Each proof scenario runs the same task with and without Quick Codex.

Full benchmark index: BENCHMARKS.md

Quick Codex ships openai.yaml agent configs so Codex can discover and invoke the skills natively:

# qc-flow/agents/openai.yaml
interface:
  display_name: "Quick Codex Flow"
  short_description: "Clarify, research, plan, then execute"
  default_prompt: "Use $qc-flow to clarify this task, verify context sufficiency,
    build a checked phase-and-wave plan, then execute it sequentially."
policy:
  allow_implicit_invocation: true

Skills are discovered from ~/.agents/skills (canonical) or ~/.codex/skills (legacy).

Quick Codex works standalone. It becomes sharper when paired with Experience Engine.

Division of responsibility:

Sync hook warnings into an active run:

# From recent hook text
quick-codex capture-hooks --dir ./my-project --input ./hooks.txt

# From a concrete next tool action
quick-codex sync-experience --dir ./my-project --tool Write \
  --tool-input '{"file_path":"src/app.ts"}'

Active warnings survive resume and compaction via Experience Snapshot in the run artifact. See CONTINUITY-CONTRACT.md for the full field ownership spec.

# Install / upgrade / uninstall
quick-codex install [--copy] [--target <dir>]
quick-codex upgrade [--copy] [--target <dir>]
quick-codex uninstall [--target <dir>] [--dir <project-dir>]

# Project setup
quick-codex init [--dir <project-dir>] [--force]
quick-codex doctor [--target <dir>]

# Active run — status and resume
quick-codex status [--dir <project-dir>] [--run <path>]
quick-codex resume [--dir <project-dir>] [--run <path>]
quick-codex project-status [--dir <project-dir>]
quick-codex snapshot [--dir <project-dir>] [--run <path>]

# Execution and verification
quick-codex verify-wave [--dir <project-dir>] [--run <path>] [--phase <id>] [--wave <id>]
quick-codex regression-check [--dir <project-dir>] [--run <path>] [--phase <id>] [--wave <id>]
quick-codex close-wave [--dir <project-dir>] [--run <path>] [--phase <id>] [--wave <id>] [--phase-done]
quick-codex lock-check [--dir <project-dir>] [--run <path>]

# Repair and validate
quick-codex repair-run [--dir <project-dir>] [--run <path>]
quick-codex doctor-run [--dir <project-dir>] [--run <path>]
quick-codex doctor-flow [--dir <project-dir>] [--run <path>]
quick-codex doctor-project [--dir <project-dir>]

# Delegation (role-split workflows)
quick-codex delegate-research [--dir <project-dir>] [--run <path>] [--question <text>]
quick-codex delegate-plan-check [--dir <project-dir>] [--run <path>] [--focus <text>]
quick-codex delegate-goal-audit [--dir <project-dir>] [--run <path>] [--focus <text>]
quick-codex complete-delegation [--dir <project-dir>] [--run <path>] --type <research|plan-check|goal-audit>

# Experience Engine sync
quick-codex capture-hooks [--dir <project-dir>] [--run <path>] [--input <path>]
quick-codex sync-experience [--dir <project-dir>] [--run <path>] --tool <name>

# Project sync
quick-codex sync-project [--dir <project-dir>] [--run <path>]

Full usage notes: QUICKSTART.md · EXAMPLES.md · TASK-SELECTION.md

Quick Codex improves workflow discipline around Codex. It does not change Codex core behavior.

Reduces:

• Context drift across turns
• Vague handoffs between planning and execution
• Execution thrash on longer tasks

Does not fix:

• Native Codex hangs or long internal wait states
• Quota or usage opacity
• Platform-level approval bugs
• Model-level compaction bugs

The package is a workflow layer. It helps work survive platform failures — it does not remove them.

• Read CONTRIBUTING.md
• Validate with bash scripts/lint-skills.sh
• Test a real task with artifacts, not only the docs

_{MIT License · Built for Codex CLI · Node 18+}