The Problem

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:

| Pain point | Without | With Quick Codex | |---|---|---| | Codex keeps losing the thread | Plan lives in chat only | Persistent run artifact: gate, phase, wave, blockers | | Can't resume after interruption | Reconstruct state by hand | quick-codex resume — one command, one pasteable prompt | | Execution drifts mid-task | Agent guesses the next step | qc-lock strict loop: preflight → plan → lock → execute → verify → fix | | Gray areas silently ignored | Agent picks a path and keeps going | Hard stop until each gray area resolves or is explicitly deferred | | Context loss at compaction | Transcript dragged forward wastefully | Deliberate carry-forward with scoped keep/drop cues |

How It Works

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:

| Layer | What it preserves | |---|---| | C1 Baseline | Goal, required outcomes, affected area, out-of-scope boundaries | | C2 State | Current gate, phase, wave, execution mode, blockers | | C3 Resume | Next safe command, next verify, compact-safe handoff | | C4 Risk | Session risk, burn risk, approval strategy | | C5 Experience | Hook-derived warnings, active constraints, invariants | | C6 Proof | Verification ledger, requirements still satisfied |

Demo

The GIFs below show real terminal sessions. Record your own with asciinema.

1 — Resume after interruption

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

Active run:   .quick-codex-flow/add-sync-feature.md
Current gate: Execute → Wave 2
Phase:        P2 — Implementation

Next prompt to paste:
  Use $qc-flow and resume from .quick-codex-flow/add-sync-feature.md.
  Restate: gate, phase, wave, blockers, experience constraints, next verify.

Carry-forward cues:
  Phase relation:        same-phase
  Compaction action:     compact
  What to forget:        Wave 1 implementation detail
  What must remain:      protected boundary list, verify path

[▶ Watch full demo — record and replace this block with your GIF] Place at: docs/demo/resume.gif then embed with ![Resume demo](docs/demo/resume.gif)

2 — qc-flow: plan a non-trivial task

$ # Prompt: Use $qc-flow for: add safer multi-repo sync preview

[qc-flow] Clarify State
  Goal confirmed: add preview mode before sync executes
  Affected area: scripts/sync.sh, repo-tool CLI, 3 config files
  Gray area #1: should preview be opt-in flag or default?
  → 3 options generated, recommended: opt-in --dry-run flag

[qc-flow] Delivery Roadmap created
  P1 — Add --dry-run flag to sync.sh
  P2 — Surface preview output in repo-tool CLI
  P3 — Document and verify edge cases

[qc-flow] Verified Plan (P1)
  Wave 1: modify sync.sh + unit test
  Wave 2: wire CLI flag
  Verify: bash test/sync-dry-run.sh

[▶ Watch full demo — record and replace this block with your GIF] Place at: docs/demo/qc-flow.gif

3 — qc-lock: strict execution with verification

$ # Prompt: Use $qc-lock for: fix missing branch name error in repo-tool

[qc-lock] Preflight
  Affected file: src/repo-tool.js:L142
  Protected boundary: existing --switch behavior
  Verify path: node test/branch-error.test.js

[qc-lock] Locked Plan
  Step 1: add guard clause for missing branch name
  Step 2: run verify
  → PASS: node test/branch-error.test.js exits 0

[qc-lock] Done — requirements still satisfied ✓

[▶ Watch full demo — record and replace this block with your GIF] Place at: docs/demo/qc-lock.gif

Quick Start

Install from npm

npx quick-codex install

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

Use it

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>

Scaffold a project

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

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

Check your active run

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

Other install options

# 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

Which Skill to Use

| Situation | Use | Why | |---|---|---| | Requirements unclear, scope unknown | qc-flow | Clarifies, surfaces affected area, researches, then executes | | Bug fix with known scope | qc-lock | Stays close to preflight → verify → fix | | Small refactor, known files | qc-lock | Keeps scope narrow, verifies each step | | Task spans multiple turns | qc-flow | Persistent artifacts survive session resets | | Already have a qc-flow run in progress | qc-flow | Resume from artifact, don't switch midstream | | qc-flow done, only execution left | qc-lock | Hand off to strict executor once front-half is complete |

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

Benchmarks

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

| Benchmark | What it proves | |---|---| | Resume After Interruption | Recovers active run, next gate, and next prompt from local state — not chat memory | | Verification Thrash | Real fail → narrow → fix loop instead of broad blind retries | | Scope Drift | Explicit artifacts and locked execution reduce mid-task drift | | Failure Recovery | Recovery behavior when the workflow is partial or awkward | | Carry-Forward Footprint | Same-phase next-wave pack is materially smaller than the full artifact | | Brain-Advised Session Action | Protocol works alone; sharper when Experience Engine adds a guarded verdict | | Workflow Hardening | Forces affected-area discussion, evidence-based planning, and qc-lock preflight | | Compaction Modes | compact vs clear vs relock checkpoint decisions are explicit, not implicit |

Full benchmark index: BENCHMARKS.md

OpenAI Native Integration

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).

Experience Engine Integration

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

Division of responsibility:

| Layer | Owner | |---|---| | Protocol baseline: phase relation, compaction action, safety guardrails | Quick Codex | | Advisor layer: hook warnings, brain verdict, model-choice routing | Experience Engine |

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.

CLI Reference

# 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

Known Limits

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.

Contributing

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

Troubleshooting

• npx quick-codex install fails → wait for npm propagation or use npx --yes ./quick-codex install
• Update available → npx quick-codex@latest upgrade
• npm cache not writable → npm_config_cache=/tmp/qc-cache npx quick-codex install
• Codex does not see the skills → check ~/.agents/skills, restart Codex

• doctor-run says stale → quick-codex repair-run --dir ./my-project
• lock-check not lock-ready → make affected area, exclusions, evidence basis, and verify path explicit; remove active gray-area triggers
• verify-wave cannot find verify commands → add Verify: bullets to Current Execution Wave
• close-wave refuses → run verify-wave first, clear failing ledger entries

• Unsure which skill → start with qc-flow, switch to qc-lock when scope is locked
• Validate the package → node bin/quick-codex.js doctor
• init should not overwrite my AGENTS.md → it writes AGENTS.quick-codex-snippet.md when AGENTS.md already exists