codex-fluent

The full skill.

Original instructions from the publisher’s SKILL.md

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

#### Deterministic Active-Session Triage (Report-Only Scanner)

Route deterministic report-only diagnosis of old active sessions through the
bundled scanner:

```
python3 ~/.codex/skills/codex-fluent/scripts/report_active_sessions.py \
  --codex-home ~/.codex --older-than-days 30 --limit 30 --format markdown
```

Contract:

- `--older-than-days` accepts any value `>= 0`; the default window is 30 days.
- `--limit` accepts 20 to 50 inclusive; the default is 30. Values such as 19
  or 51 are rejected before any scan.
- The primary size ranking is immutable: `primary_rank` is assigned once from
  `(-size_bytes, started_at, thread_id)` and never renumbered.
- A separate `returned_handoff_queue` lists returned candidates whose
  `compaction_count` is 2 or more (`handoff_required`), sorted by
  `compaction_count` descending then `primary_rank` ascending. It always
  reports `queue_scope=returned-window-only`: it covers only the returned
  top-N window and makes no claim about eligible tasks outside it.
- Compactions are counted only from decoded top-level JSONL objects whose
  `type` equals `compacted`; embedded strings and nested payload types never
  count.
- Repository identity is evidence-backed and nullable: with the current
  persisted schema, `repo_root` is `null` with provenance `unknown`. The
  scanner never infers a repository from a `cwd` basename and never probes
  guessed paths. `cwd_label` is display-only.
- Malformed session and index lines are skipped and counted
  (`skipped_session_lines`, `skipped_index_lines`), as are invalid or missing
  timestamps; subagent sessions are always excluded.
- The scanner is strictly report-only: it opens inputs only for reading and
  never writes file content or explicit metadata. Do not archive or delete
  based on its output alone. It never runs apply behavior.
- Reports are classified `sensitive-local` because operational identity fields
  can include thread titles, IDs, and local paths; do not publish or paste a
  report into a shared issue, webpage, or model context without reviewing and
  redacting it first. Markdown output renders persisted metadata inertly but
  does not remove the operational identity fields.

### 2. Handoff Creation (Chat Default)

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

The default handoff artifact is a terminal chat handoff: a structured message
in the task itself recording anchors, state, evidence, blockers, and one
next-safe task. A repo-native handoff file is allowed only when the original
task explicitly authorized the exact documentation path. Archive authorization
does not imply file-write authorization. Apply authorization does not imply
file-write authorization. Without that exact-path authorization, keep active
and do not archive.

When a file handoff is authorized, 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).

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