version: "1.0.1" name: codex-fluent description: Use when Codex feels slow, bloated, or heavy after heavy use. Provides safe session hygiene, archive strategy, and handoff discipline to keep daily Codex usage responsive and low-friction. Always pairs with comprehensive handoffs before archiving active work.

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)

2. Handoff Creation (Mandatory for Valuable Work)

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

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 Spellbook 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.
• Design handoff documents as the compact representation of a thread: preserve the objective, constraints, decisions, verification, and unresolved work.
• 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).

Gotchas

• A large session is not automatically safe to archive. If the work is active,

blocked, or likely to resume, create the handoff first and verify that the reactivation prompt points to a real file.

• Reported size reductions do not prove product speedups by themselves. Compare

before/after active-state size and a fresh startup or session-switch test.

• Never treat "Codex is closed" as an assumption. If apply mode would touch

active state, verify process state or get explicit user acceptance first.

• Do not normalize paths, prune config, or move global skills in the same pass

as session archiving unless the diagnosis explicitly named those candidates.

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.