session-steward 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.10.0] - 2026-08-30
+
+### Added
+
+- Added full MCP support for finding, inspecting, cleaning, restoring, and automatically cleaning Codex and Claude Code sessions.
+
+## [0.9.0] - 2026-08-27
+
+### Added
+
+- Add MCP server for Codex, Claude Code, and other local clients. It can inspect sessions, storage, timelines, and token usage; cleanup remains in the browser and terminal with the existing review and backup safeguards.
+- MCP session searches understand inactivity, workspace, and minimum transcript size filters.
+
 ## [0.8.0] - 2026-08-23
 
 ### Added
@@ -130,6 +143,8 @@
 - Support for custom Codex home folders and a saved folder preference.
 - Streaming and bounded-memory discovery for large session collections and transcripts.
 
+[0.10.0]: https://github.com/mallikcheripally/session-steward/compare/v0.9.0...v0.10.0
+[0.9.0]: https://github.com/mallikcheripally/session-steward/compare/v0.8.0...v0.9.0
 [0.8.0]: https://github.com/mallikcheripally/session-steward/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/mallikcheripally/session-steward/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/mallikcheripally/session-steward/compare/v0.5.2...v0.6.0

package/README.md

@@ -4,17 +4,17 @@
 [![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.
+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.
 
 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.
 
-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.
+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.
 
 ![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 sessions in a browser UI or terminal CLI.
+- 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.
@@ -33,7 +33,7 @@ Session Steward makes session cleanup safer by finding those records, showing wh
 - 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.
+- Cleanup stays local and does not upload session contents.
 
 At startup, Session Steward may contact the public npm registry to check for a newer version.
 
@@ -206,6 +206,75 @@ Run `inactive`, `archive`, or `workspace` without a value to clear that filter.
 
 Use `session-steward-cli --help` to see all available options.
 
+## Clean up sessions with ChatGPT or Claude
+
+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.
+
+Connect it to ChatGPT and Codex:
+
+```bash
+codex mcp add session-steward -- session-steward-mcp
+```
+
+Connect it to Claude Code:
+
+```bash
+claude mcp add --scope user session-steward -- session-steward-mcp
+```
+
+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.”
+- “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
+
+claude mcp list
+claude mcp remove --scope user session-steward
+```
+
+For another MCP client, add a local server named `session-steward`:
+
+```json
+{
+  "mcpServers": {
+    "session-steward": {
+      "command": "session-steward-mcp"
+    }
+  }
+}
+```
+
+The MCP server uses the same provider folders selected in the browser or
+terminal.
+
+### Privacy
+
+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.
+
 ## 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.

package/bin/session-steward-mcp.mjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+
+import { parseArgs } from "node:util";
+
+import packageMetadata from "../package.json" with { type: "json" };
+import { assertSupportedNode } from "../lib/runtime.mjs";
+
+assertSupportedNode();
+
+const { values } = parseArgs({
+  allowPositionals: false,
+  options: {
+    "claude-home": { type: "string" },
+    "codex-home": { type: "string" },
+    help: { short: "h", type: "boolean" },
+    version: { short: "v", type: "boolean" },
+  },
+});
+
+if (values.help) {
+  process.stdout.write(`Usage: session-steward-mcp [options]
+
+Run Session Steward's MCP server over stdio. MCP clients start and stop this
+process automatically. Destructive tools use the client's normal approval flow.
+
+Options:
+  --codex-home <path>  Use a custom Codex session folder
+  --claude-home <path> Use a custom Claude session folder
+  -h, --help           Show this help
+  -v, --version        Show the installed version
+`);
+  process.exit(0);
+}
+
+if (values.version) {
+  process.stdout.write(`${packageMetadata.version}\n`);
+  process.exit(0);
+}
+
+const { createProviderSettings } = await import("../lib/settings.mjs");
+const { serveMcp } = await import("../lib/mcp.mjs");
+const providerHomeOverrides = {};
+
+if (values["codex-home"] !== undefined) {
+  providerHomeOverrides.codex = values["codex-home"];
+}
+if (values["claude-home"] !== undefined) {
+  providerHomeOverrides["claude-code"] = values["claude-home"];
+}
+
+const settings = await createProviderSettings({ providerHomeOverrides });
+const handle = serveMcp({
+  onerror: (error) => process.stderr.write(`Session Steward MCP error: ${error.message}\n`),
+  settings,
+});
+let closing = false;
+
+async function close() {
+  if (closing) return;
+  closing = true;
+  await handle.close();
+}
+
+process.once("SIGINT", () => void close());
+process.once("SIGTERM", () => void close());

package/bin/session-steward-scheduler.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+
+import { parseArgs } from "node:util";
+
+import { assertSupportedNode } from "../lib/runtime.mjs";
+
+assertSupportedNode();
+
+const { values } = parseArgs({
+  allowPositionals: false,
+  options: {
+    "config-directory": { type: "string" },
+    help: { short: "h", type: "boolean" },
+    "run-due": { type: "boolean" },
+    start: { type: "boolean" },
+    status: { type: "boolean" },
+    stop: { type: "boolean" },
+  },
+});
+
+if (values.help) {
+  process.stdout.write(`Usage: session-steward-scheduler <option>
+
+Options:
+  --start    Start automatic cleanup and enable it after restart
+  --stop     Stop automatic cleanup and remove its startup task
+  --status   Show whether automatic cleanup is running
+  --run-due  Run due cleanup schedules once and exit
+  --config-directory <path> Use a specific Session Steward settings folder
+  -h, --help Show this help
+`);
+} else if ([values["run-due"], values.start, values.status, values.stop].filter(Boolean).length !== 1) {
+  process.stderr.write("Choose exactly one of --start, --stop, --status, or --run-due.\n");
+  process.exitCode = 1;
+} else if (values["run-due"]) {
+  const { createCleanupScheduleStore, runDueCleanupSchedules } = await import(
+    "../lib/cleanup-schedules.mjs"
+  );
+  const { createProviderSettings } = await import("../lib/settings.mjs");
+  const settings = await createProviderSettings({
+    configDirectory: values["config-directory"],
+  });
+  const scheduleStore = createCleanupScheduleStore({
+    configDirectory: settings.getConfigDirectory(),
+  });
+  const results = await runDueCleanupSchedules({ scheduleStore, settings });
+  if (results.some((result) => ["failed", "recovery-failed"].includes(result.status))) {
+    process.exitCode = 1;
+  }
+} else {
+  const { createCleanupSchedulerService } = await import(
+    "../lib/cleanup-scheduler-service.mjs"
+  );
+  const service = createCleanupSchedulerService({
+    configDirectory: values["config-directory"],
+  });
+  const status = values.start
+    ? await service.start()
+    : values.stop ? await service.stop() : await service.status();
+  process.stdout.write(`Automatic cleanup is ${status.running ? "running" : "stopped"}.\n`);
+}

package/lib/cleanup-scheduler-service.mjs

@@ -0,0 +1,205 @@
+import { execFile as execFileCallback } from "node:child_process";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+
+import { getDefaultConfigDirectory } from "./platform.mjs";
+
+const execFile = promisify(execFileCallback);
+const LABEL = "com.mallikcheripally.session-steward.cleanup";
+const WINDOWS_TASK_NAME = "Session Steward Cleanup";
+const RUNNER_PATH = fileURLToPath(new URL("../bin/session-steward-scheduler.mjs", import.meta.url));
+
+function xml(value) {
+  return String(value)
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&apos;");
+}
+
+function systemdArgument(value) {
+  return `"${String(value)
+    .replaceAll("%", "%%")
+    .replaceAll("\\", "\\\\")
+    .replaceAll('"', '\\"')
+    .replaceAll("$", "\\$")
+    .replaceAll("`", "\\`")}"`;
+}
+
+function windowsArgument(value) {
+  return `"${String(value).replaceAll(/(\\*)"/gu, "$1$1\\\"").replaceAll(/(\\+)$/gu, "$1$1")}"`;
+}
+
+async function writePrivateFile(filePath, contents) {
+  await fs.mkdir(path.dirname(filePath), { mode: 0o700, recursive: true });
+  await fs.writeFile(filePath, contents, { encoding: "utf8", mode: 0o600 });
+}
+
+async function exists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function createCleanupSchedulerService({
+  configDirectory = getDefaultConfigDirectory(),
+  environment = process.env,
+  execute = execFile,
+  home = os.homedir(),
+  nodePath = process.execPath,
+  platform = process.platform,
+  runnerPath = RUNNER_PATH,
+  userId = typeof process.getuid === "function" ? process.getuid() : null,
+} = {}) {
+  const launchAgentPath = path.join(home, "Library", "LaunchAgents", `${LABEL}.plist`);
+  const xdgConfigHome = path.isAbsolute(environment.XDG_CONFIG_HOME || "")
+    ? environment.XDG_CONFIG_HOME
+    : path.join(home, ".config");
+  const systemdDirectory = path.join(xdgConfigHome, "systemd", "user");
+  const systemdServicePath = path.join(systemdDirectory, "session-steward-cleanup.service");
+  const systemdTimerPath = path.join(systemdDirectory, "session-steward-cleanup.timer");
+
+  async function command(commandName, args, { allowFailure = false } = {}) {
+    try {
+      await execute(commandName, args, { windowsHide: true });
+      return true;
+    } catch (error) {
+      if (allowFailure) return false;
+      throw new Error("Session Steward could not update the automatic cleanup scheduler.", {
+        cause: error,
+      });
+    }
+  }
+
+  async function start() {
+    if (platform === "darwin") {
+      if (!Number.isSafeInteger(userId)) throw new Error("Session Steward could not identify this user.");
+      const target = `gui/${userId}`;
+      await writePrivateFile(launchAgentPath, `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>${LABEL}</string>
+  <key>ProgramArguments</key><array>
+    <string>${xml(nodePath)}</string>
+    <string>${xml(runnerPath)}</string>
+    <string>--run-due</string>
+    <string>--config-directory</string>
+    <string>${xml(configDirectory)}</string>
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>StartInterval</key><integer>900</integer>
+</dict></plist>
+`);
+      await command("launchctl", ["bootout", `${target}/${LABEL}`], { allowFailure: true });
+      await command("launchctl", ["bootstrap", target, launchAgentPath]);
+      await command("launchctl", ["enable", `${target}/${LABEL}`]);
+      return status();
+    }
+
+    if (platform === "linux") {
+      await writePrivateFile(systemdServicePath, `[Unit]
+Description=Session Steward automatic cleanup
+
+[Service]
+Type=oneshot
+ExecStart=${systemdArgument(nodePath)} ${systemdArgument(runnerPath)} --run-due --config-directory ${systemdArgument(configDirectory)}
+`);
+      await writePrivateFile(systemdTimerPath, `[Unit]
+Description=Run Session Steward automatic cleanup
+
+[Timer]
+OnBootSec=2min
+OnUnitActiveSec=15min
+Persistent=true
+
+[Install]
+WantedBy=timers.target
+`);
+      await command("systemctl", ["--user", "daemon-reload"]);
+      await command("systemctl", ["--user", "enable", "--now", "session-steward-cleanup.timer"]);
+      return status();
+    }
+
+    if (platform === "win32") {
+      const taskCommand = [
+        nodePath,
+        runnerPath,
+        "--run-due",
+        "--config-directory",
+        configDirectory,
+      ].map(windowsArgument).join(" ");
+      await command("schtasks", [
+        "/Create", "/F", "/SC", "MINUTE", "/MO", "15",
+        "/TN", WINDOWS_TASK_NAME,
+        "/TR", taskCommand,
+      ]);
+      return status();
+    }
+
+    throw new Error(`Automatic cleanup is not supported on ${platform}.`);
+  }
+
+  async function stop() {
+    if (platform === "darwin") {
+      if (Number.isSafeInteger(userId)) {
+        await command("launchctl", ["bootout", `gui/${userId}/${LABEL}`], {
+          allowFailure: true,
+        });
+      }
+      await fs.rm(launchAgentPath, { force: true });
+      return status();
+    }
+    if (platform === "linux") {
+      await command("systemctl", ["--user", "disable", "--now", "session-steward-cleanup.timer"], {
+        allowFailure: true,
+      });
+      await Promise.all([
+        fs.rm(systemdServicePath, { force: true }),
+        fs.rm(systemdTimerPath, { force: true }),
+      ]);
+      await command("systemctl", ["--user", "daemon-reload"], { allowFailure: true });
+      return status();
+    }
+    if (platform === "win32") {
+      await command("schtasks", ["/Delete", "/F", "/TN", WINDOWS_TASK_NAME], {
+        allowFailure: true,
+      });
+      return status();
+    }
+    return { platform, running: false, supported: false };
+  }
+
+  async function status() {
+    if (platform === "darwin") {
+      const running = Number.isSafeInteger(userId)
+        ? await command("launchctl", ["print", `gui/${userId}/${LABEL}`], { allowFailure: true })
+        : false;
+      return { platform, running, supported: true };
+    }
+    if (platform === "linux") {
+      const configured = await exists(systemdTimerPath);
+      const running = configured
+        ? await command("systemctl", ["--user", "is-active", "--quiet", "session-steward-cleanup.timer"], {
+          allowFailure: true,
+        })
+        : false;
+      return { platform, running, supported: true };
+    }
+    if (platform === "win32") {
+      const running = await command("schtasks", ["/Query", "/TN", WINDOWS_TASK_NAME], {
+        allowFailure: true,
+      });
+      return { platform, running, supported: true };
+    }
+    return { platform, running: false, supported: false };
+  }
+
+  return { start, status, stop };
+}