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