Codex Fluent

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

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.

Example of a High-Quality Handoff (Shortened)

(This is what good handoffs produced with codex-fluent tend to look like.)

Project: Internal billing service refactor Date: 2026-05-12

Executive Summary

We were extracting the billing calculation logic into a dedicated service with proper idempotency and retry semantics. The core happy path + two main failure modes are implemented and tested. The remaining work is around partial failure compensation and observability.

Key Decisions

• Use event-sourced ledger for all money movements (decided after comparing with outbox pattern).
• All compensation must be explicit and logged; no implicit rollback.
• Idempotency keys are required on every public mutation.

Current State

• internal/billing/ledger.go — the new event source, well tested
• internal/billing/calculator.go — pure functions + property tests
• API handlers still call the old monolith code in some paths (flagged for next step)

Next 5 Steps (Prioritized)

1. Implement the two compensation flows for the "payment succeeded but downstream failed" case. 2. Add structured logging + trace IDs across the new service. 3. Wire the new service behind a feature flag in staging. 4. Write the migration script for historical ledger entries (read-only first). 5. ...

Constraints & Style

• Prefer early returns and small functions in this package.
• All money values must go through the Money type (never raw int64 in business logic).
• Do not touch the legacy billing_v1 package unless explicitly asked.

Reactivation Prompt

Read docs/codex-handoffs/2026-05-12-billing-service.md.

Explore the current state of the repo, especially the billing directory.

Continue from the "Next 5 Steps" section. Start by confirming the current status of step 1.

Example: Typical Before/After Report (Anonymized)

Before (Heavy Use for 6 Weeks)

• Active sessions: ~47 GB total (many long debugging threads + old feature work)
• Largest active chat: 8.2 GB (one particularly painful auth + infra incident)
• Stale worktrees: 14 (some over 3 weeks old)
• Large logs: several logs_2.sqlite* files > 1.2 GB each
• Thread metadata bloat detected: 3 threads with title/preview > 80k characters each
• Feeling: "Codex takes 12–15 seconds to start and feels heavy when switching anything"

Actions Taken

1. Created handoff documents for the 4 active repos the user actually cared about continuing. 2. Archived 38 old sessions (everything non-pinned older than 12 days after handoffs). 3. Moved 11 stale worktrees. 4. Rotated oversized logs. 5. Cleaned dead project entries in config.

After (Same Day)

• Active sessions: 2.8 GB (mostly current 2–3 active threads)
• Archived sessions: 41 GB (still fully accessible, just not loaded)
• Startup time: subjectively "instant" again
• Switching between current threads: fast and pleasant
• Mental load: much lower — user knows exactly which work is "hot" and which is safely in handoff + archive

Key Lesson

The 8 GB incident thread was archived after a 40-minute handoff document was written. Two weeks later the user needed to look something up from it — they used the handoff + quick grep in the archived transcript instead of reopening the giant chat. Much better experience.

This pattern repeated across multiple cleanups.

Codex Handoff Document Template

Use this structure when creating a handoff before archiving a valuable session with codex-fluent.

The goal of a handoff is perfect continuity with minimal context. A fresh Codex thread (or even Claude via the codex skill) should be able to read the repo + this document and continue productively without the old chat.

---

Project / Ticket: Date of Handoff: Previous Session Context (optional): Handoff Author: (usually Codex itself)

Executive Summary (2-4 sentences)

What we were trying to achieve and the current state.

Key Decisions & Rationale

• Decision: ...
• Rationale: ...
• Tradeoffs considered: ...

Current Codebase State

List only the files that matter for continuation. One line each.

• path/to/important/file.ts: Current purpose + recent changes
• ...

Environment & Commands

• How to run / test / build relevant parts
• Any special setup or env vars for this task

What Has Been Completed

• [x] ...
• [x] ...

Open Questions & Next Steps (Prioritized)

1. High — Specific task with clear success criteria 2. Medium — ... 3. Low / Nice to have — ...

Constraints & Preferences (Very Important)

• Do not touch: ...
• User style notes: (e.g. "prefers early returns", "hates magic numbers in this file")
• Things we deliberately avoided and why

Reactivation Prompt (Copy-Paste Ready)

We are continuing work from a previous Codex session. 

Read the handoff document at: docs/codex-handoffs/YYYY-MM-DD-topic.md (or wherever it was saved).

1. First, explore the current state of the repo to verify what still applies.
2. Read the handoff document completely.
3. Then continue from the "Open Questions & Next Steps" section.
4. Do not assume the previous chat history is available.

Start by confirming you have understood the current state and the next priority.

Additional Notes for Future You

Anything that might be useful 2 weeks or 2 months from now.

---

Save this file in a stable location, for example:

• docs/codex-handoffs/YYYY-MM-DD-short-topic.md
• Or a project-specific handoff directory you already use.

After saving, you can safely archive the original heavy session using codex-fluent.

Codex Fluent — Safe Maintenance Checklist

Use this checklist when running codex-fluent in apply mode. Treat every step as mandatory unless you have a very good reason.

Pre-Apply (Do This Every Time)

• [ ] Ran full diagnosis in report mode first
• [ ] Reviewed sizes and candidates
• [ ] Identified all active repo chats that still matter
• [ ] Created high-quality handoff documents + reactivation prompts for every chat you might want to continue later (see handoff-template.md)
• [ ] Confirmed Codex is not running (or explicitly accepted --wait-for-codex-exit)
• [ ] Understand that we only archive, never delete

Backup Phase

• [ ] Triggered a timestamped backup (the skill does this automatically in apply mode)
• [ ] Know where the backup lives: ~/Documents/Codex/codex-backups/codex-fluent-...
• [ ] (Optional but recommended) Manually copy the backup to an external drive for very large cleanups

Archive Decisions

For each candidate the report surfaced, explicitly decide:

• [ ] This session/chat → archive (only after handoff exists)
• [ ] This worktree → archive (stale and not needed)
• [ ] This log → rotate/archive
• [ ] This config entry → safe to prune

During Apply

• [ ] Skill is running with appropriate flags (usually --archive-older-than-days X --worktree-older-than-days Y)
• [ ] Watching for any warnings

Post-Apply Verification

• [ ] Ran diagnosis again
• [ ] Confirmed active state is now significantly smaller
• [ ] Started a fresh test thread to verify "snappy" feel
• [ ] Can still find and read all archived material if needed
• [ ] (If using the optional metadata repair) Verified that full transcripts are still intact

After First Successful Maintenance

• [ ] Asked the skill to generate a recurring report-only reminder prompt
• [ ] Scheduled it (weekly for heavy use, bi-weekly otherwise)
• [ ] Documented your personal policy (e.g. "archive non-pinned chats older than 10 days after handoff")

Red Flags — Stop and Re-evaluate

• You feel pressure to archive something without a handoff "just this once"
• The skill suggests touching credentials or global skills you still actively use
• You haven't used the resulting handoff documents in practice yet (they might need improvement)
• Active state is still huge after archiving (there might be other causes — database bloat, many open sidebar threads, etc.)

Remember the goal: Codex should feel like a sharp, lightweight tool again, not a heavy application you have to fight. Handoff discipline is what makes aggressive archiving safe.