sessionsteward 0.1.0__tar.gz

sessionsteward-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Calas Automations Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sessionsteward-0.1.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: sessionsteward
+Version: 0.1.0
+Summary: Versioned snapshots for agent working state: instant undo for CLAUDE.md and friends.
+Author: Calas Automations Inc.
+License: MIT
+Project-URL: Homepage, https://github.com/calasdan-sketch/sessionsteward
+Project-URL: Issues, https://github.com/calasdan-sketch/sessionsteward/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# 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).
+
+```bash
+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`):
+
+```bash
+pip install .
+```
+
+## Usage
+
+```bash
+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:
+
+```bash
+$ 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
+
+```bash
+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
+
+```bash
+python3 -m unittest discover -s tests   # 24 tests, temp dirs only
+```
+
+## License
+
+TBD

sessionsteward-0.1.0/README.md

@@ -0,0 +1,117 @@
+# 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).
+
+```bash
+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`):
+
+```bash
+pip install .
+```
+
+## Usage
+
+```bash
+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:
+
+```bash
+$ 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
+
+```bash
+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
+
+```bash
+python3 -m unittest discover -s tests   # 24 tests, temp dirs only
+```
+
+## License
+
+TBD

sessionsteward-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sessionsteward"
+version = "0.1.0"
+description = "Versioned snapshots for agent working state: instant undo for CLAUDE.md and friends."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{name = "Calas Automations Inc."}]
+license = {text = "MIT"}
+
+
+[project.urls]
+Homepage = "https://github.com/calasdan-sketch/sessionsteward"
+Issues = "https://github.com/calasdan-sketch/sessionsteward/issues"
+
+[project.scripts]
+sessionsteward = "sessionsteward.cli:main"

sessionsteward-0.1.0/sessionsteward/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

sessionsteward-0.1.0/sessionsteward/cli.py

