Codex Sessions Manager

Overview

CLI-first local Codex history audit and recovery tool. Use official Codex for normal task management and permanent deletion. Use this tool to verify what remains under ~/.codex, inspect legacy or damaged state, and perform previewable recoverable cleanup for confirmed residual IDs.

This is not a UI product, TUI, detail page, incremental scanner, or automatic cleanup service.

Setup

npm install -g codex-sessions-manager
codex-sessions --version

The default Codex root is ~/.codex. Use --root <path> for a different root.

For official Codex Skill discovery, place this Skill directory at either:

• project scope: .agents/skills/codex-sessions-manager
• user scope: $HOME/.agents/skills/codex-sessions-manager

The distributed Skill includes agents/openai.yaml inside the Skill directory.

When To Use

• List/filter/search sessions (by project, time, status, source)
• Show session detail or timeline
• Inspect session family (parent/child/subagent/side/fork)
• Audit and verify what remains locally after official deletion
• Scan root for likely residue candidates
• Preview batch delete scope without executing
• Build explicit-ID delete plans
• Export session backup
• Delete sessions (permanent or recoverable trash)
• Restore or purge trash entries
• Verify post-delete cleanliness
• Clean stale JSONL indexes

CLI Quick Reference

codex-sessions doctor [--json] [--details]
codex-sessions list [--limit N] [--project TEXT] [--status S] [--source-kind K]
codex-sessions sources [--json]
codex-sessions projects
codex-sessions show <id> [--json]
codex-sessions events <exact-id> [--output FILE]
codex-sessions family <id> [--children|--parents|--subagents|--impact|--full]
codex-sessions audit <id> [--json]
codex-sessions audit-root [--limit 50] [--status S...] [--source S...]
codex-sessions preview-root [--limit 50] [--status S...] [--source S...]
codex-sessions monthly-review [--limit 50] [--status S...] [--source S...] [--details]
codex-sessions export <id> [--output ./backup.json]
codex-sessions plan-delete <id...> [--include-children] [--include-family] [--json]
codex-sessions plan-delete --source-kind K --limit N [--json]
codex-sessions preview-plan <file> [--json]
codex-sessions delete <full-uuid...> [--trash] [--yes] [--allow-active]
codex-sessions trash-list
codex-sessions restore <exact-trash-id> --yes
codex-sessions purge <exact-trash-id> --yes
codex-sessions cleanup-index <full-uuid...> [--yes] [--allow-active]
codex-sessions cleanup-stale [--yes]
codex-sessions verify <id...>
codex-sessions recovery-status [--json]
codex-sessions recover <exact-operation-id> --yes

Safety Rules

• All destructive commands require --yes (CLI) or confirm=true (MCP); without it you get preview only.
• Always run a separate preview before any destructive action, then require explicit user confirmation.
• preview, plan-delete, family, impact, audit-root, preview-root, monthly-review are read-only. They are never deletion authorization.
• Permanent delete removes only exact thread-linked logs. Trash retains them; restore leaves them unchanged; final purge removes them unless that ID is live again. Memory is always retained.
• Delete never recursively adds parent, child, or family sessions. List every intended ID explicitly.
• Allowlisted exact-key global-state refs are removable only through explicit-ID confirmed delete.
• Unknown global-state refs are warnings only; do not delete them automatically.
• Confirmed session mutations require full canonical UUIDs. Active-session deletion also requires --allow-active / allowActive=true.
• An interrupted write keeps an exclusive lock and durable recovery record. Inspect it before running the exact confirmed recovery operation.
• A committed operation with partial or failed verification remains committed and must be reported that way.

MCP (Optional, Advanced)

codex-sessions-mcp                       # default: read-only profile (16 bounded tools)
codex-sessions-mcp --profile admin       # all 22 tools including destructive ops

Invalid --profile values exit with code 1. Default is read-only for safety.

get_session defaults to detail=compact (20 items / 64 KiB / 1 MiB source read). detail=full is still bounded (200 items / 256 KiB / 8 MiB source read). Session metadata is bounded too. Both return explicit completeness metadata; sourceCompleteness preserves parse/unsupported status when the MCP envelope is also truncated_limit, and itemsKnown=null means the reader stopped before EOF. list_sessions defaults to 50 concise records, accepts at most 200, and caps the response at 256 KiB. Use CLI JSON for complete local result sets and export for a JSON recovery bundle whose embedded text or base64 data can reconstruct source-file bytes.

All other MCP structured responses also have a final 256 KiB / 200-items-per-collection cap. Explicit session operations accept at most 50 IDs; list_trash defaults to 50 entries. Limit hits return responseCompleteness and responseOmittedReason. Exact backup export is CLI-only.

Detailed References

For full CLI/MCP parameter reference, safety model, and advanced rules:

• Detailed tool reference
• Safety guide