Session Steward (sessionsteward)

Versioned snapshots for agent working state. Coding agents silently degrade: compaction drops constraints, and one "remember this" can overwrite your 30-line CLAUDE.md with a single bullet — no warning, no undo. sessionsteward git-versions your agent config + memory files on every change: instant undo, pre-compaction snapshots, and a context-diet report showing what's eating the window.

Scope: session ops (snapshots, undo, compaction guard) — not memory storage. That boundary stays clean.

Install

Zero dependencies — Python 3.10+ stdlib only (uses your system's git).

git clone <repo> && cd sessionsteward
# no-install alias (run from the repo root):
alias sessionsteward="python3 -m sessionsteward"

Or install it properly (console script sessionsteward):

pip install .

Usage

sessionsteward init                        # set up the snapshots repo
sessionsteward watch --add NOTES.md ~/x.md # watch extra paths

sessionsteward snap -m "before refactor"   # snapshot now
sessionsteward precompact                  # snapshot before compaction
sessionsteward watch                       # daemon: auto-snapshot on change

sessionsteward log                         # list snapshots (this project only)
sessionsteward diff                        # what changed (e.g. what compaction dropped)
sessionsteward undo                        # restore the previous snapshot
sessionsteward restore <sha>               # restore a specific snapshot
sessionsteward diet                        # what's eating the context window
sessionsteward install-hooks               # print Claude Code hooks JSON
sessionsteward install-hooks --write       # merge it into ~/.claude/settings.json

The horror-story scenario, fixed:

$ sessionsteward snap -m "before letting the agent edit memory"
$ # agent overwrites your 30-line CLAUDE.md with one bullet
$ sessionsteward undo
undone 1 step(s) -> a3f9c21
  /home/you/proj/CLAUDE.md

Safety rules: empty snaps are skipped (no noise commits); undo/restore never delete — files that didn't exist in the target snapshot are moved to ~/.sessionsteward/trash/ instead, directories included. log/diff/undo/restore are scoped to the current project (--root, default: cwd): snapshots record their project root, and a restore of a snapshot from another project is refused rather than clobbering your files. Undoing (or restoring) with unsaved changes first snapshots the current state as pre-undo/pre-restore, so every undo is reversible — redo is restore of that snapshot.

Ignored on every snap and by the watch daemon: *.log, *transcript*, __pycache__, .git, node_modules (transcripts would otherwise balloon the snapshots repo).

Claude Code hooks

sessionsteward install-hooks            # print the hooks JSON + where it goes
sessionsteward install-hooks --write   # merge into ~/.claude/settings.json

This wires PreCompact → sessionsteward precompact and SessionStart → sessionsteward snap -m "session start". --write merges into the existing settings file without clobbering your other hooks (re-running is a no-op).

Context diet

# Context diet

Watched files: 3, total ~12,400 chars (~3,100 tokens)

## Biggest files
| file | chars | lines |
...
## Duplicated content (4 lines in 2+ files)
- _Be helpful and concise in all responses_ …
  - `/proj/CLAUDE.md`
  - `/proj/.claude/settings.json`

Suggested hook wiring

• Pre-compaction: run sessionsteward precompact (or add it to your agent's pre-compact hook) — then sessionsteward diff afterwards to see exactly what the compaction dropped.
• Session start: sessionsteward snap -m "session start".
• Memory writes: point the steward at the same files your agent's memory hook writes.

Tests

python3 -m unittest discover -s tests   # 24 tests, temp dirs only

License

TBD