Session Steward MCP server

Session Steward

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.

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.

• 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.

Try Session Steward locally

Try the browser app for one run without installing it globally:

Session Steward requires Node.js 24.15 or newer.

npx session-steward@latest

The browser app listens only on 127.0.0.1 and does not upload session contents.

For ongoing use, install it globally:

npm install --global session-steward

The global install provides four commands:

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.

Find old and large Codex and Claude Code sessions

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.

You can:

• 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.

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.

Why not just delete sessions one at a time?

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.

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.

Shortened. The full README is on GitHub.