@@ -0,0 +1,244 @@
+"""Session steward: 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.
+
+Scope note: this is *session ops* (snapshots, undo, compaction guard).
+Memory *storage* is OneMemory's job — the boundary stays clean.
+
+  sessionsteward init                  # set up the snapshots repo
+  sessionsteward watch --add CLAUDE.md # watch extra paths (also: ~/..., /abs/...)
+  sessionsteward snap -m "before refactor"
+  sessionsteward precompact            # snapshot before compaction
+  sessionsteward log                   # list snapshots
+  sessionsteward diff [sha1] [sha2]    # 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 [--write]  # Claude Code hooks JSON
+  sessionsteward watch                 # daemon: auto-snapshot on change
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import time
+
+from . import core as core_mod
+from . import diet as diet_mod
+
+VERSION = "0.1.0"
+
+CLAUDE_SETTINGS = os.path.expanduser("~/.claude/settings.json")
+
+
+def cmd_init(args) -> int:
+    repo = core_mod.init_repo()
+    print(f"snapshots repo: {repo}")
+    print("watching (defaults): " + ", ".join(core_mod.DEFAULT_WATCH))
+    print("add more: sessionsteward watch --add <path>")
+    return 0
+
+
+def cmd_watch_add(args) -> int:
+    core_mod.init_repo()
+    cfg = core_mod.load_config()
+    for p in args.add:
+        if p not in cfg["watch"]:
+            cfg["watch"].append(p)
+    core_mod.save_config(cfg)
+    print("watching: " + ", ".join(cfg["watch"] or core_mod.DEFAULT_WATCH))
+    return 0
+
+
+def cmd_snap(args) -> int:
+    sha = core_mod.snap(args.root, args.message or "manual snapshot")
+    print(f"snapshot {sha[:7]}")
+    return 0
+
+
+def cmd_precompact(args) -> int:
+    sha = core_mod.snap(args.root, "pre-compaction snapshot")
+    print(f"pre-compaction snapshot {sha[:7]} — "
+          f"`sessionsteward diff {sha[:7]}` after, to see what was dropped")
+    return 0
+
+
+def cmd_log(args) -> int:
+    if not core_mod.repo_ready():
+        print("no snapshots yet — run `sessionsteward init` first")
+        return 0
+    for s in core_mod.log(args.limit, project_root=args.root):
+        print(f"{s['sha'][:7]}  {s['date'][:16]}  {s['message']}")
+    return 0
+
+
+def cmd_diff(args) -> int:
+    if not core_mod.repo_ready():
+        print("no snapshots yet")
+        return 2
+    snaps = core_mod.log(50, project_root=args.root)
+    sha1 = args.sha1 or (snaps[1]["sha"] if len(snaps) > 1 else None)
+    sha2 = args.sha2 or "HEAD"
+    if not sha1:
+        print("only one snapshot — nothing to diff")
+        return 0
+    out = core_mod.diff(sha1, sha2)
+    kept = [ln for ln in out.splitlines() if ln[:1] in "+-"
+            and not ln.startswith(("+++", "---"))]
+    sys.stdout.write("\n".join(kept[:200]) + ("\n" if kept else "(no changes)\n"))
+    return 0
+
+
+def cmd_undo(args) -> int:
+    if not core_mod.repo_ready():
+        print("no snapshots yet")
+        return 2
+    snaps = core_mod.log(50, project_root=args.root)
+    if not snaps:
+        print("nothing to restore — no snapshots yet")
+        return 1
+    if core_mod.worktree_matches_snapshot(snaps[0]["sha"], args.root):
+        # Clean state: the current state is already snapshotted, so undo
+        # needs no pre-snap and redo is just `restore` of snaps[0].
+        if len(snaps) < 2:
+            print("only one snapshot — nothing to undo to")
+            return 0
+        target = snaps[min(args.steps, len(snaps) - 1)]["sha"]
+    else:
+        # Dirty state: snapshot it first ("pre-undo") so undo is
+        # reversible — redo is `restore` of the pre-undo snapshot.
+        core_mod.snap(args.root, "pre-undo")
+        snaps = core_mod.log(50, project_root=args.root)
+        target = snaps[min(args.steps, len(snaps) - 1)]["sha"]
+    try:
+        restored = core_mod.restore(target, project_root=args.root)
+    except core_mod.NothingToRestoreError as e:
+        print(e)
+        return 1
+    except core_mod.CrossProjectError as e:
+        print(f"error: {e}")
+        return 1
+    print(f"undone {args.steps} step(s) -> {target[:7]}")
+    for r in restored:
+        print(f"  {r}")
+    return 0
+
+
+def cmd_restore(args) -> int:
+    if not core_mod.repo_ready():
+        print("no snapshots yet")
+        return 2
+    # Validate before the pre-restore snap so a bad sha doesn't pollute log.
+    try:
+        core_mod.check_restore(args.sha, args.root)
+    except core_mod.NothingToRestoreError as e:
+        print(e)
+        return 1
+    except core_mod.CrossProjectError as e:
+        print(f"error: {e}")
+        return 1
+    # Redo support: if the current state isn't snapshotted yet, snapshot
+    # it first ("pre-restore") so the restore is reversible.
+    snaps = core_mod.log(50, project_root=args.root)
+    if snaps and not core_mod.worktree_matches_snapshot(snaps[0]["sha"],
+                                                        args.root):
+        core_mod.snap(args.root, "pre-restore")
+    restored = core_mod.restore(args.sha, project_root=args.root)
+    print(f"restored {args.sha[:7]}")
+    for r in restored:
+        print(f"  {r}")
+    return 0
+
+
+def cmd_diet(args) -> int:
+    print(diet_mod.render(diet_mod.analyze(args.root)))
+    return 0
+
+
+def cmd_install_hooks(args) -> int:
+    payload = core_mod.build_hooks_json()
+    print(json.dumps(payload, indent=2))
+    print()
+    print("Copy the JSON above into the \"hooks\" section of "
+          "~/.claude/settings.json, or re-run with --write to merge it "
+          "automatically (existing settings are preserved).")
+    print("Wiring: PreCompact -> `sessionsteward precompact`, "
+          "SessionStart -> `sessionsteward snap -m \"session start\"`.")
+    if args.write:
+        path = core_mod.write_hooks_file(CLAUDE_SETTINGS)
+        print(f"merged hooks into {path}")
+    return 0
+
+
+def cmd_watch(args) -> int:
+    core_mod.init_repo()
+    print(f"watching for changes (every {args.interval}s, Ctrl-C to stop)…")
+    mtimes = core_mod.file_mtimes(core_mod.watched_paths(args.root))
+    try:
+        while True:
+            time.sleep(args.interval)
+            now = core_mod.file_mtimes(core_mod.watched_paths(args.root))
+            if now != mtimes:
+                sha = core_mod.snap(args.root, "auto: files changed")
+                print(f"change detected -> snapshot {sha[:7]}")
+                mtimes = now
+    except KeyboardInterrupt:
+        print("\nstopped.")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="sessionsteward", description=__doc__)
+    p.add_argument("--version", action="version", version=f"%(prog)s {VERSION}")
+    p.add_argument("--root", default=os.getcwd(),
+                   help="Project root for relative watch paths.")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    sub.add_parser("init", help="Set up the snapshots repo.")
+    wa = sub.add_parser("watch", help="Watch daemon / manage watch list.")
+    wa.add_argument("--add", nargs="+", default=None,
+                    help="Add paths to the watch list (then exit).")
+    wa.add_argument("--interval", type=float, default=5.0,
+                    help="Poll seconds for the daemon.")
+    sn = sub.add_parser("snap", help="Snapshot now.")
+    sn.add_argument("-m", "--message", default=None)
+    sub.add_parser("precompact", help="Snapshot before compaction.")
+    lg = sub.add_parser("log", help="List snapshots.")
+    lg.add_argument("--limit", type=int, default=20)
+    df = sub.add_parser("diff", help="Diff two snapshots.")
+    df.add_argument("sha1", nargs="?")
+    df.add_argument("sha2", nargs="?", default="HEAD")
+    un = sub.add_parser("undo", help="Restore the previous snapshot.")
+    un.add_argument("--steps", type=int, default=1)
+    rs = sub.add_parser("restore", help="Restore a specific snapshot.")
+    rs.add_argument("sha")
+    sub.add_parser("diet", help="Context-diet report.")
+    ih = sub.add_parser("install-hooks",
+                        help="Print (or --write) Claude Code hooks JSON.")
+    ih.add_argument("--write", action="store_true",
+                    help="Merge the hooks into ~/.claude/settings.json.")
+    return p
+
+
+def main(argv=None) -> int:
+    args = build_parser().parse_args(argv)
+    if args.cmd == "watch" and args.add:
+        return cmd_watch_add(args)
+    cmds = {
+        "init": cmd_init, "watch": cmd_watch, "snap": cmd_snap,
+        "precompact": cmd_precompact, "log": cmd_log, "diff": cmd_diff,
+        "undo": cmd_undo, "restore": cmd_restore, "diet": cmd_diet,
+        "install-hooks": cmd_install_hooks,
+    }
+    return cmds[args.cmd](args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())