lcode-cli 0.2.2__py3-none-any.whl → 0.3.0__py3-none-any.whl

lcode/__init__.py

@@ -1,3 +1,3 @@
 """lcode — a local-first terminal coding agent powered by open-weight models via Ollama."""
 
-__version__ = "0.2.2"
+__version__ = "0.3.0"

lcode/agent.py

@@ -19,6 +19,7 @@ from rich.panel import Panel
 from rich.text import Text
 
 from lcode import catalog, limits, sessions, web
+from lcode.checkpoints import Checkpoints
 from lcode.config import format_tokens
 from lcode.ollama import Ollama, OllamaError
 from lcode.permissions import Permissions
@@ -136,6 +137,7 @@ class Settings:
     web: str = "on"  # on | ask | off
     search_backend: str = "auto"
     searxng_url: str | None = None
+    checkpoints: bool = True  # snapshot files before the model changes them, for /undo
 
 
 class Agent:
@@ -147,6 +149,7 @@ class Agent:
         self.perms = Permissions(self.console, settings.permission_mode)
         self.tools = Toolbox(self)
         self.session_id = self.new_session_id()
+        self.checkpoints = Checkpoints(self.console, settings.checkpoints)
         self.session_name = ""
         self.session_title = ""
         self.ctx_used = 0
@@ -220,6 +223,7 @@ class Agent:
             "name": self.session_name,
             "title": self.session_title,
             "messages": self.messages,
+            "checkpoints": self.checkpoints.to_json(),
         }
         f.write_text(json.dumps(data))
 
@@ -228,6 +232,7 @@ class Agent:
         self.session_id = self.new_session_id()
         self.session_name = ""
         self.session_title = ""
+        self.checkpoints.reset(self.session_id)
 
     def rename(self, name: str) -> None:
         self.session_name = " ".join(name.split())
@@ -249,6 +254,7 @@ class Agent:
                 note = f"The session's directory {saved_cwd} no longer exists; staying in {self.cwd}"
         self.messages = [{"role": "system", "content": self.system_prompt()}, *data.get("messages", [])[1:]]
         self.session_id = info.id
+        self.checkpoints.load(info.id, data.get("checkpoints") or [])
         self.session_name = data.get("name", "")
         self.session_title = data.get("title") or sessions.title_from(self.messages)
         self.tools.read_mtimes.clear()  # files may have changed since; the model must read them again
@@ -406,6 +412,17 @@ class Agent:
         return name
 
     def run_turn(self, user_text: str) -> None:
+        self.checkpoints.begin_turn(self.session_id, user_text, len(self.messages))
+        try:
+            self._run_turn(user_text)
+        finally:
+            self.checkpoints.end_turn()
+
+    def checkpoint(self) -> None:
+        """Called before the model changes files: snapshot them once per request, for /undo."""
+        self.checkpoints.before_change(self.cwd)
+
+    def _run_turn(self, user_text: str) -> None:
         self.messages.append({"role": "user", "content": self.expand_mentions(user_text)})
         malformed = 0
         for _ in range(MAX_STEPS_PER_TURN):

lcode/checkpoints.py

