Codex Fluent Agent Skill

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