Codex Sessions Manager

Save, browse, clone, and hot-restore Codex sessions without moving accounts.

codex-sessions-mgr is built around one primary experience: ask the Codex agent to preserve or restore session memory for you with /codex-session-mgr. The terminal manager, codex-mgr, is the power-user surface for browsing, batch cleanup, diagnostics, and external-terminal restores.

The project has a deliberately tight boundary: it moves conversation history, not identity.

English | 简体中文

Start With The Skill

The recommended entry point is:

/codex-session-mgr

Use it when you want the agent to:

• save the current session before switching context;
• capture project-related sessions into a private library;
• inspect what has already been saved;
• recover or migrate sessions across providers, accounts, machines, or worktrees;
• hot-restore a saved session into the current Codex Desktop client.

That is the most convenient path because the agent already knows the current thread, workspace, Codex home, and recovery intent. It can choose the right engine command, preview the write plan, preserve safety boundaries, and open the restored clone after verification.

The user-facing surfaces are:

Surface	Use It For
/codex-session-mgr	Primary agent-driven save, inspect, migrate, and hot-restore workflow
codex-mgr	Interactive terminal manager for library browsing, search, cleanup, diagnostics, and manual restore
scripts/session-mgr.mjs	Internal JSON engine for the skill, tests, automation, and future UI surfaces

scripts/session-mgr.mjs is intentionally not the normal user interface.

Why This Exists

Codex sessions are valuable working memory. They contain project context, debugging trails, experiments, restore notes, and handoff state that you may want to keep when you switch provider, account, machine, or worktree.

This manager gives you a safer workflow:

• capture the current session or a project-related set of sessions;
• inspect global Codex sessions by home and provider;
• browse your saved library with search, paging, duplicate markers, and exact records;
• clone a saved backup into a fresh thread id;
• hot-open the clone through codex://threads/<new-id> while Codex Desktop stays open;
• delete only saved library backups, never real Codex sessions.

Safety Model

The manager does not copy authentication, tokens, config files, caches, logs, or account state.

Normal restore flows only write the minimal session artifacts needed for Codex Desktop visibility:

• sessions/**/rollout-*.jsonl
• session_index.jsonl
• the target row in state_5.sqlite.threads

Before restore writes, codex-mgr backs up state_5.sqlite and session_index.jsonl into the target Codex home .tmp directory. Restores always clone into new thread ids; they do not overwrite the source session.

Deletion is scoped to the manager library at ~/.codex-sessions-mgr/library. It does not delete .codex/sessions, archived sessions, auth, config, cache, logs, or sqlite account state.

Hot Restore

Hot restore is the default path for agent-driven restore. If Codex Desktop is already open, the agent should not ask you to close it; closing Desktop would normally terminate the agent doing the work.

The flow:

1. Choose or infer a saved backup record.
2. Choose the target Codex home.
3. Choose the target provider.
4. Confirm with HOT.
5. The manager writes a cloned rollout using Codex's native rollout filename format.
6. It appends session_index.jsonl, upserts the Desktop threads row, checkpoints WAL, verifies rollout/index/sqlite state, and opens codex://threads/<new-id>.

The result shows the new clone id, rollout/index/sqlite checks, WAL checkpoint result, and deep-link opener result.

Offline Restore

Offline restore is for conservative external-terminal workflows where Codex Desktop is intentionally closed before writes.

Use it from codex-mgr when you are outside the active Codex Desktop agent session. Inside an active agent session, use hot restore.

Install

The short version is: clone this repository into a Codex skills directory, install Node dependencies, then link the terminal command.

macOS/Linux:

skills_dir="$HOME/.agents/skills"
mkdir -p "$skills_dir"
git clone <repo-url> "$skills_dir/codex-sessions-mgr"
cd "$skills_dir/codex-sessions-mgr"
npm install
npm link

Windows PowerShell:

$skillsDir = Join-Path $HOME ".agents\skills"
New-Item -ItemType Directory -Force -Path $skillsDir | Out-Null
git clone <repo-url> (Join-Path $skillsDir "codex-sessions-mgr")
Set-Location (Join-Path $skillsDir "codex-sessions-mgr")
npm install
npm link

Then use /codex-session-mgr from Codex, or start the terminal manager:

codex-mgr

Detailed guides:

• Install guide
• 中文安装指南
• Agent install runbook

Terminal Manager

codex-mgr is the self-service terminal control surface. In an interactive terminal it opens a stateful manager console:

Codex Sessions Manager

Navigation / Homes        Global Sessions                  Detail / Actions
------------------        ----------------                 ----------------
> Global Sessions         > restore investigation          id
  Library Backups           hotstart probe                  cwd
  Save                       test session                   provider
  Hot Restore                                               library status
  Offline Restore
  Diagnostics

[q] quit  [r] refresh  [s] save  [h] hot restore  [o] offline  [d] delete

The layout is built for routine session operations:

• left rail: views, Codex homes, provider counts;
• center list: global sessions or saved library backups;
• right rail: selected record detail, restore state, delete preview, or diagnostics.

Core keys:

Key	Action
Up/Down, j/k	Move cursor
type text	Live search in the active list
Backspace	Edit search
Esc	Clear search or go back
Tab	Switch view
n/p, Left/Right	Page
Space	Multi-select backup records in Library
h	Hot restore selected backup
o	Offline restore selected backup
d	Delete selected/current backup records
s	Save sessions
r	Refresh
t	Cycle theme

Themes:

codex-mgr --theme aurora
codex-mgr --theme ember
codex-mgr --theme mono

Or:

$env:CODEX_MGR_THEME="mono"

Exact Backup Records

The library can contain multiple backups for the same source session id. The manager therefore exposes recordKey, which identifies one concrete backup record.

• library list --json returns recordKey for each saved backup.
• library delete --record-key <key> deletes exactly that backup record.
• restore-project --record-key <key> restores exactly that backup version.

The older --id selector remains available for compatibility and aggregate same-source-id workflows.

JSON Engine

The low-level engine is useful for tests, automation, and agent workflows:

node scripts\session-mgr.mjs overview --json
node scripts\session-mgr.mjs library list --json
node scripts\session-mgr.mjs capture --scope current-session --json
node scripts\session-mgr.mjs restore-project --cwd <project> --json

Most mutating commands are dry-run by default and require --apply.

Verify

npm run check
npm test

npm run check syntax-checks the main scripts. npm test runs the Node built-in test suite for restore candidate ordering, URL opening, prompt fallback, recordKey semantics, hot restore flow, and TUI rendering.

Roadmap

Near-term work is focused on polishing the terminal manager:

• bring target home/provider selection fully into the three-column console;
• improve restore result diagnostics;
• keep non-TTY fallback stable for scripts and CI;
• defer the web/dashboard surface until the TUI and engine contracts are stable.