@@ -0,0 +1,449 @@
+"""Automatic checkpoints, so /undo can take back what the model changed.
+
+Before the first change in a request (a file edit, or a shell command that isn't read-only), lcode
+snapshots the project into a private git repository in the state directory, and snapshots it again
+when the request ends. /undo puts the files that request changed back the way they were.
+
+The private repository is separate from the user's own: their index, HEAD, branches, stash and
+objects are never touched. It covers every file that isn't ignored, including changes made by shell
+commands, and works in folders that aren't git repositories.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import hashlib
+import os
+import shutil
+import stat
+import subprocess
+import time
+from dataclasses import asdict, dataclass, field, fields
+from pathlib import Path
+
+from rich.console import Console
+from rich.markup import escape
+
+from lcode import config
+
+KEEP_DAYS = 14  # checkpoints of older sessions are deleted
+MAX_FILES = 20_000  # larger folders aren't checkpointed
+MAX_TOTAL_BYTES = 1024**3
+MAX_FILE_BYTES = 10 * 1024**2  # larger files are left out of checkpoints
+GIT_TIMEOUT = 120
+LOCK_RETRIES = 20
+TITLE_LENGTH = 70
+DEFAULT_EXCLUDES = """\
+# Generated folders, left out even where no .gitignore mentions them
+node_modules/
+.venv/
+venv/
+__pycache__/
+*.pyc
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.tox/
+.gradle/
+.next/
+.DS_Store
+"""
+GIT_CONFIG = (
+    "core.autocrlf=false",
+    "core.safecrlf=false",
+    "core.quotepath=false",
+    "core.fsmonitor=false",
+    "commit.gpgsign=false",
+    "advice.addEmbeddedRepo=false",
+    "gc.auto=0",
+)
+IDENTITY = {
+    "GIT_AUTHOR_NAME": "lcode",
+    "GIT_AUTHOR_EMAIL": "lcode@localhost",
+    "GIT_COMMITTER_NAME": "lcode",
+    "GIT_COMMITTER_EMAIL": "lcode@localhost",
+}
+
+
+class CheckpointError(Exception):
+    pass
+
+
+@dataclass
+class Checkpoint:
+    n: int
+    request: str  # the start of the request, for display and for finding it in the conversation
+    worktree: str
+    before: str  # commit with the files as they were before the request
+    after: str = ""  # commit with the files after it; empty if lcode stopped before recording it
+    message_index: int = 0  # where the request starts in the conversation
+    created: float = 0.0
+    changes: list[dict] = field(default_factory=list)  # [{"status": "A" | "M" | "D", "path": ...}]
+    undone: bool = False
+
+    @property
+    def title(self) -> str:
+        text = " ".join(self.request.split())
+        return text if len(text) <= TITLE_LENGTH else text[: TITLE_LENGTH - 1].rstrip() + "…"
+
+    @property
+    def paths(self) -> list[str]:
+        return [c["path"] for c in self.changes]
+
+    @classmethod
+    def from_dict(cls, data: dict) -> Checkpoint:
+        known = {f.name for f in fields(cls)}
+        return cls(**{k: v for k, v in data.items() if k in known})
+
+
+@dataclass
+class Restore:
+    """What /undo or /rewind will do: which checkpoints it reverts and which files it touches."""
+
+    target: Checkpoint  # files go back to how they were before this request
+    undoing: list[Checkpoint]
+    restore: list[str]  # files to put back (modified or deleted since)
+    remove: list[str]  # files the requests created
+    conflicts: list[str]  # files that changed again after lcode changed them
+    current: str  # tree with the files as they are now
+
+
+def stores_dir() -> Path:
+    return config.STATE_DIR / "checkpoints"
+
+
+def work_tree_for(cwd: Path) -> Path:
+    """The folder a checkpoint covers: the enclosing git repository, or the folder itself."""
+    try:
+        r = subprocess.run(
+            ["git", "rev-parse", "--show-toplevel"],
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            timeout=10,
+            env=_clean_env(),
+        )
+    except (OSError, subprocess.SubprocessError):
+        return cwd.resolve()
+    top = r.stdout.strip()
+    return Path(top).resolve() if r.returncode == 0 and top else cwd.resolve()
+
+
+def _clean_env() -> dict[str, str]:
+    return {k: v for k, v in os.environ.items() if not k.startswith("GIT_")}
+
+
+def _exclude_pattern(path: str) -> str:
+    """An exclude line matching exactly this path (relative to the work tree)."""
+    escaped = "".join("\\" + ch if ch in "\\*?[" else ch for ch in path)
+    if escaped.endswith(" "):
+        escaped = escaped[:-1] + "\\ "
+    return "/" + escaped
+
+
+class Store:
+    """A private git repository with the snapshots of one work tree."""
+
+    def __init__(self, worktree: Path):
+        self.worktree = worktree
+        key = hashlib.sha256(str(worktree).encode()).hexdigest()[:16]
+        self.git_dir = stores_dir() / f"{key}.git"
+
+    def git(self, *args: str, stdin: bytes | None = None, check: bool = True, timeout: int = GIT_TIMEOUT) -> str:
+        env = _clean_env()
+        env.update(IDENTITY, GIT_DIR=str(self.git_dir), GIT_WORK_TREE=str(self.worktree), GIT_LITERAL_PATHSPECS="1")
+        cmd = ["git"]
+        for option in GIT_CONFIG:
+            cmd += ["-c", option]
+        cmd += args
+        for attempt in range(LOCK_RETRIES):
+            try:
+                r = subprocess.run(cmd, cwd=self.worktree, env=env, input=stdin, capture_output=True, timeout=timeout)
+            except FileNotFoundError as e:
+                raise CheckpointError("git isn't installed") from e
+            except subprocess.TimeoutExpired as e:
+                raise CheckpointError(f"git {args[0]} took longer than {timeout}s") from e
+            except OSError as e:
+                raise CheckpointError(str(e)) from e
+            err = r.stderr.decode(errors="replace").strip()
+            if r.returncode != 0 and ".lock" in err:
+                if attempt < LOCK_RETRIES - 1:
+                    time.sleep(0.25)  # another lcode session in the same folder is saving a checkpoint
+                    continue
+                raise CheckpointError(err.splitlines()[-1])
+            if check and r.returncode != 0:
+                raise CheckpointError(err.splitlines()[-1] if err else f"git {args[0]} failed")
+            return r.stdout.decode("utf-8", "surrogateescape")
+        raise AssertionError("unreachable")
+
+    def ensure(self) -> None:
+        if (self.git_dir / "HEAD").exists():
+            return
+        home = Path.home().resolve()
+        if self.worktree == home or self.worktree in home.parents:
+            raise CheckpointError(f"{self.worktree} is your home folder or above it; start lcode in a project folder")
+        self.git_dir.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            r = subprocess.run(
+                ["git", "init", "-q", "--bare", str(self.git_dir)], capture_output=True, env=_clean_env(), timeout=30
+            )
+        except FileNotFoundError as e:
+            raise CheckpointError("git isn't installed") from e
+        if r.returncode != 0:
+            raise CheckpointError(r.stderr.decode(errors="replace").strip() or "git init failed")
+        excludes = DEFAULT_EXCLUDES
+        own = self.worktree / ".git" / "info" / "exclude"  # the project's private ignore rules
+        if own.is_file():
+            excludes += "\n" + own.read_text(errors="replace")
+        (self.git_dir / "info").mkdir(exist_ok=True)
+        (self.git_dir / "info" / "exclude").write_text(excludes)
+        (self.git_dir / "lcode-worktree").write_text(str(self.worktree) + "\n")
+
+    def _candidates(self, limit: int | None = None) -> list[str]:
+        """Files that are new or changed since the last snapshot (every file, for the first one)."""
+        out = self.git("ls-files", "-z", "--others", "--modified", "--exclude-standard", timeout=60)
+        paths = [p for p in out.split("\0") if p]
+        if limit is not None and len(paths) > limit:
+            raise CheckpointError(f"{self.worktree} has more than {limit:,} files")
+        return paths
+
+    def _skip_large_files(self, first: bool) -> None:
+        large, total = [], 0
+        for rel in self._candidates(MAX_FILES if first else None):
+            try:
+                st = (self.worktree / rel).lstat()
+            except OSError:
+                continue
+            if not stat.S_ISREG(st.st_mode):
+                continue
+            if st.st_size > MAX_FILE_BYTES:
+                large.append(rel)
+            else:
+                total += st.st_size
+        if first and total > MAX_TOTAL_BYTES:
+            raise CheckpointError(f"{self.worktree} has more than {MAX_TOTAL_BYTES // 1024**3} GB of files")
+        if large:
+            with (self.git_dir / "info" / "exclude").open("a") as f:
+                f.write("".join(_exclude_pattern(rel) + "\n" for rel in large))
+            self.git("rm", "-q", "-r", "--cached", "--ignore-unmatch", "--", *large)
+
+    def tree(self) -> str:
+        """Record the files as they are now; returns the tree id."""
+        self.ensure()
+        first = not (self.git_dir / "index").exists()
+        self._skip_large_files(first)
+        self.git("add", "-A", "--ignore-errors", check=False)  # unreadable files are skipped
+        (self.git_dir / "lcode-last-used").touch()
+        return self.git("write-tree").strip()
+
+    def commit(self, tree: str, message: str, parent: str = "") -> str:
+        return self.git("commit-tree", tree, "-m", message, *(["-p", parent] if parent else [])).strip()
+
+    def tree_of(self, commit: str) -> str:
+        return self.git("rev-parse", f"{commit}^{{tree}}").strip()
+
+    def changes(self, a: str, b: str, paths: list[str] | None = None) -> list[dict]:
+        """Files that differ between two commits or trees: status A (only in b), D (only in a) or M."""
+        args = ["diff", "--name-status", "--no-renames", "--no-ext-diff", "-z", a, b]
+        if paths is not None and not paths:
+            return []
+        if paths is not None and len(paths) <= 500:
+            args += ["--", *paths]
+        parts = self.git(*args).split("\0")
+        wanted = set(paths) if paths is not None else None
+        out = []
+        for status, path in zip(parts[0::2], parts[1::2], strict=False):
+            if status and path and (wanted is None or path in wanted):
+                out.append({"status": status[0] if status[0] in "AD" else "M", "path": path})
+        return out
+
+    def restore_files(self, commit: str, paths: list[str]) -> None:
+        for i in range(0, len(paths), 200):  # works with any git version, unlike `git restore`
+            self.git("checkout", commit, "--", *paths[i : i + 200])
+
+    def remove_files(self, paths: list[str]) -> None:
+        for rel in paths:
+            p = self.worktree / rel
+            if p.is_symlink() or p.is_file():
+                p.unlink()
+            parent = p.parent
+            while parent != self.worktree and self.worktree in parent.parents:
+                try:
+                    parent.rmdir()  # only succeeds while empty
+                except OSError:
+                    break
+                parent = parent.parent
+
+    def set_ref(self, name: str, commit: str) -> None:
+        self.git("update-ref", name, commit)
+
+    def delete_ref(self, name: str) -> None:
+        self.git("update-ref", "-d", name, check=False)
+
+    def prune(self, keep_days: int = KEEP_DAYS) -> None:
+        """Delete the checkpoints of sessions older than keep_days."""
+        if not (self.git_dir / "HEAD").exists():
+            return
+        cutoff = dt.datetime.now() - dt.timedelta(days=keep_days)
+        refs = self.git("for-each-ref", "--format=%(refname)", "refs/lcode/").split()
+        old = [ref for ref in refs if _session_time(ref.split("/")[2]) < cutoff]
+        for ref in old:
+            self.delete_ref(ref)
+        if old:
+            self.git("gc", "-q", "--prune=now", check=False, timeout=600)
+
+
+def _session_time(session_id: str) -> dt.datetime:
+    try:
+        return dt.datetime.strptime(session_id[:15], "%Y%m%d-%H%M%S")
+    except ValueError:
+        return dt.datetime.min
+
+
+def prune_stores(keep_days: int = KEEP_DAYS) -> None:
+    """Delete the checkpoint stores of folders lcode hasn't worked in for keep_days."""
+    cutoff = time.time() - keep_days * 86400
+    root = stores_dir()
+    if not root.is_dir():
+        return
+    for store in root.glob("*.git"):
+        marker = store / "lcode-last-used"
+        try:
+            last = marker.stat().st_mtime if marker.exists() else store.stat().st_mtime
+        except OSError:
+            continue
+        if last < cutoff:
+            shutil.rmtree(store, ignore_errors=True)
+
+
+class Checkpoints:
+    """The checkpoints of one session."""
+
+    def __init__(self, console: Console, enabled: bool = True):
+        self.console = console
+        self.enabled = enabled
+        self.items: list[Checkpoint] = []
+        self.session_id = ""
+        self._pending: tuple[str, int] | None = None  # (request, message index) of the running request
+        self._current: Checkpoint | None = None
+        self._before_tree = ""
+        self._disabled: dict[str, str] = {}  # work tree -> why checkpoints are off there
+        self._pruned: set[str] = set()
+
+    # -- recording
+    def begin_turn(self, session_id: str, request: str, message_index: int) -> None:
+        self.session_id = session_id
+        self._pending = (request[:500], message_index)
+        self._current = None
+
+    def before_change(self, cwd: Path) -> None:
+        """Snapshot the files before the first change of the running request."""
+        if not self.enabled or self._pending is None or self._current is not None:
+            return
+        worktree = work_tree_for(cwd)
+        if str(worktree) in self._disabled:
+            return
+        store = Store(worktree)
+        request, index = self._pending
+        n = (self.items[-1].n if self.items else 0) + 1
+        try:
+            if str(worktree) not in self._pruned:
+                self._pruned.add(str(worktree))
+                prune_stores()
+                store.prune()
+            self._before_tree = store.tree()
+            before = store.commit(self._before_tree, f"lcode checkpoint {n} (before): {request[:200]}")
+            store.set_ref(self.ref(n), before)
+        except CheckpointError as e:
+            self._disabled[str(worktree)] = str(e)
+            self.console.print(f"[yellow]Checkpoints are off in {escape(str(worktree))}: {escape(str(e))}.[/]")
+            self.console.print("[yellow]/undo can't take back changes made there.[/]")
+            return
+        self._current = Checkpoint(
+            n=n, request=request, worktree=str(worktree), before=before, message_index=index, created=time.time()
+        )
+
+    def end_turn(self) -> None:
+        """Snapshot the files after the request and keep the checkpoint if anything changed."""
+        cp, self._current, self._pending = self._current, None, None
+        if cp is None:
+            return
+        store = Store(Path(cp.worktree))
+        try:
+            after_tree = store.tree()
+            if after_tree == self._before_tree:
+                store.delete_ref(self.ref(cp.n))  # nothing changed; nothing to undo
+                return
+            cp.after = store.commit(after_tree, f"lcode checkpoint {cp.n} (after): {cp.request[:200]}", cp.before)
+            store.set_ref(self.ref(cp.n), cp.after)
+            cp.changes = store.changes(cp.before, cp.after)
+        except CheckpointError as e:
+            self.console.print(f"[yellow]Couldn't record the files after this request: {escape(str(e))}[/]")
+        self.items.append(cp)
+        if cp.changes:
+            count = len(cp.changes)
+            self.console.print(
+                f"[dim]↶ Checkpoint {cp.n}: {count} file{'' if count == 1 else 's'} changed · /undo reverts them[/]"
+            )
+
+    def ref(self, n: int) -> str:
+        return f"refs/lcode/{self.session_id}/{n}"
+
+    # -- sessions
+    def to_json(self) -> list[dict]:
+        return [asdict(cp) for cp in self.items]
+
+    def load(self, session_id: str, data: list[dict]) -> None:
+        self.session_id = session_id
+        self.items = [Checkpoint.from_dict(d) for d in data if isinstance(d, dict)]
+
+    def reset(self, session_id: str) -> None:
+        self.session_id = session_id
+        self.items = []
+
+    # -- going back
+    def active(self) -> list[Checkpoint]:
+        return [cp for cp in self.items if not cp.undone]
+
+    def find(self, n: int) -> Checkpoint | None:
+        return next((cp for cp in self.items if cp.n == n), None)
+
+    def plan(self, target: Checkpoint) -> Restore:
+        """Work out how to put the files back to how they were before `target`'s request."""
+        undoing = [cp for cp in self.active() if cp.n >= target.n and cp.worktree == target.worktree]
+        store = Store(Path(target.worktree))
+        current = store.tree()
+        latest: dict[str, str] = {}  # path -> commit with lcode's last version of it
+        for cp in undoing:
+            if not cp.after:  # lcode stopped before recording the result; compare with the files now
+                cp.changes = store.changes(cp.before, current)
+            for path in cp.paths:
+                latest[path] = cp.after or current
+        paths = sorted(latest)
+        conflicts: list[str] = []
+        for commit in set(latest.values()):
+            group = [p for p in paths if latest[p] == commit]
+            conflicts += [c["path"] for c in store.changes(commit, current, group)]
+        diff = store.changes(target.before, current, paths)
+        return Restore(
+            target=target,
+            undoing=undoing,
+            restore=[c["path"] for c in diff if c["status"] != "A"],
+            remove=[c["path"] for c in diff if c["status"] == "A"],
+            conflicts=sorted(conflicts),
+            current=current,
+        )
+
+    def apply(self, plan: Restore) -> None:
+        store = Store(Path(plan.target.worktree))
+        n = plan.target.n
+        # Keep the files as they are now too, in case the undo itself needs undoing by hand.
+        store.set_ref(f"{self.ref(n)}-undo", store.commit(plan.current, f"lcode: files before undoing {n}"))
+        store.restore_files(plan.target.before, plan.restore)
+        store.remove_files(plan.remove)
+        for cp in plan.undoing:
+            cp.undone = True
+
+    def absolute_paths(self, plan: Restore) -> list[str]:
+        root = Path(plan.target.worktree)
+        return [str((root / p).resolve()) for p in [*plan.restore, *plan.remove]]

