session-steward 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 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
@@ -137,6 +143,7 @@
 - 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

package/README.md

@@ -4,7 +4,7 @@
 [![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. It also includes an MCP server for inspecting sessions with AI.
+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.
 
@@ -14,7 +14,7 @@ Session Steward makes session cleanup safer by finding those records, showing wh
 
 ## 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.
@@ -22,7 +22,6 @@ Session Steward makes session cleanup safer by finding those records, showing wh
 - 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.
-- Let compatible local MCP clients inspect sessions and help identify what is worth reviewing.
 - Choose standard or thorough cleanup.
 - Use custom Codex or Claude home folders across browser and terminal sessions.
 
@@ -34,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.
-- Browser and terminal cleanup stay local and do not upload session contents.
+- 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.
 
@@ -207,34 +206,45 @@ Run `inactive`, `archive`, or `workspace` without a value to clear that filter.
 
 Use `session-steward-cli --help` to see all available options.
 
-## Read-only MCP server
+## Clean up sessions with ChatGPT or Claude
 
-Session Steward includes `session-steward-mcp`, a local MCP server for Codex,
-and Claude Code. It can list and inspect sessions, timelines, storage, and
-token usage. It cannot delete, back up, restore, or change anything.
+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.
 
-Once configured, you can ask naturally:
-
-- “Find old chats I have not used in 2 months that are over 500 MB.”
-- “Show sessions from project x workspace, sorted by size, inactive for a month.”
-- “Show the timeline and token usage for this session.”
-
-Install Session Steward globally first, then register it with the clients you
-use.
-
-For Codex:
+Connect it to ChatGPT and Codex:
 
 ```bash
 codex mcp add session-steward -- session-steward-mcp
 ```
 
-For Claude Code:
+Connect it to Claude Code:
 
 ```bash
 claude mcp add --scope user session-steward -- session-steward-mcp
 ```
 
-Check or remove the configuration at any time:
+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
@@ -244,12 +254,7 @@ claude mcp list
 claude mcp remove --scope user session-steward
 ```
 
-Removing the MCP configuration does not uninstall Session Steward or change any
-sessions. Use the normal npm uninstall command only if you also want to remove
-the package.
-
-For another compatible client, configure a local `stdio` server named
-`session-steward` with `session-steward-mcp` as its command:
+For another MCP client, add a local server named `session-steward`:
 
 ```json
 {
@@ -261,31 +266,14 @@ For another compatible client, configure a local `stdio` server named
 }
 ```
 
-### Custom provider folders
+The MCP server uses the same provider folders selected in the browser or
+terminal.
 
-The MCP server uses the same saved Codex and Claude home folders as the browser
-and terminal interfaces. You can override either folder in the MCP command:
-
-```bash
-codex mcp add session-steward -- session-steward-mcp \
-  --codex-home /path/to/.codex \
-  --claude-home /path/to/.claude
-```
+### Privacy
 
-### Privacy and access
-
-- The MCP server runs locally with your user account's file permissions.
-- Every tool call must choose `codex` or `claude-code`; it does not combine the
-  providers silently.
-- Lists and timelines are bounded, and provider database and transcript paths
-  are omitted from results.
-- Timeline results can contain session messages, commands, file names, and
-  workspace paths. Only request a timeline when that content is appropriate to
-  share with the configured client.
-- Session Steward does not upload MCP results itself. Your MCP client may send
-  tool results to its AI provider under that product's privacy terms.
-- MCP tools are read-only. Cleanup remains available only through the browser UI
-  and terminal CLI, with the existing review, backup, and verification flow.
+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
 

package/bin/session-steward-mcp.mjs

@@ -20,8 +20,8 @@ const { values } = parseArgs({
 if (values.help) {
   process.stdout.write(`Usage: session-steward-mcp [options]
 
-Run Session Steward's read-only MCP server over stdio. MCP clients start and
-stop this process automatically.
+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
@@ -38,7 +38,7 @@ if (values.version) {
 }
 
 const { createProviderSettings } = await import("../lib/settings.mjs");
-const { serveReadOnlyMcp } = await import("../lib/mcp.mjs");
+const { serveMcp } = await import("../lib/mcp.mjs");
 const providerHomeOverrides = {};
 
 if (values["codex-home"] !== undefined) {
@@ -49,7 +49,7 @@ if (values["claude-home"] !== undefined) {
 }
 
 const settings = await createProviderSettings({ providerHomeOverrides });
-const handle = serveReadOnlyMcp({
+const handle = serveMcp({
   onerror: (error) => process.stderr.write(`Session Steward MCP error: ${error.message}\n`),
   settings,
 });

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 };
+}