session-steward 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+## [0.3.0] - 2026-08-03
+
+### Added
+
+- Support for Claude Code CLI sessions on macOS and Linux, plus local Claude Code Desktop sessions on macOS.
+- Provider switching and separate saved home folders for Codex and Claude Code.
+- Per-session sizes, workspace storage totals, date grouping, and largest-first sorting.
+- CLI overviews and filters for inactivity, archive status, workspace, session type, and size.
+- CLI tools to list, restore, and permanently remove recovery backups retained after unsuccessful cleanup.
+
+### Changed
+
+- Redesigned the browser interface with clearer navigation, filters, selection controls, session details, and cleanup progress.
+- Kept session discovery, activity detection, and size calculations responsive with bounded caches and incremental reads.
+- Stopped tracking generated `dist` files; npm packages continue to build and include the production UI automatically.
+
+### Fixed
+
+- Opening a Claude session no longer makes it appear recently active when its transcript has not changed.
+
+## [0.2.0] - 2026-08-01
+
+### Added
+
+- Session and storage overview metrics.
+- Filters for inactivity, archive status, and workspace in the browser and terminal interfaces.
+- Guided restore and backup removal options when cleanup cannot be completed.
+- Scale benchmarks for session listing, storage overviews, and transcript discovery.
+
+### Changed
+
+- Recovery backups are removed automatically after cleanup is verified and retained only when recovery may be needed.
+- Session listing and cleanup planning were expanded to handle large local session collections with bounded memory use.
+- The README and product demo were revised around the complete cleanup workflow.
+
+## [0.1.1] - 2026-08-01
+
+### Added
+
+- `--help` and `--version` options for the Session Steward launcher.
+
+## [0.1.0] - 2026-08-01
+
+### Added
+
+- Browser and terminal interfaces for reviewing local Codex sessions.
+- Standard and thorough cleanup with a deletion preview, recovery backup, and post-cleanup verification.
+- Compatibility checks that leave unrecognized Codex storage untouched.
+- Support for custom Codex home folders and a saved folder preference.
+- Streaming and bounded-memory discovery for large session collections and transcripts.
+
+[0.3.0]: https://github.com/mallikcheripally/session-steward/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/mallikcheripally/session-steward/compare/v0.1.1...v0.2.0
+[0.1.1]: https://github.com/mallikcheripally/session-steward/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/mallikcheripally/session-steward/releases/tag/v0.1.0

package/README.md

@@ -1,36 +1,66 @@
 # Session Steward
 
