sessions

Sessions Command

Manage OpenAI Codex session history - list, load, alias, and edit sessions stored in ~/.codex/session-data/ with legacy reads from ~/.codex/sessions/.

Execution Contract

• Role: session-history operator for local OpenAI Codex metadata only.
• Surface: read or update session aliases and session metadata; do not modify project source files.
• State: treat ~/.codex/session-data/, ~/.codex/sessions/, and aliases as durable local state; summarize old history instead of replaying it.
• Compatibility: keep legacy ~/.codex/sessions/ reads while preferring ~/.codex/session-data/.
• Rollback: alias edits must be reversible by removing the alias entry; never delete session files.
• Validation and errors: validate requested IDs or aliases, report missing sessions without guessing, and leave files unchanged on errors.
• Verification command: node tests/lib/session-manager.test.js && node tests/scripts/session-inspect.test.js.

Usage

/sessions [list|load|alias|info|help] [options]

Actions

List Sessions

Display all sessions with metadata, filtering, and pagination.

Use /sessions info when you need operator-surface context for a swarm: branch, worktree path, and session recency.

/sessions                              # List all sessions (default)
/sessions list                         # Same as above
/sessions list --limit 10              # Show 10 sessions
/sessions list --date 2026-02-01       # Filter by date
/sessions list --search abc            # Search by session ID

Script:

node -e "
const _r = (()=>{var e=process.env.CODEX_PLUGIN_ROOT;if(e&&e.trim())return e.trim();var p=require('path'),f=require('fs'),h=require('os').homedir(),d=p.join(h,'.codex'),q=p.join('scripts','lib','utils.js');if(f.existsSync(p.join(d,q)))return d;for(var s of [['eoc'],['eoc@eoc'],['marketplaces','eoc'],['ecc'],['ecc@ecc'],['marketplaces','ecc'],['ecc','everything-openai-codex'],['eoc','everything-openai-codex'],['everything-openai-codex'],['everything-openai-codex@everything-openai-codex'],['marketplaces','everything-openai-codex']]){var l=p.join(d,'plugins',...s);if(f.existsSync(p.join(l,q)))return l}try{for(var g of ['ecc','everything-openai-codex'],['eoc','everything-openai-codex']){var b=p.join(d,'plugins','cache',g);for(var o of f.readdirSync(b,{withFileTypes:true})){if(!o.isDirectory())continue;for(var v of f.readdirSync(p.join(b,o.name),{withFileTypes:true})){if(!v.isDirectory())continue;var c=p.join(b,o.name,v.name);if(f.existsSync(p.join(c,q)))return c}}}}catch(x){}return d})();
const sm = require(_r + '/scripts/lib/session-manager');
const aa = require(_r + '/scripts/lib/session-aliases');
const path = require('path');

const result = sm.getAllSessions({ limit: 20 });
const aliases = aa.listAliases();
const aliasMap = {};
for (const a of aliases) aliasMap[a.sessionPath] = a.name;

console.log('Sessions (showing ' + result.sessions.length + ' of ' + result.total + '):');
console.log('');
console.log('ID        Date        Time     Branch       Worktree           Alias');
console.log('────────────────────────────────────────────────────────────────────');

for (const s of result.sessions) {
  const alias = aliasMap[s.filename] || '';
  const metadata = sm.parseSessionMetadata(sm.getSessionContent(s.sessionPath));
  const id = s.shortId === 'no-id' ? '(none)' : s.shortId.slice(0, 8);
  const time = s.modifiedTime.toTimeString().slice(0, 5);
  const branch = (metadata.branch || '-').slice(0, 12);
  const worktree = metadata.worktree ? path.basename(metadata.worktree).slice(0, 18) : '-';

  console.log(id.padEnd(8) + ' ' + s.date + '  ' + time + '   ' + branch.padEnd(12) + ' ' + worktree.padEnd(18) + ' ' + alias);
}
"