codex-sessions-manager

简体中文

Codex Desktop now includes a delete action for archived chats. Local testing shows that it removes the main session file and some thread rows, but may still leave session index rows, execution logs, and desktop state references behind.

codex-sessions-manager is a local Codex session audit and cleanup tool. It works as a Skill (Claude Code / Codex), a CLI, and an MCP server — all sharing the same core. Use it to inspect what remains under ~/.codex, audit leftovers after the official UI delete/archive flow, clean hidden local residues by exact session ID, and verify that deletion actually left no local orphans.

Why this one?

Codex Desktop's built-in delete is the right first stop for ordinary archived-chat cleanup. This tool is for the harder local cases: proving what remains after deletion, cleaning orphaned records, handling exact session IDs, and giving agents a safe way to manage local history.

Quick Start

# Install globally
npm install -g codex-sessions-manager

# List recent sessions
codex-sessions list --limit 10

# Inspect parent and child sessions (safe, no changes)
codex-sessions family <session-id>

# Audit what still exists locally after official UI archive/delete (safe, no changes)
codex-sessions audit <session-id>

# Scan the whole root for likely residue candidates (safe, no changes)
codex-sessions audit-root --limit 50
codex-sessions audit-root --status risky-global-state --source global-state-unknown --limit 50

# Preview what deletion would do (safe, no changes)
codex-sessions delete <session-id>

# Delete with recoverable trash (recommended)
codex-sessions delete <session-id> --trash --yes

# Changed your mind? Restore it
codex-sessions restore <session-id> --yes

# Verify nothing is left behind
codex-sessions verify <session-id>

How deletion actually works

Most tools: delete one file or one DB row → done → orphans everywhere.

This tool:

1. Snapshot all files (in case we need to roll back)
2. Rewrite session_index.jsonl (remove matching rows)
3. Rewrite history.jsonl (remove matching rows)
4. Clean `.codex-global-state.json` references
5. Delete raw session files
6. Delete shell snapshot files
7. Delete SQLite rows (threads, logs, spawn_edges, agent jobs, dynamic tools, stage1, thread goals)

If ANY step fails → everything rolls back to the original state.

After deletion, run verify to confirm zero orphans remain.

Features

Use with AI Agents (MCP)

Add to your MCP config:

{
  "mcpServers": {
    "codex-sessions": {
      "command": "codex-sessions-mcp",
      "args": []
    }
  }
}

16 tools exposed: inspect_root, list_sessions, list_projects, get_session, get_session_family, audit_session, audit_root, export_session_backup, preview_delete_sessions, delete_sessions, list_trash, restore_sessions, purge_trash, cleanup_session_indexes, cleanup_stale_indexes, verify_sessions.

get_session_family, audit_session, and audit_root are read-only and do not need confirmation. All destructive tools require confirm: true. Without it, you get a preview only.

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 projects
codex-sessions doctor [--json]
codex-sessions show <session-id>
codex-sessions family <session-id> [--json]
codex-sessions audit <session-id> [--json]
codex-sessions audit-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 <session-id> --yes
codex-sessions purge <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.

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, 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:

• --status risky-global-state
• --status db-only
• --status broken-family
• --status partial-residue
• --status global-state-unknown
• --source global-state-unknown
• --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 family before deleting a parent or child session. Parent and child sessions are independent sessions with their own IDs. Deleting a parent does not delete children, and deleting a child does not delete its parent. Delete previews and audits warn when relationship records point at missing sessions or missing file/index surfaces. To process multiple related sessions, put every intended session ID into the preview/delete command explicitly. The tool never recurses into parent or child sessions automatically.

Human-readable family output keeps the table narrow by showing compact source labels such as subagent, mcp, exec, side-thread, or unknown. Use family --json or MCP get_session_family when you need the full raw source field.

Session Titles

A local Codex session can have multiple title sources:

• displayTitle: the default title shown in lists, preferred from session_index.jsonl.thread_name, and usually closest to what Codex UI search can find.
• indexTitle: the title from session_index.jsonl.
• sqliteTitle: the threads.title value from state_N.sqlite, which can be an older internal long title.
• firstUserMessage: the first user request.
• titleSource: where the current display title came from.
• titleMismatch: whether title sources disagree.
• titleCandidates: all candidate titles.

list and search results show displayTitle by default. Human-readable show prints shortened sqliteTitle, firstUserMessage, title candidates, and timeline preview so title drift is visible without dumping large transcript-like text. Use show --json when you need the full values and full timeline.

What Codex stores (and what we clean)

When Codex Desktop deletes an archived chat, it may already remove some of these surfaces. audit-root can find likely leftover IDs first, and audit gives a read-only report for one ID. verify remains useful after a cleanup action. delete --yes or cleanup-index --yes can remove remaining local records only when you intentionally choose to do so.

~/.codex/
├── sessions/            ← raw rollout JSONL files        ✅ cleaned
├── archived_sessions/   ← archived rollout JSONL files   ✅ cleaned
├── shell_snapshots/     ← shell snapshot scripts         ✅ cleaned
├── session_index.jsonl  ← session metadata index         ✅ cleaned
├── history.jsonl        ← conversation history index     ✅ cleaned
├── state_N.sqlite       ← threads and related records     ✅ cleaned
├── logs_N.sqlite        ← execution logs                 ✅ cleaned
└── .codex-global-state.json ← known active-session refs   ✅ cleaned

Documentation

• Safety guide — read before delete/trash/restore/purge
• Changelog — release notes
• SKILL.md — AI skill instructions for Claude Code / Codex

Development

git clone https://github.com/1939869736luosi/codex-sessions-manager.git
cd codex-sessions-manager
npm install
npm run build
npm test

License

Apache-2.0