lcode/cli.py

@@ -390,6 +390,7 @@ def cmd_chat(args) -> None:
         web="off" if args.no_web else cfg["web"],
         search_backend=cfg["search_backend"],
         searxng_url=cfg["searxng_url"],
+        checkpoints=cfg["checkpoints"],
     )
     agent = Agent(ollama, settings, cwd, console=console)
     repl(agent, prompt=args.prompt, hardware=hw, cont=args.cont, resume=args.resume)

lcode/config.py

@@ -37,6 +37,7 @@ SETTINGS: dict[str, tuple[object, type, str]] = {
     "web": ("on", str, "web search and page fetching for the model: on | ask | off"),
     "search_backend": ("auto", str, "auto | ollama | brave | tavily | searxng (keys come from environment variables)"),
     "searxng_url": (None, str, "your SearXNG instance, e.g. http://localhost:8888"),
+    "checkpoints": (True, bool, "snapshot files before the model changes them, so /undo can restore them"),
 }
 ENV_OVERRIDES = {
     "LCODE_MODEL": "model",

lcode/repl.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import html
+import json
 import os
 import re
 import threading
@@ -23,6 +24,7 @@ from rich.text import Text
 from lcode import __version__, catalog, limits, sessions, web
 from lcode.agent import AUTO_COMPACT_RATIO, INIT_PROMPT, Agent
 from lcode.catalog import MIN_USEFUL_CONTEXT
+from lcode.checkpoints import Checkpoint, CheckpointError, Restore
 from lcode.config import PERMISSION_MODES, STATE_DIR, ConfigError, format_tokens, parse_context
 from lcode.hardware import Hardware
 from lcode.ollama import OllamaError
@@ -34,6 +36,9 @@ COMMANDS = {
     "/clear": "Start a fresh conversation",
     "/rename": "Name this session so you can find it later, e.g. /rename auth refactor",
     "/resume": "Resume a saved session: pick from a list, or /resume <number|name> (/resume all: every folder)",
+    "/undo": "Undo the file changes of the last request (lcode saves a checkpoint before changing files)",
+    "/rewind": "Go back to before an earlier request: its files, and optionally the conversation",
+    "/checkpoints": "List the requests that changed files, and which files",
     "/compact": "Summarize the conversation to free context (optional: what to focus on)",
     "/context": "Show context usage and change the window size: pick from a list, or /context 128k",
     "/ctx": "Shortcut for /context",
@@ -229,6 +234,157 @@ def context_command(agent: Agent, arg: str, hardware: Hardware) -> None:
     apply_context(agent, size, hardware)
 
 
+def ask_yes(question: str) -> bool:
+    try:
+        return input(f"  {question} [y/N] ").strip().lower() in ("y", "yes")
+    except EOFError:
+        return False
+
+
+def checkpoints_off(agent: Agent) -> bool:
+    if agent.checkpoints.enabled:
+        return False
+    agent.console.print("Checkpoints are off. Turn them on with: lcode config set checkpoints true")
+    return True
+
+
+def print_checkpoints(agent: Agent) -> None:
+    c = agent.console
+    if checkpoints_off(agent):
+        return
+    items = agent.checkpoints.items
+    if not items:
+        c.print(
+            "No checkpoints yet. Before the model first changes files in a request, lcode saves a checkpoint; "
+            "/undo restores it."
+        )
+        return
+    table = Table(title="Checkpoints", title_justify="left", header_style="bold")
+    table.add_column("#", justify="right", style="cyan")
+    table.add_column("When")
+    table.add_column("Request")
+    table.add_column("Files changed")
+    for cp in items:
+        files = ", ".join(escape(p) for p in cp.paths[:3]) + (f", +{len(cp.paths) - 3}" if len(cp.paths) > 3 else "")
+        style = "dim strike" if cp.undone else ""
+        table.add_row(
+            str(cp.n),
+            sessions.age(cp.created),
+            escape(cp.title),
+            files + (" [dim](undone)[/]" if cp.undone else ""),
+            style=style,
+        )
+    c.print(table)
+    c.print("[dim]/undo reverts the latest request; /rewind <number> goes back to before that request.[/]")
+
+
+def undo_command(agent: Agent) -> None:
+    if checkpoints_off(agent):
+        return
+    active = agent.checkpoints.active()
+    if not active:
+        agent.console.print("Nothing to undo: no request in this session has changed files (or they're all undone).")
+        return
+    restore_checkpoint(agent, active[-1], rewind=False)
+
+
+def rewind_command(agent: Agent, arg: str) -> None:
+    c = agent.console
+    if checkpoints_off(agent):
+        return
+    if not arg:
+        print_checkpoints(agent)
+        if not agent.checkpoints.active():
+            return
+        try:
+            arg = input("  Go back to before which request? (number, Enter to cancel): ").strip()
+        except EOFError:
+            return
+        if not arg:
+            return
+    target = agent.checkpoints.find(int(arg)) if arg.isdigit() else None
+    if target is None:
+        c.print(f"[yellow]No checkpoint {escape(arg)}. /checkpoints lists them.[/]")
+    elif target.undone:
+        c.print(f"Checkpoint {target.n} is already undone.")
+    else:
+        restore_checkpoint(agent, target, rewind=True)
+
+
+def file_summary(plan: Restore, limit: int = 30) -> str:
+    parts = []
+    for verb, paths in (("restored", plan.restore), ("removed", plan.remove)):
+        if paths:
+            shown = ", ".join(paths[:limit]) + (f" and {len(paths) - limit} more" if len(paths) > limit else "")
+            parts.append(f"{verb} {shown}")
+    return "; ".join(parts)
+
+
+def restore_checkpoint(agent: Agent, target: Checkpoint, rewind: bool) -> None:
+    """Put the files back to how they were before `target`'s request (and every later one)."""
+    c, cps = agent.console, agent.checkpoints
+    try:
+        plan = cps.plan(target)
+    except CheckpointError as e:
+        c.print(f"[red]Can't read checkpoint {target.n}: {escape(str(e))}[/]")
+        return
+    later = len(plan.undoing) - 1
+    also = f" and {later} later request{'' if later == 1 else 's'}" if later > 0 else ""
+    action = "Going back to before" if rewind else "Undoing"
+    c.print(f"{action} request {target.n}{also}: [bold]{escape(target.title)}[/]")
+    for path in plan.restore[:20]:
+        c.print(f"  [green]restore[/] {escape(path)}")
+    for path in plan.remove[:20]:
+        c.print(f"  [red]remove[/]  {escape(path)}")
+    hidden = max(0, len(plan.restore) - 20) + max(0, len(plan.remove) - 20)
+    if hidden:
+        c.print(f"  … and {hidden} more")
+    if plan.conflicts:
+        c.print("[yellow]These files changed again after lcode changed them; going back loses those later edits:[/]")
+        for path in plan.conflicts[:20]:
+            c.print(f"  [yellow]{escape(path)}[/]")
+        if not ask_yes("Go back anyway?"):
+            c.print("Nothing changed.")
+            return
+    elif rewind and (plan.restore or plan.remove) and not ask_yes("Restore these files?"):
+        c.print("Nothing changed.")
+        return
+    index = target.message_index
+    truncate = (
+        rewind
+        and 0 < index < len(agent.messages)
+        and agent.messages[index].get("role") == "user"
+        and agent.messages[index].get("content", "").startswith(target.request)
+        and ask_yes("Also remove those requests and answers from the conversation?")
+    )
+    try:
+        cps.apply(plan)
+    except CheckpointError as e:
+        c.print(f"[red]Couldn't restore the files: {escape(str(e))}[/]")
+        return
+    for path in cps.absolute_paths(plan):
+        agent.tools.read_mtimes.pop(path, None)  # the model must read restored files again before editing
+    if not (plan.restore or plan.remove):
+        c.print("The files were already back to how they were before that request.")
+    else:
+        c.print(f"[green]Done:[/] {escape(file_summary(plan, limit=8))}.")
+    if truncate:
+        agent.messages = agent.messages[:index]
+        agent.ctx_used = sum(len(json.dumps(m)) for m in agent.messages) // 3
+        c.print(f"The conversation is back to before request {target.n} as well.")
+    elif plan.restore or plan.remove:
+        what = "undid the file changes from" if not rewind else "rolled the files back to before"
+        agent.messages.append(
+            {
+                "role": "user",
+                "content": f'[lcode] The user {what} their request "{target.title}": {file_summary(plan)}. '
+                "Those files are back to how they were before that request, so read them again before "
+                "changing them.",
+            }
+        )
+    agent.save()
+
+
 def apply_context(agent: Agent, size: int, hardware: Hardware) -> None:
     c, s = agent.console, agent.settings
     if size == s.context:
@@ -282,7 +438,7 @@ def handle_command(agent: Agent, line: str, hardware: Hardware) -> bool:
     if cmd in ("/exit", "/quit", "/q"):
         return False
     if cmd == "/help":
-        rows = "\n".join(f"  [cyan]{k:<10}[/] {v}" for k, v in COMMANDS.items())
+        rows = "\n".join(f"  [cyan]{k:<13}[/] {v}" for k, v in COMMANDS.items())
         keys = (
             "Enter = send · Esc+Enter or trailing \\ = newline · Ctrl+C = interrupt · Ctrl+D = quit · "
             "@path = attach a file · Shift+Tab = cycle permission mode"
@@ -302,6 +458,12 @@ def handle_command(agent: Agent, line: str, hardware: Hardware) -> bool:
         info = choose_session(agent, arg)
         if info:
             resume_session(agent, info)
+    elif cmd == "/undo":
+        undo_command(agent)
+    elif cmd == "/rewind":
+        rewind_command(agent, arg)
+    elif cmd == "/checkpoints":
+        print_checkpoints(agent)
     elif cmd == "/compact":
         agent.compact(arg)
     elif cmd in ("/context", "/ctx"):

lcode/tools.py

@@ -438,6 +438,7 @@ class Toolbox:
         ok, feedback = self.agent.perms.request("edit", "edit", f"{verb} {self.rel(p)}", body)
         if not ok:
             return feedback
+        self.agent.checkpoint()
         self._write(p, content)
         n = len(content.splitlines())
         self.console.print(f"  [green]✓[/] {'Updated' if exists else 'Created'} {self.rel(p)} ({n} lines)")
@@ -472,6 +473,7 @@ class Toolbox:
         ok, feedback = self.agent.perms.request("edit", "edit", f"Edit {self.rel(p)}", self._diff(p, text, new_text))
         if not ok:
             return feedback
+        self.agent.checkpoint()
         self._write(p, new_text)
         self.console.print(f"  [green]✓[/] Edited {self.rel(p)}")
         idx = new_text.find(new_string) if new_string else -1
@@ -493,6 +495,7 @@ class Toolbox:
             )
             if not ok:
                 return feedback
+            self.agent.checkpoint()
         self.console.print(Text(f"  $ {command}", style="bold cyan"))
         fd, cwd_file = tempfile.mkstemp(prefix="lcode_cwd_")
         os.close(fd)

{lcode_cli-0.2.2.dist-info → lcode_cli-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: lcode-cli
-Version: 0.2.2
+Version: 0.3.0
 Summary: A local-first terminal coding agent powered by open-weight models on your own GPU or Mac, via Ollama.
 Project-URL: Homepage, https://nasser1941.github.io/lcode/
 Project-URL: Documentation, https://nasser1941.github.io/lcode/
@@ -76,6 +76,8 @@ through [Ollama](https://ollama.com), and when it needs current information it c
   largest context that fits: `lcode setup` does it in one step.
 - **Safe by default.** Every edit is shown as a diff and every command that isn't read-only needs
   your approval. `auto-edit` and `yolo` modes when you want speed.
+- **Undo.** lcode saves a checkpoint before the model changes files; `/undo` takes back the last
+  request's edits, new files and shell-command changes, without touching your git history.
 - **Bring your own model.** Eight curated open-weight models, all tested end to end, or any Ollama model
   with tool calling.
 - **Web search when needed.** Looks up the latest versions, docs and error messages with Ollama web
@@ -123,6 +125,7 @@ lcode
 | `lcode -c` / `lcode --resume` | continue the last session here / pick a saved session from a list |
 | `lcode --model qwen3.5-9b --context 128k` | pick a model and context window for this session |
 | `lcode models` / `lcode doctor` | what fits this machine / check the installation |
+| `/undo`, `/rewind` | take back the last request's file changes, or go back further |
 | `/rename`, `/resume` | name the current session, resume a saved one |
 | `/model`, `/context`, `/compact`, `/help` | switch model, resize the context window (pick from a list), summarize, list commands |
 
@@ -167,7 +170,6 @@ fills up. Details: [How it works](https://nasser1941.github.io/lcode/how-it-work
 
 See the pinned [Roadmap issue](https://github.com/nasser1941/lcode/issues/10). Next up:
 
-- [`/undo` and automatic checkpoints](https://github.com/nasser1941/lcode/issues/4)
 - [`lcode bench`: score models on your own hardware](https://github.com/nasser1941/lcode/issues/5)
 - [MCP tool servers](https://github.com/nasser1941/lcode/issues/6)
 - [Homebrew formula](https://github.com/nasser1941/lcode/issues/8) and an [optional sandbox for shell commands](https://github.com/nasser1941/lcode/issues/9)

lcode_cli-0.3.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+lcode/__init__.py,sha256=6o9drjzBZ6xhvmNDRH_G_fyZUs1QniLoDVSjRcEmymU,117
+lcode/__main__.py,sha256=s5N5pryX2FAu93GGZ3FxUrIXHWGzxz66lKUoaV_h8Ws,35
+lcode/agent.py,sha256=NtLV_QI75Ixvs-6Ig39qhMb2kPuIkK4z1qMclyBb3sQ,25335
+lcode/catalog.py,sha256=pZ1azX9OH2r4JE2c6E5OfwywpgS39-W2oXzoCHJhmtM,4141
+lcode/checkpoints.py,sha256=eqPtmPe44-aweWqc2H21ROogwzIt3NpvcUobsaCHoGY,18354
+lcode/cli.py,sha256=rU5XYsYmnUU-N9N1GX_s0oWSwgqYM-8k_TEKR0tlzvs,20143
+lcode/config.py,sha256=xkD7L5gSrHbgnXt7C8SYktNXO62BqNIXtuGyCY-y4FY,6002
+lcode/hardware.py,sha256=2VbknZCxTZJwJUD8YWdQ7ryEQo_LcjtoOBOHOU9Y0fw,3085
+lcode/limits.py,sha256=oJzVQoMyTZ0_Fkpu5t3qxrf9v7Hv9S8U8BRQR5M1aKA,1237
+lcode/models.toml,sha256=lt2G64zzo_Ryxv2ISRSNZoVD_JqCqYqsM01n8WoXGs8,4098
+lcode/ollama.py,sha256=fELwqw7xqLH9TM7XvdI1pxqYZFeIRJBv-VSz9REdvwA,6516
+lcode/permissions.py,sha256=wJKwhJQx44AzjOFZCWwM4M2oUlPFUNYI2cIVfoBGGgc,3898
+lcode/render.py,sha256=gMvf4W3qkLUJ4Vot3az_hP_zRDAItJC9pP-68dHFkfA,1375
+lcode/repl.py,sha256=F5DsLYya5UmJt2LvJf-N_3CdBKxiK8sr7B0zNSS7gKI,26525
+lcode/sessions.py,sha256=wOR-J0EHgJxLSPboKPHnvBcp5VTUYTj3tZWgpsa6-K4,4013
+lcode/tools.py,sha256=0JFM-owT3K243tvMhHlcfWKSMyHSa44GY4A2GebKU0k,25935
+lcode/web.py,sha256=vyxKbSRJTl1Lj3hj7Yd_NwTgbv0Xi6dup2YfUXjqp-Y,14579
+lcode_cli-0.3.0.dist-info/METADATA,sha256=o6_TdM5_SW2xs3j5SyjtNE6iIfagy9ivcBS29xplJ_c,9423
+lcode_cli-0.3.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+lcode_cli-0.3.0.dist-info/entry_points.txt,sha256=pZ_uDQ98UzVAHUQeXn5HeyQWKGSH3r3T5aPHuSB89eI,41
+lcode_cli-0.3.0.dist-info/licenses/LICENSE,sha256=JWjmoL7nNIC1XUa-dZm2hwLUgjUQMFo6k8APb0idNzs,1074
+lcode_cli-0.3.0.dist-info/RECORD,,

lcode_cli-0.2.2.dist-info/RECORD

@@ -1,21 +0,0 @@
-lcode/__init__.py,sha256=f69CJWRNbXrayd_uWS82hWDQJcvsIH6fRtjvpXj-I8s,117
-lcode/__main__.py,sha256=s5N5pryX2FAu93GGZ3FxUrIXHWGzxz66lKUoaV_h8Ws,35
-lcode/agent.py,sha256=ppO9sMxymIVvFPeHS-5hqTyryQYBOK_0OAucaX6SeWU,24535
-lcode/catalog.py,sha256=pZ1azX9OH2r4JE2c6E5OfwywpgS39-W2oXzoCHJhmtM,4141
-lcode/cli.py,sha256=bvKv_5SGJgy8bkY-zFpXwyNACiGa6nu_n16ems_Vmq8,20103
-lcode/config.py,sha256=ZyddgIZ9TaHAcJSW_A8o7qFQbp1s2RHmsbFzOzEjV4o,5894
-lcode/hardware.py,sha256=2VbknZCxTZJwJUD8YWdQ7ryEQo_LcjtoOBOHOU9Y0fw,3085
-lcode/limits.py,sha256=oJzVQoMyTZ0_Fkpu5t3qxrf9v7Hv9S8U8BRQR5M1aKA,1237
-lcode/models.toml,sha256=lt2G64zzo_Ryxv2ISRSNZoVD_JqCqYqsM01n8WoXGs8,4098
-lcode/ollama.py,sha256=fELwqw7xqLH9TM7XvdI1pxqYZFeIRJBv-VSz9REdvwA,6516
-lcode/permissions.py,sha256=wJKwhJQx44AzjOFZCWwM4M2oUlPFUNYI2cIVfoBGGgc,3898
-lcode/render.py,sha256=gMvf4W3qkLUJ4Vot3az_hP_zRDAItJC9pP-68dHFkfA,1375
-lcode/repl.py,sha256=1InDmkMz286vuCOwRHNCTdBih_KekYkM4Ol52_g7C4s,20001
-lcode/sessions.py,sha256=wOR-J0EHgJxLSPboKPHnvBcp5VTUYTj3tZWgpsa6-K4,4013
-lcode/tools.py,sha256=97wPiabQuztMr4qsMgf_beNAFfraxSlU2195QJffFkg,25835
-lcode/web.py,sha256=vyxKbSRJTl1Lj3hj7Yd_NwTgbv0Xi6dup2YfUXjqp-Y,14579
-lcode_cli-0.2.2.dist-info/METADATA,sha256=XQ3SNVJtZ6MAxIM90xpJVSLQ17uCvulOJ00kyhSNbco,9232
-lcode_cli-0.2.2.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-lcode_cli-0.2.2.dist-info/entry_points.txt,sha256=pZ_uDQ98UzVAHUQeXn5HeyQWKGSH3r3T5aPHuSB89eI,41
-lcode_cli-0.2.2.dist-info/licenses/LICENSE,sha256=JWjmoL7nNIC1XUa-dZm2hwLUgjUQMFo6k8APb0idNzs,1074
-lcode_cli-0.2.2.dist-info/RECORD,,