session-steward 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [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
+
+- Session details now show how many tokens a Codex or Claude session used, with clear breakdowns for input, cache use, output, reasoning, models, and inherited work in forked sessions.
+- The same token breakdown is available in the terminal with `--tokens`.
+
 ## [0.7.0] - 2026-08-20
 
 ### Added
@@ -123,6 +137,8 @@
 - Support for custom Codex home folders and a saved folder preference.
 - Streaming and bounded-memory discovery for large session collections and transcripts.
 
+[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
 [0.5.2]: https://github.com/mallikcheripally/session-steward/compare/v0.5.1...v0.5.2

package/README.md

@@ -4,11 +4,11 @@
 [![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. It also includes an MCP server for inspecting sessions with AI.
 
 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)
 
@@ -21,6 +21,8 @@ Session Steward makes session cleanup safer by finding those records, showing wh
 - Filter active or archived sessions by workspace, name, or session ID.
 - 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.
 
@@ -32,7 +34,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.
+- Browser and terminal cleanup stay local and do not upload session contents.
 
 At startup, Session Steward may contact the public npm registry to check for a newer version.
 
@@ -165,6 +167,20 @@ With `--json`, each session carries its own `events`, plus a `coverage` summary
 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
@@ -176,6 +192,7 @@ archive archived
 workspace /path/to/project
 internals
 supporting
+tokens
 cleanup standard
 cleanup thorough
 overview
@@ -190,6 +207,86 @@ 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
+
+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.
+
+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:
+
+```bash
+codex mcp add session-steward -- session-steward-mcp
+```
+
+For Claude Code:
+
+```bash
+claude mcp add --scope user session-steward -- session-steward-mcp
+```
+
+Check or remove the configuration at any time:
+
+```bash
+codex mcp list
+codex mcp remove session-steward
+
+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:
+
+```json
+{
+  "mcpServers": {
+    "session-steward": {
+      "command": "session-steward-mcp"
+    }
+  }
+}
+```
+
+### Custom provider folders
+
+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 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.
+
 ## 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-cli.mjs

@@ -29,6 +29,9 @@ const { values } = parseArgs({
     events: {
       type: "boolean",
     },
+    tokens: {
+      type: "boolean",
+    },
     "events-limit": {
       type: "string",
     },
@@ -116,6 +119,7 @@ async function main() {
     providerId,
     search: values.search ?? "",
     sort: values.sort ?? "updated",
+    tokens: values.tokens ?? false,
     workspace: values.workspace,
   });
 }

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 read-only MCP server over stdio. MCP clients start and
+stop this process automatically.
+
+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 { serveReadOnlyMcp } = 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 = serveReadOnlyMcp({
+  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());