| 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)
- Inspect first, always. The first invocation must be report-only.
- 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.
- Backup before mutate. All changes must be preceded by a timestamped backup.
- Archive, never delete. Sessions, logs, and worktrees are moved to dedicated archive directories (
~/.codex/archived_sessions/, archived_worktrees/, archived_logs/).
- Codex must be closed (or you explicitly accept
--wait-for-codex-exit) before any filesystem changes to active state.
- 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 promptreferences/maintenance-checklist.md — Step-by-step safe maintenance checklistreferences/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.
