Codex Fluent

Keep Codex feeling fast, light, and pleasant to use over months of heavy daily work.

This skill is about operational fluency — the subjective experience of Codex staying responsive, starting quickly, and not forcing you to fight accumulated context and state.

Core Philosophy

• Fresh small state = speed and low mental load.
• Old work must be preserved, but moved out of the active path.
• Handoffs are non-negotiable before archiving anything you might still need.
• Never delete. Archive with clear restore paths.

When to Use This Skill

• Codex feels laggy on startup or when switching sessions.
• You have many long-running or old chats you rarely touch but don't want to lose.
• Before big maintenance or after noticing session directory growth.
• After a codex-retrospective session where Codex itself flagged repeated context bloat or "I keep having to re-explain the current state".

Safety Rules (Hard)

1. Inspect first, always. The first invocation must be report-only.
2. Handoff before archive. For any active repo chat you might continue, a high-quality handoff document + reactivation prompt must exist before it is moved to archive.
3. Backup before mutate. All changes must be preceded by a timestamped backup.
4. Archive, never delete. Sessions, logs, and worktrees are moved to dedicated archive directories (~/.codex/archived_sessions/, archived_worktrees/, archived_logs/).
5. Codex must be closed (or you explicitly accept --wait-for-codex-exit) before any filesystem changes to active state.
6. Never touch credentials, global skills you still use, or memory files without explicit confirmation.

Recommended Cadence

• Heavy daily multi-repo users: weekly report + maintenance when needed.
• Moderate users: every 10–14 days.
• The skill can generate a recurring report-only reminder prompt for you.

Workflow

1. Diagnosis (Report Mode)

Ask:

Use codex-fluent to inspect my current Codex local state and give me a clear picture of what is causing drag.

The skill will report on:

• Active vs archived session sizes
• Largest active sessions and their ages
• Stale worktrees
• Large log files
• Potential thread metadata bloat (title/preview)
• Dead config entries
• Heavy background processes (reported only)

Deterministic Active-Session Triage (Report-Only Scanner)

Route deterministic report-only diagnosis of old active sessions through the bundled scanner:

python3 ~/.codex/skills/codex-fluent/scripts/report_active_sessions.py \
  --codex-home ~/.codex --older-than-days 30 --limit 30 --format markdown

Contract:

• --older-than-days accepts any value >= 0; the default window is 30 days.
• --limit accepts 20 to 50 inclusive; the default is 30. Values such as 19 or 51 are rejected before any scan.
• The primary size ranking is immutable: primary_rank is assigned once from (-size_bytes, started_at, thread_id) and never renumbered.
• A separate returned_handoff_queue lists returned candidates whose compaction_count is 2 or more (handoff_required), sorted by compaction_count descending then primary_rank ascending. It always reports queue_scope=returned-window-only: it covers only the returned top-N window and makes no claim about eligible tasks outside it.
• Compactions are counted only from decoded top-level JSONL objects whose type equals compacted; embedded strings and nested payload types never count.
• Repository identity is evidence-backed and nullable: with the current persisted schema, repo_root is null with provenance unknown. The scanner never infers a repository from a cwd basename and never probes guessed paths. cwd_label is display-only.
• Malformed session and index lines are skipped and counted (skipped_session_lines, skipped_index_lines), as are invalid or missing timestamps; subagent sessions are always excluded.
• The scanner is strictly report-only: it opens inputs only for reading and never writes file content or explicit metadata. Do not archive or delete based on its output alone. It never runs apply behavior.
• Reports are classified sensitive-local because operational identity fields can include thread titles, IDs, and local paths; do not publish or paste a report into a shared issue, webpage, or model context without reviewing and redacting it first. Markdown output renders persisted metadata inertly but does not remove the operational identity fields.

2. Handoff Creation (Chat Default)

Before any archiving of chats you care about, create excellent handoffs.

The default handoff artifact is a terminal chat handoff: a structured message in the task itself recording anchors, state, evidence, blockers, and one next-safe task. A repo-native handoff file is allowed only when the original task explicitly authorized the exact documentation path. Archive authorization does not imply file-write authorization. Apply authorization does not imply file-write authorization. Without that exact-path authorization, keep active and do not archive.

When a file handoff is authorized, use the template in references/handoff-template.md.

The reactivation prompt must allow a completely fresh Codex thread (or even Claude via the codex skill) to pick up without the old giant context.

3. Apply Maintenance

Only after handoffs exist for everything important:

Use codex-fluent to perform safe maintenance now. I have created handoffs for the sessions I want to keep continuity on. Codex is closed.

What a normal apply does:

• Timestamped backup to ~/Documents/Codex/codex-backups/codex-fluent-YYYYMMDD-HHMM/
• Move qualifying old sessions to ~/.codex/archived_sessions/
• Move stale worktrees to ~/.codex/archived_worktrees/
• Rotate oversized logs
• Clean dead project entries from config
• Normalize certain path issues where safe

4. Verification

Run diagnosis again and compare before/after sizes and feel.

5. (Optional) Recurring Reminder

Generate a safe, report-only weekly reminder prompt that never applies changes automatically.

Integration with Other Arsenal Skills

• After running codex-retrospective, if Codex complains about "having to re-read huge context every time" or repeated state loss, this skill is the natural follow-up.
• Use strategic-compact thinking when designing handoff documents — they should be the ultimate compact representation of a thread.
• Handoff documents created here are excellent material to feed into future codex-retrospective runs.

What This Skill Will Not Do

• Automatically delete anything.
• Kill processes.
• Touch credentials or irreplaceable memory.
• Archive pinned or explicitly marked "do not touch" sessions without confirmation.
• Promise universal speedups (results depend on your usage patterns).

References

• references/handoff-template.md — High-quality handoff document template + reactivation prompt
• references/maintenance-checklist.md — Step-by-step safe maintenance checklist
• references/examples/ — Real-world (anonymized) before/after reports and handoff examples

Success Criteria

After using this skill properly you should experience:

• Noticeably faster Codex startup and session switching
• Lower anxiety about "losing history"
• Clear, searchable handoff documents in your important repos
• A repeatable, low-risk maintenance habit

Start with a diagnosis run. The rest follows naturally.