Catalog / Incubator

Incubator candidate

Codex Context Guard

Prevent Codex context-window exhaustion during long-running refactors, repo audits, migrations, debugging sessions, or tasks with large logs, many file reads, or repeated tool output. Use when Codex context is getting high, /compact may be needed, or the user asks for context-efficient workflows.

Codex Operations Version 0.1.0 Apache-2.0 Codex/OpenAI metadata available

Goal

Keep a long Codex session useful by reducing unnecessary context growth, preserving decisions in a compact handoff, and choosing bounded next steps before the thread becomes hard to continue.

Trigger conditions

  • The task has many files, logs, diffs, generated outputs, or repeated tool calls.
  • The user asks whether to compact, summarize, or continue in a new thread.
  • The agent is about to inspect broad files without a specific need.

When to use

  • Use when context budget, log volume, or file-reading scope is becoming a risk.
  • Use before compacting a long session or moving work to another thread.

When not to use

  • Do not use for short, self-contained tasks that have no context pressure.
  • Do not use as a substitute for actually validating completed work.

Inputs to inspect

  • Current objective, recent user instructions, changed files, validation output, and unresolved blockers.
  • Use git status --short and git diff --stat before reading large diffs.

Rules

  • Prefer targeted rg, sed, git diff --stat, and small file ranges over whole-file dumps.
  • Keep one bounded objective active at a time.
  • Store durable state in a handoff artifact when the work will outlive the current context.
  • Summarize large outputs instead of pasting them back to the user.
  • Tell the user when a compaction or handoff would preserve momentum.

Workflow

  1. Identify the current objective, latest decision, and next blocking question.
  2. Replace broad exploration with a targeted search plan.
  3. Track changed files, validation commands, and open risks in a compact note.
  4. Use references only when they solve the immediate context problem.
  5. When context is high, prepare a handoff and recommend /compact or a new thread.

Commands

Useful low-context commands:

git diff --stat
git status --short
rg -n "pattern" path
sed -n '1,120p' path/to/file

Safety rules

  • Do not hide failed validation behind a summary.
  • Do not discard unresolved blockers when compacting.
  • Do not paste secrets or full large logs into handoff text.

References

Read only when needed:

  • references/context-budgeting.md for large task tactics.
  • references/handoff-template.md when writing a handoff file.

Scripts

No bundled scripts.

Output format

Return:

  1. Current objective
  2. Context risks
  3. What to keep in active context
  4. What to move to a handoff
  5. Recommended next bounded action

Completion criteria

  • The active objective and next action are clear.
  • Large context sources have been summarized or moved to a handoff.
  • Validation failures and blockers remain visible.

Failure modes

  • If context is already overloaded, stop broad reads and produce a compact state summary.
  • If important evidence is missing, name the missing command or file instead of guessing.

Recovery behavior

If the thread is already overloaded, stop broad exploration, write a compact state summary, name the most recent verified command result, and recommend continuing from the handoff.