Codex/Claude Code skill + CLI + MCP server

Install globally

npm install -g codex-sessions-manager

Quick Start

```bash

CLI Reference

codex-sessions list [--status active|archived] [--limit N] [--project TEXT]
codex-sessions list --updated-after 2026-04-01 --updated-before 2026-04-30
codex-sessions list --group-by project
codex-sessions list --source-kind cli --model-provider openai
codex-sessions list --source mcp --thread-source mcp
codex-sessions list --agent-role subagent --agent-nickname helper
codex-sessions sources [--json]
codex-sessions projects
codex-sessions doctor [--json]
codex-sessions show <session-id>
codex-sessions family <session-id> [--json] [--children|--parents|--subagents|--impact] [--full] [--source-kind KIND]
codex-sessions audit <session-id> [--json]
codex-sessions audit-root [--json] [--limit 50] [--status STATUS...] [--source SOURCE...] [--all]
codex-sessions preview-root [--json] [--limit 50] [--status STATUS...] [--source SOURCE...] [--all]
codex-sessions export <session-id> [--output ./backup.json]
codex-sessions delete <session-id...> [--trash] [--yes]
codex-sessions trash-list
codex-sessions restore <trash-id-or-session-id> --yes
codex-sessions purge <trash-id-or-session-id> --yes
codex-sessions cleanup-stale [--yes]
codex-sessions cleanup-index <session-id...> [--yes]
codex-sessions verify <session-id...> [--json]

Safety first: All destructive commands require --yes. Without it, you only get a preview. Run a separate preview for the exact session IDs first; family, impact, audit-root, and preview-root never count as permission to delete.

export and trash bundles are recovery data, not previews. They may include full global-state exact-key values such as prompt-history content. Human delete previews show only path, rule, shape, and byte counts.

Duplicate trash entries: restore does not delete the trash entry. If a restored session is moved to trash again, trash-list can show multiple recoverable copies for the same session ID. This is normal trash state, not live residue. A newer copy does not replace an older one. When one session ID has multiple trash entries, confirmed restore and purge refuse the session ID and require the exact trashId. Do not auto-purge duplicates. purge permanently removes only the selected trash entry and never touches the live session.

Use audit after the official Codex UI delete/archive flow when you need a clear local residue report. It is read-only. It reports whether the raw rollout file, shell snapshot, session_index, history, SQLite records, known global-state refs, P11 exact-key global-state refs, unknown global-state refs, and thread_spawn_edges are still present. It also reports family membership and broken parent/child links. If anything remains, the suggested next command is a preview-only delete command; nothing is deleted unless you add --yes.

Use audit-root when you do not already have the session ID. It scans the whole Codex root and lists likely residue candidates by risk: broken parent/child edges, missing rollout files with unknown global-state refs, SQLite-only rows, shell snapshots, index-only rows, and other partial leftovers. It is read-only, defaults to --limit 50, does not print transcript content, and recommends a per-session audit command for each candidate. Add --all only when you intentionally want complete non-residue sessions included too.

audit-root supports display-only filters. Matching candidates are not a deletion list or a deletion recommendation; audit them one by one or inspect a read-only preview before choosing any cleanup:

• --status risky-global-state
• --status global-state-exact-key
• --status db-only
• --status broken-family
• --status partial-residue
• --status global-state-unknown
• --source global-state-unknown
• --source global-state-exact-key
• --source global-state-known
• --source sqlite
• --source session-index
• --source history
• --source shell-snapshot
• --source thread-spawn-edges

You can pass --status or --source more than once. Multiple values of the same kind use OR. Combining status and source uses AND. These filters only narrow what is shown. A matching candidate still needs per-session audit or delete preview before any cleanup decision, and it does not mean the candidate should be deleted.

Human and JSON output include a summary: filters, totalCandidatesBeforeFilter, totalCandidatesAfterFilter, returnedCandidates, limit, byStatus, and bySource. The byStatus and bySource counts are computed after status/source filters and before limit.

Use sources when you need a read-only overview of where sessions came from. It groups by inferred sourceKind, raw source, thread_source, model_provider, model, and agent_role. sourceKind can be subagent, mcp, vscode, cli, exec, or unknown. The raw source value is still kept in JSON output and shown in human output, because sourceKind is only this tool's inferred category.

list supports the same source-facing filters: --source-kind, --source, --thread-source, --agent-role, --agent-nickname, --model-provider, and --model. Filters combine with AND across different fields. Repeating the same field uses OR. MCP list_sessions accepts the same fields, and MCP summarize_sources returns the same summary shape as CLI sources --json.

Important source limits:

• source=vscode is a raw Codex thread source label. It should not be treated as proof that the chat came from the VS Code IDE.
• Do not infer "Desktop" by exclusion. Sessions not marked cli, mcp, vscode, or exec are unknown, not automatically Desktop.
• source=mcp means the thread was recorded with that source. It is not a log of every MCP tool call inside the conversation.
• model_provider is only displayed and filtered here. This tool does not repair provider identity or rewrite provider history.

Use preview-root when you want a read-only batch delete preview for the same candidates audit-root would select. It reuses the same status/source filters and conservative default --limit 50, then summarizes what a read-only preview would touch across rollout files, shell snapshots, session_index, history, SQLite, known global-state refs, P11 exact-key global-state refs, unknown global-state refs, and thread_spawn_edges. It does not delete, does not rewrite JSONL, SQLite, shell snapshots, or global-state, does not accept --yes, does not recommend deleting any session, and does not recursively add parent, child, or family sessions. A preview-root result is not a deletion recommendation; it only shows what would be touched if you later choose explicit delete commands. Actual deletion still requires a separate explicit-ID delete preview and then a separate delete ... --yes command.