session-steward 0.11.0 → 0.11.2

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.11.2] - 2026-09-23
+
+### Added
+
+- Added `session-steward update` with version output and a sudo prompt when needed.
+
+### Changed
+
+- Updated compatibility coverage for current Codex and Claude releases, including Codex memory v2 storage.
+
+## [0.11.1] - 2026-09-14
+
+### Added
+
+- Added Official MCP Registry metadata and a package-name MCP launch command for registry clients.
+
 ## [0.11.0] - 2026-09-14
 
 ### Added
@@ -168,6 +184,8 @@
 - Support for custom Codex home folders and a saved folder preference.
 - Streaming and bounded-memory discovery for large session collections and transcripts.
 
+[0.11.2]: https://github.com/mallikcheripally/session-steward/compare/v0.11.1...v0.11.2
+[0.11.1]: https://github.com/mallikcheripally/session-steward/compare/v0.11.0...v0.11.1
 [0.11.0]: https://github.com/mallikcheripally/session-steward/compare/v0.10.3...v0.11.0
 [0.10.3]: https://github.com/mallikcheripally/session-steward/compare/v0.10.2...v0.10.3
 [0.10.2]: https://github.com/mallikcheripally/session-steward/compare/v0.10.1...v0.10.2

package/README.md

@@ -4,355 +4,212 @@
 [![Build status](https://img.shields.io/github/actions/workflow/status/mallikcheripally/session-steward/validate.yml?branch=main&style=flat-square&label=build)](https://github.com/mallikcheripally/session-steward/actions/workflows/validate.yml)
 [![License: MIT](https://img.shields.io/npm/l/session-steward?style=flat-square)](https://github.com/mallikcheripally/session-steward/blob/main/LICENSE)
 
-A local Codex and Claude Code session manager for safely reviewing, backing up, and deleting old sessions from a browser UI or terminal CLI, or through MCP with ChatGPT or Claude.
+Session Steward is a local session manager for Codex and Claude Code. It helps you find old or large sessions across workspaces, decide what is worth keeping, and clean up the related records it recognizes. You can use it with browser UI or terminal CLI, or through MCP with ChatGPT or Claude.
 
-AI coding tools can accumulate hundreds or thousands of local sessions. A session may leave behind transcripts, history, logs, checkpoints, and linked artifacts, so manual cleanup can easily miss related data.
+Codex can delete a session, and Claude Code can purge a project. Built-in deletion works when you already know what should go. Session Steward helps when the hard part is reviewing many sessions across both tools.
 
-Session Steward makes session cleanup safer by finding those records, showing what cleanup will affect, creating a local backup, removing supported data, and verifying the result afterward. Session Steward runs locally.
+- Find inactive or large sessions across workspaces. Switch between Codex and Claude Code, then filter by archive status, name, or session ID.
+- Open a session before deciding. See a distilled timeline of recent messages, file changes, commands, and command results, plus recognized storage and token use.
+- Clean selected sessions using a plan you review first, with a local backup, verification afterward, and recovery when cleanup needs attention.
 
-![Session Steward cleanup demo](https://raw.githubusercontent.com/mallikcheripally/session-steward/main/docs/session-steward-demo.gif)
-
-## Manage local Codex and Claude Code sessions
-
-- Review and clean up sessions from the browser, terminal, ChatGPT, or Claude through MCP.
-- Switch between Codex and Claude Code without installing another package.
-- See session counts and the storage used by recognized session files.
-- Find sessions inactive for 30, 60, or 90 days.
-- Filter active or archived sessions by workspace, name, or session ID.
-- Mark important sessions or workspaces Keep so cleanup skips them.
-- Inspect session details and affected records before deletion.
-- Read a session timeline of what you asked, what changed, and which commands ran.
-- See how many tokens a session used, split into fresh input, cached input, cache writes, and output.
-- Choose standard or thorough cleanup.
-- Use custom Codex or Claude home folders across browser and terminal sessions.
-
-## Safe by default
-
-- Cleanup happens entirely on your computer.
-- Only records included in the reviewed cleanup plan are removed.
-- A local recovery backup is created before anything changes.
-- Cleanup is verified before the backup is removed.
-- Unrecognized storage is reported and left untouched.
-- Thorough cleanup is unavailable when the detected storage format is not supported.
-- Cleanup stays local and does not upload session contents.
-
-### Keep important sessions
+## Try Session Steward locally
 
-Mark a session or workspace Keep and Session Steward skips it during manual and scheduled cleanup. A workspace Keep also covers descendant folders and future sessions there.
+Try the browser app for one run without installing it globally:
 
-It protects against Session Steward cleanup only. Codex or Claude Code can still remove the data.
+Session Steward requires Node.js 24.15 or newer.
 
-### Session Steward does not remove
-
-- Sign-in data or saved API credentials
-- Configuration, plugins, caches, or custom prompt files
-- Project files, Git repositories, or worktrees
-- Sessions outside the reviewed cleanup plan
-- Conversations stored in your ChatGPT or Claude account
-- Claude Code worktrees, branches, repositories, remote sessions, SSH sessions, or Cowork data
-
-At startup, Session Steward may contact the public npm registry to check for a newer version.
+```bash
+npx session-steward@latest
+```
 
-## Install and get started
+The browser app listens only on `127.0.0.1` and does not upload session contents.
 
-Session Steward supports macOS, Linux, and Windows and requires Node.js 24.15 or newer.
+![Session Steward cleanup demo](https://raw.githubusercontent.com/mallikcheripally/session-steward/main/docs/session-steward-demo.gif)
 
-Install it globally:
+For ongoing use, install it globally:
 
 ```bash
 npm install --global session-steward
 ```
 
-Then launch it:
-
-```bash
-session-steward
-```
+The global install provides four commands:
 
-Or try it without installing:
+| Command | Use it for |
+| --- | --- |
+| `session-steward` | Browser interface |
+| `session-steward-cli` | Interactive terminal and JSON output |
+| `session-steward-mcp` | MCP session management |
+| `session-steward-scheduler` | Automatic session cleanup |
 
-```bash
-npx session-steward@latest
-```
+Session Steward supports macOS, Linux, and Windows. Run `session-steward` to open the browser interface. Leave its terminal open while you use it; press `Ctrl+C` to stop it.
 
-Session Steward opens in your browser, listens only on `127.0.0.1`, and detects `~/.codex` and `~/.claude` by default. Claude Code CLI and local Claude Desktop sessions are detected on macOS and Windows; the Claude Code CLI is also supported on Linux. On Windows, these resolve to `%USERPROFILE%\.codex` and `%USERPROFILE%\.claude`.
+## Find old and large Codex and Claude Code sessions
 
-When run inside WSL, Session Steward uses the Linux home folder and manages sessions stored there. Run it from Windows to manage sessions in your Windows profile.
+Session Steward reads the local session folders already used by Codex and Claude Code. It looks for `~/.codex` and `~/.claude` by default and lets you switch providers from the same interface.
 
-To clean up sessions:
+You can:
 
-1. Review the detected sessions.
-2. Select one or more sessions.
-3. Choose a cleanup option.
-4. Review exactly what will be removed.
-5. Close any selected sessions that may still be active.
-6. Confirm the cleanup.
+- filter by inactivity, exact workspace, active or archived status, name, or session ID;
+- see recognized session-owned storage by session and workspace, then sort by size;
+- browse session timeline of recent messages, file changes, commands, and command results;
+- inspect fresh input, cached input, cache writes, output, and recorded reasoning tokens;
+- mark a session or workspace **Keep** so manual and scheduled cleanup skip it.
 
-Keep the terminal open while using Session Steward. Press `Ctrl+C` to stop it.
+A workspace Keep covers that folder, its descendants, and future sessions there. Keep affects Session Steward cleanup only. Codex or Claude Code can still remove their own data.
 
-## Cleanup and recovery
+## Why not just delete sessions one at a time?
 
-### Standard cleanup
+The native delete commands are useful when you already know what should go. They do not cover the same cross-workspace review and cleanup job.
 
-Recommended for routine removal. It removes supported transcripts, history, registry entries, logs, and linked session artifacts belonging to the selected sessions.
+A session can have more than its transcript. Depending on the provider and storage version, it may also have history or registry entries, logs, checkpoints, and other linked records. Removing a JSONL file by hand can leave those records behind.
 
-### Thorough cleanup
+Session Steward starts from the session instead of a file path. It finds supported related records, shows them in one cleanup plan, and leaves storage it does not recognize alone. You can review several candidates together without treating every old session as safe to delete.
 
-Includes standard cleanup and removes additional recognized session-owned data. For Codex this can include supported Desktop references, memory outputs, and goal records. For Claude Code this includes recognized file checkpoints.
+## Use the browser, CLI, or MCP
 
-Thorough cleanup is unavailable when Session Steward finds storage it does not recognize. Standard cleanup remains available for supported records that can be identified safely.
+### Browser
 
-### Recovery backups
+Run:
 
-A temporary backup is created inside the active provider folder under `session-steward-backups/`.
+```bash
+session-steward
+```
 
-After cleanup is successfully verified, the backup is removed automatically. If cleanup fails, Session Steward keeps the backup and lets you restore the sessions, keep the backup, or delete it.
+Choose Codex or Claude Code, filter or search the list, and open sessions you are unsure about. When you select sessions for cleanup, the browser shows the affected records before asking for confirmation.
 
-Before restoring, the current versions of affected files are saved separately to provide another recovery point.
+Use `session-steward --no-open` to start without opening a browser automatically. Open the local address printed in the terminal.
 
-## Terminal CLI
+### Terminal CLI
 
-Start the interactive terminal interface:
+Start the interactive terminal:
 
 ```bash
 session-steward-cli
 ```
 
-Use Claude Code instead of Codex:
+Use Claude Code instead of Codex, or return a limited JSON result for another tool:
 
 ```bash
 session-steward-cli --provider claude-code
-```
-
-List sessions as JSON:
-
-```bash
 session-steward-cli --json --limit 10
 ```
 
-<details>
-<summary>More terminal options</summary>
-
-Show session and workspace storage totals:
+Filter with options such as `--inactive-days 60`, `--archive-status archived`, or `--workspace /path/to/project`. Use `--events` for the timeline, `--tokens` for token use, and `--sort size` for the largest sessions first. Run `session-steward-cli --help` for every option.
 
-```bash
-session-steward-cli --overview
-```
-
-Add `--json` when the output will be read by another tool.
+### MCP with ChatGPT, Codex, or Claude Code
 
-Find sessions inactive for at least 60 days:
+Connect the local MCP server once:
 
 ```bash
-session-steward-cli --inactive-days 60
-```
-
-Show only archived sessions:
-
-```bash
-session-steward-cli --archive-status archived
+codex mcp add session-steward -- session-steward-mcp
 ```
 
-Show sessions from one exact workspace:
+Or connect it to Claude Code:
 
 ```bash
-session-steward-cli --workspace /path/to/project
+claude mcp add --scope user session-steward -- session-steward-mcp
 ```
 
-Use `--include-internals` to include subagents and `--include-supporting` to include supporting sessions. Session sizes are shown in the interactive list, and `--sort size` places the largest sessions first.
+Registry installers can start the same server without a global install using `npx session-steward@latest mcp`.
 
-Start with `--events` to read what happened inside a session — what you asked, what the assistant concluded, which files changed, and which commands ran or failed. In the interactive list, `inspect <number>` then shows that session's timeline:
+You can then ask your client to find inactive sessions, compare recognized session storage between Codex and Claude Code, inspect a session, keep a workspace, clean exact sessions, restore a backup, or manage a cleanup schedule.
 
-```bash
-session-steward-cli --events --events-limit 50
-```
+Session Steward marks cleanup, restore, and schedule management as destructive MCP actions so the client can apply its configured approval policy.
 
-With `--json`, each session carries its own `events`, plus a `coverage` summary of how much of the transcript was recognized:
+Scheduled cleanup continues in the background after you close the client. You can ask to pause, resume, run, change, or remove a schedule. Before uninstalling Session Steward, stop scheduled cleanup:
 
 ```bash
-session-steward-cli --json --limit 5 --events
-```
-
-Use `--tokens` to count what a session spent. The total is split into fresh input, cached input, cache writes, and output, with reasoning reported as a share of output where the provider records it:
-
-```bash
-session-steward-cli --tokens
-```
-
-In the interactive list, `tokens` toggles the same breakdown into `inspect`. With `--json`, each session carries a `tokens` object:
-
-```bash
-session-steward-cli --json --limit 5 --tokens
-```
-
-Cached input usually dominates, because the whole conversation is re-sent on every turn. A forked session reports its own work separately from the tokens it inherited from the session it branched from, so the two are never added together.
-
-The interactive terminal accepts the same filters:
-
-```text
-inactive 30
-inactive 60
-inactive 90
-archive active
-archive archived
-workspace /path/to/project
-internals
-supporting
-tokens
-keep 3
-unkeep 3
-keep-workspace /path/to/project
-unkeep-workspace /path/to/project
-cleanup standard
-cleanup thorough
-overview
-backups
+session-steward-scheduler --stop
 ```
 
-Run `inactive`, `archive`, or `workspace` without a value to clear that filter.
+For another MCP client, configure a local stdio server named `session-steward` with the command `session-steward-mcp`.
 
-`keep` and `unkeep` accept session selectors. `keep-workspace` and
-`unkeep-workspace` accept a full path.
+The MCP process uses Session Steward's saved provider folders or the defaults when none are saved. Its server command can set startup folders with `--codex-home` or `--claude-home`, and its `manage_settings` tool can change the saved folders. A one-time browser or CLI override does not carry into a later MCP process.
 
-`backups` lists recovery backups retained after an interrupted or unsuccessful cleanup. Use `restore <number>` to restore one, or `delete-backup <number>` to remove it permanently. Both actions require an explicit confirmation.
+The MCP server runs locally, but session details can contain messages, commands, file names, and workspace paths. Your MCP client may send that information to its AI provider.
 
-</details>
+## Review what will be deleted first
 
-Use `session-steward-cli --help` to see all available options.
+For a manual cleanup:
 
-## Clean up sessions with ChatGPT or Claude
+1. Select the sessions.
+2. Close any selected sessions that may still be active.
+3. Review the cleanup plan Session Steward builds.
+4. Confirm the plan.
+5. Session Steward creates a local recovery backup.
+6. It removes only supported records in the reviewed plan.
+7. It checks whether those records are gone.
 
-Connect Session Steward once, then ask ChatGPT or Claude to find old or large
-sessions, delete them safely, restore a backup, or clean sessions automatically
-on a schedule.
+Every interface revalidates the selected sessions before changing data. If Session Steward can detect that a selected session is active, preflight or cleanup stops. When detection is unavailable, it warns you to confirm that the selected sessions are closed.
 
-Connect it to ChatGPT and Codex:
+### Standard and thorough cleanup
 
-```bash
-codex mcp add session-steward -- session-steward-mcp
-```
+**Standard cleanup** removes supported transcripts, history, registry entries, logs, and linked artifacts belonging to the selected sessions. It is the routine option.
 
-Connect it to Claude Code:
+**Thorough cleanup** also removes additional recognized session-owned data. For Codex, that can include supported Desktop references, memory outputs, and goal records. For Claude Code, it includes recognized file checkpoints.
 
-```bash
-claude mcp add --scope user session-steward -- session-steward-mcp
-```
+Thorough cleanup is unavailable when the detected storage layout is not supported. Standard cleanup can still remove records that Session Steward can identify safely.
 
-You can then ask things like:
-
-- “Find sessions I have not used in 60 days.”
-- “Show sessions from this workspace, largest first.”
-- “Delete those sessions.”
-- “Keep this session from Session Steward cleanup.”
-- “Keep every session in this workspace.”
-- “Every 12 days, delete sessions I have not used in 45 days.”
-- “Restore my latest backup.”
-
-Cleanup uses the same local backup and verification checks as the browser and
-terminal. Codex or Claude Code asks for approval before cleanup, restore, or
-schedule changes.
-
-Scheduled cleanup continues in the background after you close Codex or Claude
-Code. You can ask to pause, resume, run, change, or remove a schedule. Before
-uninstalling Session Steward, stop scheduled cleanup:
-
-```bash
-session-steward-scheduler --stop
-```
-
-Check or remove the MCP connection at any time:
-
-```bash
-codex mcp list
-codex mcp remove session-steward
+<details>
+<summary>Backup and restore behavior</summary>
 
-claude mcp list
-claude mcp remove --scope user session-steward
-```
+Recovery backups are stored under `session-steward-backups/` inside the active provider folder.
 
-For another MCP client, add a local server named `session-steward`:
+If cleanup from the browser or interactive terminal needs attention, the backup is kept until you decide whether to restore it. The browser offers **Restore**, and the terminal reports the backup for the `restore` command. MCP and scheduled cleanup try to restore automatically.
 
-```json
-{
-  "mcpServers": {
-    "session-steward": {
-      "command": "session-steward-mcp"
-    }
-  }
-}
-```
+After successful cleanup, Session Steward removes the recovery backup when it can. A restore first creates a temporary safety backup of the current files, then tries to remove both backups if the restore succeeds. If a restore or backup removal cannot complete, recovery data remains and Session Steward reports it.
 
-The MCP server uses the same provider folders selected in the browser or
-terminal.
+</details>
 
-### Privacy
+### What cleanup leaves alone
 
-The MCP server runs locally. Session details can include messages, commands,
-file names, and workspace paths, and your MCP client may send that information
-to its AI provider.
+- Sign-in data and saved API credentials
+- Configuration, plugins, caches, and custom prompt files
+- Project files, Git repositories, and worktrees
+- Sessions outside the reviewed cleanup plan
+- Conversations stored in your ChatGPT or Claude account
+- Claude Code worktrees, branches, repositories, remote sessions, SSH sessions, and Cowork data
 
-## Use a custom provider folder
+## Provider folders and platform support
 
-The browser interface displays the active provider folder. Select **Change** to choose another existing folder and remember it for later browser and terminal sessions.
+The browser shows the active provider folder. Select **Change** to choose another existing folder and save it for later browser, terminal, and MCP sessions.
 
-For a one-time override:
+For a one-time browser override:
 
 ```bash
 session-steward --codex-home /path/to/.codex
-```
-
-For Claude Code:
-
-```bash
 session-steward --claude-home /path/to/.claude
 ```
 
-The command-line override applies only to that run and does not replace your saved folder.
+The CLI and MCP commands accept the same flags. An override applies only to that process and does not replace the saved folder.
 
-## Other commands
+Codex and Claude Code CLI sessions are supported on macOS, Linux, and Windows. Local Claude Desktop sessions are also supported on macOS and Windows. On Windows, the default provider folders are `%USERPROFILE%\.codex` and `%USERPROFILE%\.claude`; both standalone and Microsoft Store Claude Desktop data locations are detected.
 
-Start without automatically opening the browser:
+Inside WSL, Session Steward uses the Linux home folder. Run it from Windows to manage sessions in your Windows profile.
 
-```bash
-session-steward --no-open
-```
+Archiving a Claude Desktop session does not delete it. It remains available until it is explicitly included in cleanup. Session Steward does not remove Claude worktrees.
 
-Update Session Steward:
-
-```bash
-npm install --global session-steward@latest
-```
-
-Uninstall it:
+## Update or uninstall
 
 ```bash
+session-steward update
 npm uninstall --global session-steward
 ```
 
-Uninstalling Session Steward does not remove provider sessions, recovery backups, or saved folder preferences.
+If npm needs root access, the update command asks before retrying with `sudo`.
+
+Uninstalling does not remove provider sessions, recovery backups, or saved folder preferences.
 
 ## Troubleshooting
 
-- **The browser did not open:** Run `session-steward --no-open`, then open the local address shown in the terminal.
+- **The browser did not open:** Run `session-steward --no-open`, then open the local address printed in the terminal.
 - **No sessions were found:** Check the selected provider and displayed home folder. Use **Change** or pass a one-time home-folder override.
-- **Thorough cleanup is unavailable:** Review the compatibility details. Unrecognized storage is left untouched, but standard cleanup may still be available.
+- **Thorough cleanup is unavailable:** Unrecognized storage stays unchanged, while standard cleanup may still be available.
 - **Your Node.js version is too old:** Install Node.js 24.15 or newer and run Session Steward again.
 
-## Development
+## Benchmarks
 
-```bash
-git clone https://github.com/mallikcheripally/session-steward.git
-cd session-steward
-npm install
-npm test
-npm run build
-```
-
-## Performance and scale
-
-Session Steward uses paginated listings, incremental transcript reads, and bounded caches to remain responsive with large session libraries.
-
-Current synthetic benchmarks on an arm64 Mac with Node.js 24.15.0:
+Current benchmarks on an arm64 Mac with Node.js 24.15.0:
 
 | Scenario | Scale | Time | Measured memory growth |
 | --- | ---: | ---: | ---: |
@@ -374,11 +231,7 @@ Results vary with hardware, disk speed, and session layout. Tests and benchmarks
 
 ## Support
 
-Codex, Claude Code CLI, and local Claude Code Desktop sessions are supported. Claude Desktop archive is not treated as deletion, and Session Steward never removes its worktrees. On Windows, both the standalone and Microsoft Store Claude Desktop data locations are detected.
-
-Use [GitHub Issues](https://github.com/mallikcheripally/session-steward/issues) to report a bug, request a provider, or share a storage format that Session Steward does not recognize.
-
-See the [changelog](https://github.com/mallikcheripally/session-steward/blob/main/CHANGELOG.md) for published release history.
+Use [GitHub Issues](https://github.com/mallikcheripally/session-steward/issues) to report a bug, request a provider, or share a storage format that Session Steward does not recognize. See the [changelog](https://github.com/mallikcheripally/session-steward/blob/main/CHANGELOG.md) for release history.
 
 Session Steward is an independent project and is not affiliated with or endorsed by OpenAI or Anthropic.
 

package/bin/session-steward.mjs

@@ -10,20 +10,48 @@ import { findAvailableUpdate, formatUpdateNotice } from "../lib/update-check.mjs
 
 assertSupportedNode();
 
-const { values } = parseArgs({
-  allowPositionals: false,
-  options: {
-    "codex-home": { type: "string" },
-    "claude-home": { type: "string" },
-    help: { short: "h", type: "boolean" },
-    "no-open": { type: "boolean", default: false },
-    port: { type: "string" },
-    version: { short: "v", type: "boolean" },
-  },
-});
-
-if (values.help) {
-  process.stdout.write(`Usage: session-steward [options]
+if (process.argv[2] === "mcp") {
+  process.argv.splice(2, 1);
+  await import("./session-steward-mcp.mjs");
+} else if (process.argv[2] === "update") {
+  process.argv.splice(2, 1);
+  if (process.argv.length !== 2) {
+    process.stderr.write("Usage: session-steward update\n");
+    process.exitCode = 1;
+  } else {
+    const { updateSessionSteward } = await import("../lib/self-update.mjs");
+    try {
+      process.exitCode = await updateSessionSteward();
+    } catch (error) {
+      process.stderr.write(`Could not run the update: ${error.message}\n`);
+      process.exitCode = 1;
+    }
+  }
+} else {
+  await startBrowser();
+}
+
+async function startBrowser() {
+  const { values } = parseArgs({
+    allowPositionals: false,
+    options: {
+      "codex-home": { type: "string" },
+      "claude-home": { type: "string" },
+      help: { short: "h", type: "boolean" },
+      "no-open": { type: "boolean", default: false },
+      port: { type: "string" },
+      version: { short: "v", type: "boolean" },
+    },
+  });
+
+  if (values.help) {
+    process.stdout.write(`Usage: session-steward [options]
+       session-steward mcp [options]
+       session-steward update
+
+Commands:
+  mcp                  Run the MCP server over stdio
+  update               Install the latest version with npm
 
 Options:
   --codex-home <path>  Use a custom Codex session folder
@@ -33,44 +61,45 @@ Options:
   -h, --help           Show this help
   -v, --version        Show the installed version
 `);
-  process.exit(0);
-}
+    return;
+  }
 
-if (values.version) {
-  process.stdout.write(`${packageMetadata.version}\n`);
-  process.exit(0);
-}
+  if (values.version) {
+    process.stdout.write(`${packageMetadata.version}\n`);
+    return;
+  }
 
-const { startLocalServer } = await import("../lib/server.mjs");
-const port = values.port === undefined ? 0 : Number.parseInt(values.port, 10);
-const availableUpdate = await findAvailableUpdate({ packageMetadata });
+  const { startLocalServer } = await import("../lib/server.mjs");
+  const port = values.port === undefined ? 0 : Number.parseInt(values.port, 10);
+  const availableUpdate = await findAvailableUpdate({ packageMetadata });
 
-if (availableUpdate) {
-  process.stdout.write(`${formatUpdateNotice(availableUpdate)}\n`);
-}
+  if (availableUpdate) {
+    process.stdout.write(`${formatUpdateNotice(availableUpdate)}\n`);
+  }
 
-const server = await startLocalServer({
-  claudeHome: values["claude-home"],
-  codexHome: values["codex-home"],
-  port,
-});
-
-process.stdout.write(`Session Steward is running at http://127.0.0.1:${server.port}\n`);
-
-if (!values["no-open"]) {
-  const url = `http://127.0.0.1:${server.port}`;
-  const invocation = getBrowserOpenInvocation(url);
-
-  if (invocation) {
-    const opener = spawn(invocation.command, invocation.args, {
-      detached: true,
-      stdio: "ignore",
-      windowsHide: invocation.windowsHide,
-    });
-    opener.unref();
-  } else {
-    process.stdout.write(`Open ${url} in a browser.\n`);
+  const server = await startLocalServer({
+    claudeHome: values["claude-home"],
+    codexHome: values["codex-home"],
+    port,
+  });
+
+  process.stdout.write(`Session Steward is running at http://127.0.0.1:${server.port}\n`);
+
+  if (!values["no-open"]) {
+    const url = `http://127.0.0.1:${server.port}`;
+    const invocation = getBrowserOpenInvocation(url);
+
+    if (invocation) {
+      const opener = spawn(invocation.command, invocation.args, {
+        detached: true,
+        stdio: "ignore",
+        windowsHide: invocation.windowsHide,
+      });
+      opener.unref();
+    } else {
+      process.stdout.write(`Open ${url} in a browser.\n`);
+    }
   }
-}
 
-process.stdout.write("Press Ctrl+C to stop.\n");
+  process.stdout.write("Press Ctrl+C to stop.\n");
+}

package/lib/providers/claude-code/store.mjs

@@ -19,15 +19,15 @@ const PROVIDER_ID = "claude-code";
 const COMPATIBILITY_PROFILE = Object.freeze({
   id: "claude-local-store-2026-08",
   builtFor: {
-    claudeCli: ["2.1.199", "2.1.220", "2.1.228", "2.1.237", "2.1.267"],
-    claudeDesktop: ["1.24012.9", "1.28929.0", "1.32885.1", "1.40609.0", "1.49585.0"],
+    claudeCli: ["2.1.199", "2.1.220", "2.1.228", "2.1.237", "2.1.267", "2.1.280"],
+    claudeDesktop: ["1.24012.9", "1.28929.0", "1.32885.1", "1.40609.0", "1.49585.0", "2.2553.1"],
   },
 });
 const SUPPORTED_ENTRYPOINTS = new Set(["cli", "claude-desktop"]);
 const SHARED_DESKTOP_STATE_FILES = new Set(["scheduled-tasks.json"]);
 const KNOWN_TOP_LEVEL = new Set([
   ".DS_Store", ".last-cleanup", ".last-update-result.json", "agents", "backups", "cache", "commands", "debug", "downloads", "file-history", "history.jsonl", "history.jsonl.lock",
-  "ide", "paste-cache", "plans", "plugins", "projects", "session-env", "sessions", "settings.json",
+  "ide", "image-cache", "paste-cache", "plans", "plugins", "projects", "session-env", "sessions", "settings.json",
   "settings.local.json", "shell-snapshots", "skills", "stats-cache.json", "tasks", "telemetry",
   "todos", "uploads", "usage-data", "mcp-needs-auth-cache.json", "session-steward-backups",
 ]);

package/lib/providers/codex/database-families.mjs

@@ -4,12 +4,24 @@ import path from "node:path";
 import { queryRows } from "../../storage/sqlite.mjs";
 
 const CACHE_TTL_MS = 2_000;
+const MEMORY_TABLES = [
+  { name: "stage1_outputs", requiredColumns: ["thread_id"] },
+  {
+    name: "jobs",
+    optional: true,
+    requiredColumns: [
+      "kind", "job_key", "status", "worker_id", "ownership_token", "started_at",
+      "finished_at", "lease_until", "retry_at", "retry_remaining", "last_error",
+      "input_watermark", "last_success_watermark",
+    ],
+  },
+];
 
 export const CODEX_DATABASE_PROFILE = Object.freeze({
-  id: "codex-local-store-2026-08",
+  id: "codex-local-store-2026-09",
   builtFor: {
-    chatgptDesktop: ["26.727.40816", "26.803.61601", "26.818.21641", "26.818.22352", "26.825.41651", "26.903.61454", "26.903.71938"],
-    codexCli: ["0.144.1", "0.146.0", "0.147.0", "0.148.0", "0.153.4", "0.154.0"],
+    chatgptDesktop: ["26.727.40816", "26.803.61601", "26.818.21641", "26.818.22352", "26.825.41651", "26.903.61454", "26.903.71938", "26.917.51856"],
+    codexCli: ["0.144.1", "0.146.0", "0.147.0", "0.148.0", "0.153.4", "0.154.0", "0.156.1"],
   },
 });
 
@@ -30,28 +42,13 @@ const SCHEMA_REQUIREMENTS = Object.freeze({
     fallback: "memories_1.sqlite",
     pattern: /^memories_(\d+)\.sqlite$/u,
     required: false,
-    tables: [
-      { name: "stage1_outputs", requiredColumns: ["thread_id"] },
-      {
-        name: "jobs",
-        optional: true,
-        requiredColumns: [
-          "kind",
-          "job_key",
-          "status",
-          "worker_id",
-          "ownership_token",
-          "started_at",
-          "finished_at",
-          "lease_until",
-          "retry_at",
-          "retry_remaining",
-          "last_error",
-          "input_watermark",
-          "last_success_watermark",
-        ],
-      },
-    ],
+    tables: MEMORY_TABLES,
+  },
+  memoriesV2: {
+    fallback: "memories_v2_1.sqlite",
+    pattern: /^memories_v2_(\d+)\.sqlite$/u,
+    required: false,
+    tables: MEMORY_TABLES,
   },
   goals: {
     fallback: "goals_1.sqlite",

package/lib/providers/codex/store.mjs

@@ -479,7 +479,7 @@ export function getCodexPaths(codexHomeInput, { refresh = false } = {}) {
   const archivedSessionsDirectory = path.join(codexHome, "archived_sessions");
   const sessionsDirectory = path.join(codexHome, "sessions");
   const resolution = resolveCodexDatabases(codexHome, { refresh });
-  const { goals, logs, memories, queue, state, threadHistory } = resolution.families;
+  const { goals, logs, memories, memoriesV2, queue, state, threadHistory } = resolution.families;
   const stateDatabasePath = state.primary?.path ?? path.join(codexHome, "state_5.sqlite");
   const logsDatabasePath = logs.primary?.path ?? path.join(codexHome, "logs_2.sqlite");
   const memoryDatabasePath = memories.primary?.path ?? path.join(codexHome, "memories_1.sqlite");
@@ -500,7 +500,8 @@ export function getCodexPaths(codexHomeInput, { refresh = false } = {}) {
     logsDatabasePath,
     logsDatabasePaths: allValidDatabases(logs).map((database) => database.path),
     memoryDatabasePath,
-    memoryDatabasePaths: allValidDatabases(memories).map((database) => database.path),
+    memoryDatabasePaths: [memories, memoriesV2].flatMap((family) =>
+      allValidDatabases(family).map((database) => database.path)),
     queueDatabasePath,
     queueDatabasePaths: allValidDatabases(queue).map((database) => database.path),
     resolvedDatabases: databaseFamilySummary(resolution),
@@ -971,6 +972,8 @@ function stateSchema(database) {
     ? database.tables.thread_dynamic_tools
     : inspectSqliteTable(database.path, "thread_dynamic_tools");
   const schema = {
+    attachmentTables: ["thread_artifacts", "thread_attachments"]
+      .filter((tableName) => inspectSqliteTable(database.path, tableName).exists),
     columns,
     hasDynamicTools: Boolean(dynamicTools?.exists),
     hasSpawnEdges: Boolean(spawn?.exists),
@@ -2408,6 +2411,9 @@ export async function fingerprintSessionDeletion({ plan, scope, store }) {
 
   for (const database of store.stateDatabases ?? [{ path: store.stateDatabasePath }]) {
     fingerprintRowsForIds(hash, database.path, "threads", "id", plan.ids);
+    for (const tableName of stateSchema(database).attachmentTables) {
+      fingerprintRowsForIds(hash, database.path, tableName, "thread_id", plan.ids);
+    }
     if (stateSchema(database).hasDynamicTools) {
       fingerprintRowsForIds(hash, database.path, "thread_dynamic_tools", "thread_id", plan.ids);
     }

package/lib/self-update.mjs

@@ -0,0 +1,95 @@
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline/promises";
+
+import packageMetadata from "../package.json" with { type: "json" };
+import { getCommandInvocation } from "./platform.mjs";
+
+const PACKAGE_SPEC = `${packageMetadata.name}@latest`;
+const INSTALL_ARGS = ["install", "--global", PACKAGE_SPEC];
+const VERSION_ARGS = ["list", "--global", "--depth=0", "--json", packageMetadata.name];
+
+async function runCommand(command, args, { captureStdout = false, platform, stderr, stdout }) {
+  const invocation = getCommandInvocation(command, args, { platform });
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(invocation.command, invocation.args, {
+      stdio: ["inherit", "pipe", "pipe"],
+      windowsHide: invocation.windowsHide,
+    });
+    let errorOutput = "";
+    let output = "";
+
+    child.stdout.on("data", (chunk) => {
+      if (captureStdout) output = (output + chunk.toString()).slice(-16_384);
+      else stdout.write(chunk);
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr.write(chunk);
+      errorOutput = (errorOutput + chunk.toString()).slice(-8_192);
+    });
+    child.on("error", reject);
+    child.on("close", (exitCode) => resolve({ exitCode: exitCode ?? 1, errorOutput, output }));
+  });
+}
+
+async function confirmSudo({ stdin, stdout }) {
+  const prompt = createInterface({ input: stdin, output: stdout });
+  try {
+    const answer = await prompt.question("Retry the update with sudo? [y/N] ");
+    return /^(?:y|yes)$/iu.test(answer.trim());
+  } finally {
+    prompt.close();
+  }
+}
+
+export async function updateSessionSteward({
+  confirm = confirmSudo,
+  currentVersion = packageMetadata.version,
+  platform = process.platform,
+  run = runCommand,
+  stdin = process.stdin,
+  stdout = process.stdout,
+  stderr = process.stderr,
+} = {}) {
+  stdout.write(`Current version: ${currentVersion}\nUpdating Session Steward with npm...\n`);
+  let result = await run("npm", INSTALL_ARGS, { platform, stderr, stdout });
+  let usedSudo = false;
+
+  if (result.exitCode !== 0 && /\b(?:EACCES|EPERM)\b/u.test(result.errorOutput)) {
+    if (platform === "win32") {
+      stderr.write("Global npm install needs permission. Open an elevated terminal and run session-steward update.\n");
+    } else if (stdin.isTTY && stdout.isTTY) {
+      stdout.write("The global npm install needs elevated permission.\n");
+      if (await confirm({ stdin, stdout })) {
+        usedSudo = true;
+        result = await run("sudo", ["npm", ...INSTALL_ARGS], { platform, stderr, stdout });
+      }
+    } else {
+      stderr.write("Global npm install needs elevated permission. Run sudo session-steward update in a terminal.\n");
+    }
+  }
+
+  if (result.exitCode === 0) {
+    let installedVersion;
+    try {
+      const versionResult = await run(
+        usedSudo ? "sudo" : "npm",
+        usedSudo ? ["npm", ...VERSION_ARGS] : VERSION_ARGS,
+        { captureStdout: true, platform, stderr, stdout },
+      );
+      if (versionResult.exitCode === 0) {
+        installedVersion = JSON.parse(versionResult.output)?.dependencies?.[packageMetadata.name]?.version;
+      }
+    } catch {
+      // Installation succeeded, but npm could not confirm the installed version.
+    }
+
+    if (typeof installedVersion === "string" && /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.+-]+)?$/u.test(installedVersion)) {
+      stdout.write(`Updated version: ${installedVersion}\n`);
+    } else {
+      stderr.write("Update completed, but the installed version could not be confirmed. Run session-steward --version.\n");
+    }
+  }
+
+  return result.exitCode;
+}

package/lib/update-check.mjs

@@ -80,6 +80,6 @@ export async function findAvailableUpdate({
   }
 }
 
-export function formatUpdateNotice({ latestVersion, packageName }) {
-  return `Session Steward ${latestVersion} is available. Update with: npm install -g ${packageName}@latest`;
+export function formatUpdateNotice({ latestVersion }) {
+  return `Session Steward ${latestVersion} is available. Update with: session-steward update`;
 }

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "session-steward",
-  "version": "0.11.0",
-  "description": "Codex and Claude Code session manager - browse, back up, and delete old sessions. Local browser UI + CLI.",
+  "version": "0.11.2",
+  "mcpName": "io.github.mallikcheripally/session-steward",
+  "description": "Codex and Claude Code session manager - browse and delete old sessions. Browser UI + CLI + MCP",
   "license": "MIT",
   "author": "Mallik Cheripally",
   "type": "module",
@@ -22,17 +23,19 @@
     "codex-cli",
     "codex-sessions",
     "codex-cleanup",
+    "codex-session-manager",
     "openai-codex",
     "chatgpt-desktop",
     "claude-code",
     "claude-code-sessions",
     "claude-code-cleanup",
+    "claude-code-session-manager",
     "claude-desktop",
     "session-cleanup",
     "session-history",
     "session-manager",
-    "disk-space",
-    "disk-cleanup"
+    "automatic-session-cleanup",
+    "mcp-server"
   ],
   "os": [
     "darwin",