-Safely review, back up, and remove local Codex sessions with a browser UI or terminal CLI.
+[![npm version](https://img.shields.io/npm/v/session-steward?style=flat-square)](https://www.npmjs.com/package/session-steward)
+[![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)
 
-Session Steward is a local-first Codex session manager for macOS and Linux. It shows what will be removed before cleanup, creates a local backup, and verifies the result afterward. Your session data stays on your computer.
+A local Codex and Claude Code session manager for safely reviewing, backing up, and deleting old sessions from a browser UI or terminal CLI.
 
-Use it to clear old Codex session history, reclaim the space used by session artifacts, or remove local session traces without resetting the rest of your Codex setup.
+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.
 
-![UI of sessions, filters, and session details](https://raw.githubusercontent.com/mallikcheripally/session-steward/main/docs/session-steward-overview.jpg)
+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. Everything runs locally, and your session data stays on your computer.
 
-## Why Session Steward
+![Session Steward cleanup demo](https://raw.githubusercontent.com/mallikcheripally/session-steward/main/docs/session-steward-demo.gif)
 
-- Review local Codex sessions in a clear browser interface.
-- See linked subagents and affected local records before deletion.
-- Choose between focused session removal and a deeper local cleanup.
-- Keep an automatic backup of every cleanup operation.
-- Pause thorough cleanup when an unfamiliar storage format is found.
-- Verify that selected session artifacts were removed.
-- Use the same saved Codex folder in the browser and terminal interfaces.
+## Manage local Codex and Claude Code sessions
 
-Session Steward does not delete conversations stored in your ChatGPT account.
+- Review sessions in a browser UI or terminal CLI.
+- 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.
+- Inspect session details and affected records before deletion.
+- Choose standard or thorough cleanup.
+- Use custom Codex or Claude home folders across browser and terminal sessions.
 
-## Requirements
+## Built for large session libraries
 
-- macOS or Linux
-- [Node.js](https://nodejs.org/) 24.15 or newer
-- Local sessions created by Codex
+Current synthetic benchmarks on an arm64 Mac with Node.js 24.15.0:
 
-Git and a separate SQLite installation are not required. Session Steward uses the SQLite support included with Node.js.
+| Scenario | Scale | Time | Measured memory growth |
+| --- | ---: | ---: | ---: |
+| Paginated session listing | 50,003 sessions | 26 ms | 0.16 MB heap |
+| Session size index | 20,003 sessions | 85 ms cold, 9.7 ms warm | 30 MB peak RSS |
+| Transcript-only discovery | 5,003 sessions | 662 ms | 4.02 MB heap |
 
-## Install
+Results vary with hardware, disk speed, and session layout. The benchmark commands are included in the repository and use temporary synthetic data.
 
-Install Session Steward globally with npm:
+## 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.
+- Session contents are never sent over the network.
+
+At startup, Session Steward may contact the public npm registry to check for a newer version.
+
+### 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
+
+## Install and get started
+
+Session Steward supports macOS and Linux and requires Node.js 24.15 or newer. Git and a separate SQLite installation are not required.
+
+Install it globally:
 
 ```bash
 npm install --global session-steward
@@ -42,175 +72,199 @@ Then launch it:
 session-steward
 ```
 
-Session Steward opens its browser interface and listens only on `127.0.0.1`. It uses `~/.codex` by default.
-
-Keep the terminal open while using Session Steward. Press `Ctrl+C` when you want to stop it.
-
-To try it without a global installation:
+Or try it without installing:
 
 ```bash
 npx session-steward@latest
 ```
 
-## Quick start
+Session Steward opens in your browser, listens only on `127.0.0.1`, and detects `~/.codex` and `~/.claude` by default. Claude Desktop sessions are detected on macOS; Claude Code CLI sessions work on macOS and Linux.
+
+To clean up sessions:
 
-1. Run `session-steward`.
-2. Review the detected Codex sessions.
-3. Select one or more sessions.
-4. Choose a cleanup option and review the deletion preview.
+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.
 
-Each cleanup creates a backup inside your Codex folder under `session-steward-backups/`.
+Keep the terminal open while using Session Steward. Press `Ctrl+C` to stop it.
 
-## What you can adjust
+## Cleanup and recovery
 
-- Search by session name, workspace, or session ID.
-- Sort by recent activity, creation time, name, or workspace.
-- Show subagent and supporting sessions when you need the additional detail.
-- Choose standard or thorough cleanup for each deletion.
-- Change the Codex session folder and save that choice for later runs.
+### Standard cleanup
 
-## Safety model
+Recommended for routine removal. It removes supported transcripts, history, registry entries, logs, and linked session artifacts belonging to the selected sessions.
 
-Session Steward is intentionally conservative:
+### Thorough cleanup
 
-- All session inspection and cleanup happens on your computer.
-- Only recognized Codex storage is changed.
-- Unrecognized databases and changed storage layouts are reported but left untouched.
-- Thorough cleanup is paused when the local storage layout is not supported.
-- A backup is created before session data is changed.
-- Cleanup is checked afterward for remaining selected artifacts.
-- Authentication, plugins, caches, project files, worktrees, and unrelated sessions are not removed.
+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.
 
-At startup, Session Steward may contact the public npm registry to check for a newer release. It does not send session contents or other Codex data.
+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.
 
-Close selected Codex sessions before deleting them. Session Steward cannot currently determine whether a session is still being written to.
+### Recovery backups
 
-## Cleanup options
+A temporary backup is created inside the active provider folder under `session-steward-backups/`.
 
-### Standard cleanup
+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.
 
-Recommended for routine session removal. It removes the selected session registry entries, transcripts, history entries, session-index entries, logs, and linked subagents.
+Before restoring, the current versions of affected files are saved separately to provide another recovery point.
 
-### Thorough cleanup
+## Terminal CLI
 
-Choose this when you also want supported local references and generated records removed. It includes everything in standard cleanup, plus recognized ChatGPT Desktop references, memory outputs, and goal records.
+Start the interactive terminal interface:
 
-Thorough cleanup remains unavailable when Session Steward finds storage it does not recognize. Standard cleanup stays available for the supported records it can identify safely.
+```bash
+session-steward-cli
+```
 
-## Backups and recovery
+Use Claude Code instead of Codex:
 
-Completed cleanups keep their recovery backup on disk. If cleanup encounters a problem after creating its backup, Session Steward offers a guided restore from the cleanup progress screen.
+```bash
+session-steward-cli --provider claude-code
+```
 
-Before restoring, Session Steward saves the current versions of the affected files in a separate safety folder. This gives you a second recovery point if the restore itself is interrupted.
+List sessions as JSON:
 
-## Use a custom Codex home folder
+```bash
+session-steward-cli --json --limit 10
+```
 
-The browser interface shows the active Codex session folder. Choose **Change folder** to select another existing Codex folder and remember it for future browser and terminal sessions.
+<details>
+<summary>More terminal options</summary>
 
-For a one-time folder override:
+Show session and workspace storage totals:
 
 ```bash
-session-steward --codex-home /path/to/.codex
+session-steward-cli --overview
 ```
 
-The command-line override applies only to that run and does not replace the saved folder.
-
-Saved settings are stored at:
+Add `--json` when the output will be read by another tool.
 
-- macOS: `~/Library/Application Support/session-steward/config.json`
-- Linux: `$XDG_CONFIG_HOME/session-steward/config.json`, or `~/.config/session-steward/config.json` when `XDG_CONFIG_HOME` is not set
+Find sessions inactive for at least 60 days:
 
-## Terminal interface
+```bash
+session-steward-cli --inactive-days 60
+```
 
-For an interactive terminal workflow:
+Show only archived sessions:
 
 ```bash
-session-steward-cli
+session-steward-cli --archive-status archived
 ```
 
-To inspect a small JSON result without opening the browser:
+Show sessions from one exact workspace:
 
 ```bash
-session-steward-cli --json --limit 10
+session-steward-cli --workspace /path/to/project
 ```
 
-Run `session-steward-cli --help` for all available options. The terminal interface uses the same saved Codex folder as the browser interface.
+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.
+
+The interactive terminal accepts the same filters:
+
+```text
+inactive 30
+inactive 60
+inactive 90
+archive active
+archive archived
+workspace /path/to/project
+internals
+supporting
+cleanup standard
+cleanup thorough
+overview
+backups
+```
 
-## Common commands
+Run `inactive`, `archive`, or `workspace` without a value to clear that filter.
 
-Start without opening a browser:
+`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.
 
-```bash
-session-steward --no-open
-```
+</details>
+
+Use `session-steward-cli --help` to see all available options.
 
-Update to the latest release:
+## Use a custom provider folder
+
+The browser interface displays the active provider folder. Select **Change** to choose another existing folder and remember it for later browser and terminal sessions.
+
+For a one-time override:
 
 ```bash
-npm install --global session-steward@latest
+session-steward --codex-home /path/to/.codex
 ```
 
-Uninstall Session Steward:
+For Claude Code:
 
 ```bash
-npm uninstall --global session-steward
+session-steward --claude-home /path/to/.claude
 ```
 
-Uninstalling the package does not remove your Codex sessions, Session Steward backups, or saved folder preference.
+The command-line override applies only to that run and does not replace your saved folder.
 
-## Troubleshooting
+## Other commands
+
+Start without automatically opening the browser:
 
-### The browser did not open
+```bash
+session-steward --no-open
+```
 
-Run `session-steward --no-open`, then open the local address printed in the terminal.
+Update Session Steward:
 
-### No sessions were found
+```bash
+npm install --global session-steward@latest
+```
 
-Confirm that the displayed Codex folder contains your local session data. Use **Change folder** or pass `--codex-home` for a one-time override.
+Uninstall it:
 
-### Thorough cleanup is unavailable
+```bash
+npm uninstall --global session-steward
+```
 
-Open the compatibility details in Session Steward. New or changed local storage is left untouched until that format is supported. You can still use standard cleanup when its recognized records are supported.
+Uninstalling Session Steward does not remove provider sessions, recovery backups, or saved folder preferences.
 
-### Node.js is too old
+## Troubleshooting
 
-Install Node.js 24.15 or newer, then run `session-steward` again.
+- **The browser did not open:** Run `session-steward --no-open`, then open the local address shown 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.
+- **Your Node.js version is too old:** Install Node.js 24.15 or newer and run Session Steward again.
 
 ## Development
 
-Clone the repository and install its dependencies:
-
 ```bash
 git clone https://github.com/mallikcheripally/session-steward.git
 cd session-steward
 npm install
+npm test
+npm run build
 ```
 
-Useful commands:
+Scale benchmarks are also available:
 
 ```bash
-npm start
-npm test
 npm run benchmark:scale
+npm run benchmark:overview
+npm run benchmark:size
 npm run benchmark:discovery
 npm run benchmark:transcripts
-npm run build
-npm pack --dry-run --cache .npm-cache
 ```
 
-Tests use temporary synthetic Codex data. They do not read or change your local Codex sessions.
+Tests and benchmarks use temporary synthetic session data. They do not read or modify your local sessions.
 
-## Roadmap
+## Support
 
-Codex is supported today. Claude Code is planned as the next provider integration.
+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.
 
-## Support
+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.
 
-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 yet recognize.
+See the [changelog](https://github.com/mallikcheripally/session-steward/blob/main/CHANGELOG.md) for published release history.
 
-Session Steward is an independent project and is not affiliated with or endorsed by OpenAI.
+Session Steward is an independent project and is not affiliated with or endorsed by OpenAI or Anthropic.
 
 ## License
 

package/bin/session-steward-cli.mjs

@@ -11,28 +11,55 @@ const { runCli } = await import("../lib/cli.mjs");
 const { values } = parseArgs({
   allowPositionals: false,
   options: {
+    "archive-status": {
+      type: "string",
+    },
+    backups: {
+      type: "boolean",
+    },
     "codex-home": {
       type: "string",
     },
+    "claude-home": {
+      type: "string",
+    },
+    cleanup: {
+      type: "string",
+    },
     help: {
       short: "h",
       type: "boolean",
     },
+    "inactive-days": {
+      type: "string",
+    },
     "include-internals": {
       type: "boolean",
     },
+    "include-supporting": {
+      type: "boolean",
+    },
     json: {
       type: "boolean",
     },
     limit: {
       type: "string",
     },
+    overview: {
+      type: "boolean",
+    },
+    provider: {
+      type: "string",
+    },
     search: {
       type: "string",
     },
     sort: {
       type: "string",
     },
+    workspace: {
+      type: "string",
+    },
   },
 });
 
@@ -43,24 +70,39 @@ const numericLimit =
 
 async function main() {
   const help = values.help ?? false;
-  let codexHome = values["codex-home"];
+  if (help) {
+    await runCli({ help: true });
+    return;
+  }
+  const { createProviderSettings } = await import("../lib/settings.mjs");
+  let settings = await createProviderSettings();
+  const providerId = values.provider || settings.getActiveProviderId();
+  if (!["codex", "claude-code"].includes(providerId)) throw new Error("Provider must be codex or claude-code.");
+  const homeOption = providerId === "codex" ? values["codex-home"] : values["claude-home"];
 
-  if (!help) {
-    const { createProviderSettings } = await import("../lib/settings.mjs");
-    const settings = await createProviderSettings({
-      providerHomeOverrides: codexHome === undefined ? {} : { codex: codexHome },
+  if (homeOption !== undefined) {
+    settings = await createProviderSettings({
+      providerHomeOverrides: { [providerId]: homeOption },
     });
-    codexHome = settings.getHome("codex");
   }
+  const providerHome = settings.getHome(providerId);
 
   await runCli({
-    codexHome,
+    archiveStatus: values["archive-status"],
+    backups: values.backups ?? false,
+    cleanup: values.cleanup,
     help,
+    inactiveDays: values["inactive-days"],
     includeInternals: values["include-internals"] ?? false,
+    includeSupporting: values["include-supporting"] ?? false,
     json: values.json ?? false,
     limit: numericLimit,
+    overview: values.overview ?? false,
+    providerHome,
+    providerId,
     search: values.search ?? "",
     sort: values.sort ?? "updated",
+    workspace: values.workspace,
   });
 }
 

package/bin/session-steward.mjs

@@ -13,6 +13,7 @@ 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" },
@@ -25,6 +26,7 @@ if (values.help) {
 
 Options:
   --codex-home <path>  Use a custom Codex session folder
+  --claude-home <path> Use a custom Claude session folder
   --port <number>      Use a specific local port
   --no-open            Start without opening a browser
   -h, --help           Show this help
@@ -47,6 +49,7 @@ if (availableUpdate) {
 }
 
 const server = await startLocalServer({
+  claudeHome: values["claude-home"],
   codexHome: values["codex-home"],
   port,
 });