lcode-cli 0.1.1__py3-none-any.whl → 0.1.2__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.1.1"
+__version__ = "0.1.2"

lcode/agent.py

@@ -18,14 +18,17 @@ from rich.markdown import Markdown
 from rich.panel import Panel
 from rich.text import Text
 
-from lcode import catalog
-from lcode.config import STATE_DIR, format_tokens
+from lcode import catalog, limits, sessions
+from lcode.config import format_tokens
 from lcode.ollama import Ollama, OllamaError
 from lcode.permissions import Permissions
 from lcode.render import MarkdownStreamer
 from lcode.tools import SCHEMAS, Toolbox, is_binary, parse_text_tool_calls, tree, truncate
 
-MAX_STEPS_PER_TURN = 150  # safety cap on tool-call iterations for one request
+GPU_MEMORY_ERRORS = ("out of memory", "illegal memory access", "cudamalloc failed")
+SAFE_NUM_BATCH = 512  # Ollama's default prompt batch
+MAX_STEPS_PER_TURN = 150
+MAX_MALFORMED_CALL_RETRIES = 2  # Ollama rejects tool calls whose arguments aren't valid JSON  # safety cap on tool-call iterations for one request
 AUTO_COMPACT_RATIO = 0.85  # summarize the history when the context is this full
 PROJECT_FILES = ("AGENTS.md", "LCODE.md", "CLAUDE.md")
 
@@ -100,6 +103,8 @@ class Agent:
         self.perms = Permissions(self.console, settings.permission_mode)
         self.tools = Toolbox(self)
         self.session_id = self.new_session_id()
+        self.session_name = ""
+        self.session_title = ""
         self.ctx_used = 0
         self.last_speed = 0.0
         self.messages: list[dict] = []
@@ -134,25 +139,63 @@ class Agent:
         self.ctx_used = len(self.messages[0]["content"]) // 3
 
     def session_file(self) -> Path:
-        return STATE_DIR / "sessions" / f"{self.session_id}.json"
+        return sessions.sessions_dir() / f"{self.session_id}.json"
+
+    def has_conversation(self) -> bool:
+        return any(m.get("role") == "user" for m in self.messages)
 
     def save(self) -> None:
+        if not (self.has_conversation() or self.session_name):
+            return  # nothing worth resuming
+        self.session_title = self.session_title or sessions.title_from(self.messages)
         f = self.session_file()
         f.parent.mkdir(parents=True, exist_ok=True)
-        f.write_text(json.dumps({"cwd": str(self.cwd), "model": self.settings.model, "messages": self.messages}))
+        data = {
+            "cwd": str(self.cwd),
+            "model": self.settings.model,
+            "name": self.session_name,
+            "title": self.session_title,
+            "messages": self.messages,
+        }
+        f.write_text(json.dumps(data))
+
+    def new_session(self) -> None:
+        self.reset()
+        self.session_id = self.new_session_id()
+        self.session_name = ""
+        self.session_title = ""
+
+    def rename(self, name: str) -> None:
+        self.session_name = " ".join(name.split())
+        self.save()
+
+    def load(self, info: sessions.SessionInfo) -> str:
+        """Resume a saved session. Returns a note about the working directory, if it changed."""
+        try:
+            data = json.loads(info.path.read_text())
+        except (OSError, ValueError) as e:
+            raise OSError(f"can't read session {info.id}: {e}") from e
+        note = ""
+        saved_cwd = Path(info.cwd) if info.cwd else self.cwd
+        if saved_cwd != self.cwd:
+            if saved_cwd.is_dir():
+                self.cwd = saved_cwd.resolve()
+                note = f"Working directory is now {self.cwd}"
+            else:
+                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.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
+        self.ctx_used = sum(len(json.dumps(m)) for m in self.messages) // 3
+        return note
 
     def load_latest(self) -> bool:
-        for f in sorted((STATE_DIR / "sessions").glob("*.json"), reverse=True):
-            try:
-                data = json.loads(f.read_text())
-            except (OSError, json.JSONDecodeError):
-                continue
-            if data.get("cwd") == str(self.cwd):
-                self.messages = [{"role": "system", "content": self.system_prompt()}, *data["messages"][1:]]
-                self.session_id = f.stem
-                self.ctx_used = sum(len(json.dumps(m)) for m in self.messages) // 3
-                return True
-        return False
+        latest = sessions.list_sessions(self.cwd, limit=1)
+        if latest:
+            self.load(latest[0])
+        return bool(latest)
 
     # -- model calls
     def options(self) -> dict:
@@ -171,18 +214,45 @@ class Agent:
         }
         if tools:
             payload["tools"] = tools
+        started = False
         try:
-            yield from self.ollama.chat_stream(payload)
+            for chunk in self.ollama.chat_stream(payload):
+                started = True
+                yield chunk
         except OllamaError as e:
-            if think and "think" in str(e) and "support" in str(e):
+            error = str(e).lower()
+            if not started and think and "think" in error and "support" in error:
                 self.settings.think = False
                 self.console.print(f"[dim]{self.settings.model} does not support reasoning; continuing without.[/]")
-                yield from self.ollama.chat_stream({**payload, "think": False})
+                yield from self.chat(messages, tools, False)
                 return
-            if "out of memory" in str(e).lower():
+            if any(marker in error for marker in GPU_MEMORY_ERRORS):
+                batch = self.settings.num_batch
+                if not started and batch and batch > SAFE_NUM_BATCH:
+                    # Larger batches read prompts faster but need extra VRAM that isn't always free.
+                    self.settings.num_batch = SAFE_NUM_BATCH
+                    self.console.print(
+                        f"[yellow]The GPU ran out of memory with a prompt batch of {batch}; retrying with "
+                        f"{SAFE_NUM_BATCH}.[/] [dim]To skip this retry: lcode config set num_batch {SAFE_NUM_BATCH}[/]"
+                    )
+                    yield from self.chat(messages, tools, think)
+                    return
+                context = self.settings.context
+                if not started and context > catalog.MIN_USEFUL_CONTEXT:
+                    # The context cache has to fit in memory; halve it until the model loads.
+                    smaller = max(catalog.MIN_USEFUL_CONTEXT, context // 2)
+                    self.settings.context = smaller
+                    limits.record(self.settings.model, smaller)
+                    self.console.print(
+                        f"[yellow]{self.settings.model} didn't fit in GPU memory with a {format_tokens(context)} "
+                        f"context; retrying with {format_tokens(smaller)}.[/] [dim]lcode will start there next "
+                        "time on this machine.[/]"
+                    )
+                    yield from self.chat(messages, tools, think)
+                    return
                 raise OllamaError(
-                    f"{e}\nThe model ran out of GPU memory. Try a smaller context (/ctx 128k) or a smaller "
-                    "prompt batch (`lcode config set num_batch 512`)."
+                    f"{e}\nThe model ran out of GPU memory. Try a smaller context (/ctx 128k), close other programs "
+                    "using the GPU, or pick a smaller model (/models)."
                 ) from e
             raise
 
@@ -267,9 +337,26 @@ class Agent:
 
     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):
             self.maybe_compact()
-            calls = self.assistant_step().get("tool_calls") or []
+            try:
+                calls = self.assistant_step().get("tool_calls") or []
+            except OllamaError as e:
+                if "error parsing tool call" not in str(e) or malformed >= MAX_MALFORMED_CALL_RETRIES:
+                    raise
+                malformed += 1
+                reason = str(e).rsplit("err=", 1)[-1].strip() if "err=" in str(e) else "invalid JSON"
+                self.console.print("[yellow]The model wrote a malformed tool call; asking it to try again.[/]")
+                self.messages.append(
+                    {
+                        "role": "user",
+                        "content": f"[lcode] Your last tool call could not be parsed ({reason}): its arguments "
+                        "must be one complete, valid JSON object. Make the call again. If it writes a file, "
+                        "make sure the whole content is included and properly escaped.",
+                    }
+                )
+                continue
             if not calls:
                 break
             for i, call in enumerate(calls):

lcode/cli.py

@@ -14,7 +14,7 @@ from rich.progress import BarColumn, DownloadColumn, Progress, TextColumn, TimeR
 from rich.prompt import Confirm
 from rich.table import Table
 
-from lcode import __version__, catalog, config
+from lcode import __version__, catalog, config, limits
 from lcode.agent import Agent, Settings
 from lcode.catalog import ModelSpec
 from lcode.config import ConfigError, format_tokens, parse_context
@@ -78,9 +78,9 @@ def choose_context(
     if requested:
         ctx = requested
     elif spec:
-        ctx = spec.fit(hw)[0] or catalog.MIN_USEFUL_CONTEXT
+        ctx = limits.cap(model, spec.fit(hw)[0] or catalog.MIN_USEFUL_CONTEXT)
     else:
-        ctx = 32768
+        ctx = limits.cap(model, 32768)
     if limit and ctx > limit:
         ctx, note = limit, f"capped at the model maximum of {format_tokens(limit)}"
     if spec and requested and spec.memory_gib(ctx) > hw.budget_gib:
@@ -272,6 +272,13 @@ def cmd_doctor(args) -> None:
         if spec:
             detail += f" · ~{spec.memory_gib(ctx):.0f} GB needed, ~{hw.budget_gib:.0f} GB available"
         line("Context", detail + (f" ({note})" if note else ""), None if note else True)
+        if limits.get(model):
+            line(
+                "Limit",
+                f"{format_tokens(limits.get(model))} for {model}: larger contexts ran out of GPU memory "
+                f"here (delete {limits.path()} to try again)",
+                None,
+            )
         loaded = [m for m in ollama.running() if m.get("name") == model or m.get("model") == model]
         if loaded:
             m = loaded[0]
@@ -370,7 +377,7 @@ def cmd_chat(args) -> None:
         permission_mode=mode,
     )
     agent = Agent(ollama, settings, cwd, console=console)
-    repl(agent, prompt=args.prompt, resume=args.cont, hardware=hw)
+    repl(agent, prompt=args.prompt, hardware=hw, cont=args.cont, resume=args.resume)
 
 
 def build_parser() -> argparse.ArgumentParser:
@@ -384,7 +391,14 @@ def build_parser() -> argparse.ArgumentParser:
     parser.add_argument("-m", "--model", help="catalog key (see `lcode models`) or any installed Ollama model")
     parser.add_argument("--context", "--ctx", dest="context", help="context window, e.g. 65536, 128k or 1m")
     parser.add_argument("-r", "--repo", default=".", help="working directory (default: current directory)")
-    parser.add_argument("-c", "--continue", dest="cont", action="store_true", help="resume the last session here")
+    parser.add_argument("-c", "--continue", dest="cont", action="store_true", help="continue the last session here")
+    parser.add_argument(
+        "--resume",
+        nargs="?",
+        const="",
+        metavar="SESSION",
+        help="resume a saved session: pick from a list, or give its number, name or id",
+    )
     parser.add_argument("--auto-edit", action="store_true", help="apply file edits without asking")
     parser.add_argument("--yolo", action="store_true", help="never ask for permission (edits and commands)")
     parser.add_argument("--no-think", action="store_true", help="disable model reasoning (faster, less accurate)")

lcode/limits.py

@@ -0,0 +1,41 @@
+"""Context sizes learned to be too large on this machine, from out-of-memory errors.
+
+When a model fails to load because its context doesn't fit in GPU memory, lcode retries with half the
+context and records the size that was tried, so later sessions start there instead of failing first.
+Delete the file (see `path()`) to let lcode try larger contexts again, e.g. after a GPU upgrade.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from lcode import config
+
+
+def path() -> Path:
+    return config.STATE_DIR / "limits.json"
+
+
+def _load() -> dict[str, int]:
+    try:
+        data = json.loads(path().read_text())
+    except (OSError, ValueError):
+        return {}
+    return {k: int(v) for k, v in data.items() if isinstance(v, int)} if isinstance(data, dict) else {}
+
+
+def get(model: str) -> int | None:
+    return _load().get(model)
+
+
+def record(model: str, context: int) -> None:
+    data = _load()
+    data[model] = min(context, data.get(model, context))
+    path().parent.mkdir(parents=True, exist_ok=True)
+    path().write_text(json.dumps(data, indent=2, sort_keys=True) + "\n")
+
+
+def cap(model: str, context: int) -> int:
+    limit = get(model)
+    return min(context, limit) if limit else context

lcode/models.toml

@@ -29,7 +29,6 @@ moe = true
 size_gb = 22.6
 max_context = 262144
 kv_kib_per_token = 22
-num_batch = 1024
 swe_bench_verified = 73.4
 tested = true
 notes = "Default. Strongest tool calling among local MoE coders; fast even with experts in RAM."
@@ -44,8 +43,8 @@ moe = false
 size_gb = 17.7
 max_context = 262144
 kv_kib_per_token = 68
-tested = false
-notes = "Newest Qwen. Dense: excellent when it fits entirely in GPU/unified memory, slow when split."
+tested = true
+notes = "Newest Qwen. Dense: clean, accurate tool use; ~8 tok/s when split on a 12 GB GPU, fast when it fits in GPU/unified memory."
 
 [[model]]
 key = "qwen3.6-27b"
@@ -57,8 +56,8 @@ moe = false
 size_gb = 17.8
 max_context = 262144
 kv_kib_per_token = 68
-tested = false
-notes = "Dense coding model. Best on 24 GB+ GPUs or Macs with 48 GB+ unified memory."
+tested = true
+notes = "Dense coding model: clean, accurate tool use; ~7 tok/s when split on a 12 GB GPU. Best on 24 GB+ GPUs or 48 GB+ Macs."
 
 [[model]]
 key = "laguna-xs-2.1"
@@ -70,10 +69,9 @@ moe = true
 size_gb = 20.3
 max_context = 262144
 kv_kib_per_token = 40
-kv_estimated = true
 swe_bench_verified = 70.9
-tested = false
-notes = "Agentic-coding MoE built for local machines; slightly smaller than Qwen3.6 35B."
+tested = true
+notes = "Agentic-coding MoE built for local machines; 15-38 tok/s at 256K on a 12 GB GPU. Full KV cache in 10 of 40 layers."
 
 [[model]]
 key = "nemotron-3.5-lightning"
@@ -85,21 +83,8 @@ moe = true
 size_gb = 25.4
 max_context = 1048576
 kv_kib_per_token = 7
-tested = false
-notes = "Hybrid Mamba-Transformer: tiny KV cache, up to 1M tokens of context."
-
-[[model]]
-key = "gpt-oss-20b"
-tag = "gpt-oss:20b"
-name = "gpt-oss 20B"
-publisher = "OpenAI"
-params = "21B MoE · 3.6B active"
-moe = true
-size_gb = 13.8
-max_context = 131072
-kv_kib_per_token = 24
-tested = false
-notes = "Compact MoE with 128K context; fits 16 GB GPUs and 24 GB Macs."
+tested = true
+notes = "Hybrid Mamba-Transformer: tiny KV cache, up to 1M tokens (512K on a 12 GB GPU); 44 tok/s on a 12 GB GPU."
 
 [[model]]
 key = "qwen3.5-9b"
@@ -114,6 +99,19 @@ kv_kib_per_token = 32
 tested = true
 notes = "Small and capable: 64 tok/s fully on a 12 GB GPU at 128K context. For 8-12 GB GPUs and 16-24 GB Macs."
 
+[[model]]
+key = "gpt-oss-20b"
+tag = "gpt-oss:20b"
+name = "gpt-oss 20B"
+publisher = "OpenAI"
+params = "21B MoE · 3.6B active"
+moe = true
+size_gb = 13.8
+max_context = 131072
+kv_kib_per_token = 24
+tested = true
+notes = "Compact MoE with 128K context: 43 tok/s on a 12 GB GPU. Sometimes invents tool arguments but corrects itself."
+
 [[model]]
 key = "qwen3.5-4b"
 tag = "qwen3.5:4b"

lcode/repl.py

@@ -14,11 +14,13 @@ from prompt_toolkit.formatted_text import HTML
 from prompt_toolkit.history import FileHistory
 from prompt_toolkit.key_binding import KeyBindings
 from rich.console import Group
+from rich.markup import escape
 from rich.panel import Panel
 from rich.rule import Rule
+from rich.table import Table
 from rich.text import Text
 
-from lcode import __version__, catalog
+from lcode import __version__, catalog, limits, sessions
 from lcode.agent import INIT_PROMPT, Agent
 from lcode.catalog import MIN_USEFUL_CONTEXT
 from lcode.config import PERMISSION_MODES, STATE_DIR, ConfigError, format_tokens, parse_context
@@ -30,6 +32,8 @@ COMMANDS = {
     "/help": "Show this help",
     "/init": "Analyze the repo and write an AGENTS.md guide (loaded at every start)",
     "/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)",
     "/compact": "Summarize the conversation to free context (optional: what to focus on)",
     "/context": "Show context-window usage",
     "/ctx": "Show or change the context window, e.g. /ctx 128k",
@@ -105,6 +109,7 @@ def build_session(agent: Agent) -> PromptSession:
             f" <b>{html.escape(s.model)}</b> · ctx {format_tokens(agent.ctx_used)}/{format_tokens(s.context)} "
             f"({pct:.0f}%) · mode <{color}>{agent.perms.mode}</{color}> (shift+tab) · "
             f"think {'on' if s.think else 'off'} · {html.escape(agent.cwd.name)}/"
+            + (f" · <b>{html.escape(agent.session_name)}</b>" if agent.session_name else "")
         )
 
     STATE_DIR.mkdir(parents=True, exist_ok=True)
@@ -167,9 +172,19 @@ def handle_command(agent: Agent, line: str, hardware: Hardware) -> bool:
         )
         c.print(Panel(f"{rows}\n\n  [dim]{keys}[/]", title="lcode commands", border_style="cyan"))
     elif cmd == "/clear":
-        agent.reset()
-        agent.session_id = agent.new_session_id()
-        c.print("[green]Conversation cleared.[/]")
+        agent.new_session()
+        c.print("[green]Started a new conversation.[/] The previous one is saved; /resume brings it back.")
+    elif cmd == "/rename":
+        if not arg:
+            current = f"'{escape(agent.session_name)}'" if agent.session_name else "not named yet"
+            c.print(f"This session is {current}. Name it with /rename <name>.")
+        else:
+            agent.rename(arg)
+            c.print(f"[green]Session named '{escape(agent.session_name)}'.[/] Find it later with /resume.")
+    elif cmd == "/resume":
+        info = choose_session(agent, arg)
+        if info:
+            resume_session(agent, info)
     elif cmd == "/compact":
         agent.compact(arg)
     elif cmd == "/context":
@@ -208,7 +223,7 @@ def handle_command(agent: Agent, line: str, hardware: Hardware) -> bool:
             s.model = name
             s.num_batch = spec.num_batch if spec and name == spec.local_name else None
             if spec:  # size the context for the new model: largest window that fits this machine
-                s.context = spec.fit(hardware)[0] or MIN_USEFUL_CONTEXT
+                s.context = limits.cap(name, spec.fit(hardware)[0] or MIN_USEFUL_CONTEXT)
             agent.messages[0]["content"] = agent.system_prompt()
             c.print(f"[green]Switched to {name}[/] (context {format_tokens(s.context)}).")
     elif cmd == "/think":
@@ -241,9 +256,110 @@ def handle_command(agent: Agent, line: str, hardware: Hardware) -> bool:
     return True
 
 
-def repl(agent: Agent, prompt: str | None, resume: bool, hardware: Hardware) -> None:
-    if resume and agent.load_latest():
-        agent.console.print(f"[green]Resumed session {agent.session_id} ({len(agent.messages)} messages).[/]")
+def print_sessions(agent: Agent, found: list[sessions.SessionInfo], all_dirs: bool) -> None:
+    where = "all folders" if all_dirs else str(agent.cwd)
+    table = Table(title=f"Saved sessions · {where}", title_justify="left", header_style="bold")
+    table.add_column("#", justify="right", style="cyan")
+    table.add_column("Session")
+    table.add_column("Last used", no_wrap=True)
+    table.add_column("Requests", justify="right")
+    if all_dirs:
+        table.add_column("Folder", overflow="fold")
+    for i, info in enumerate(found, 1):
+        if info.name:
+            label = f"[bold]{escape(info.name)}[/]\n[dim]{escape(info.title or '(no requests yet)')}[/]"
+        else:
+            label = escape(info.label)
+        if info.id == agent.session_id:
+            label += " [green](current)[/]"
+        row = [str(i), label, sessions.age(info.updated), str(info.turns)]
+        if all_dirs:
+            row.append(escape(info.cwd))
+        table.add_row(*row)
+    agent.console.print(table)
+
+
+def choose_session(agent: Agent, query: str = "") -> sessions.SessionInfo | None:
+    """Find a session by number/name/id, or list them and ask. `all` lists every folder."""
+    c = agent.console
+    words = query.split()
+    all_dirs = bool(words) and words[0].lower() in ("all", "--all", "-a")
+    query = " ".join(words[1:] if all_dirs else words)
+    found = sessions.list_sessions(None if all_dirs else agent.cwd)
+    if not found and not all_dirs:
+        found, all_dirs = sessions.list_sessions(None), True
+        if found and not query:
+            c.print("[dim]No saved sessions in this folder; showing all folders.[/]")
+    if not found:
+        c.print("No saved sessions yet. Sessions are saved after every request.")
+        return None
+    if query:
+        match = sessions.find(query, found)
+        if match is None and not all_dirs:
+            match = sessions.find(query, sessions.list_sessions(None))
+        if match:
+            return match
+        c.print(f"[yellow]No session matches '{escape(query)}'.[/]")
+    print_sessions(agent, found, all_dirs)
+    try:
+        answer = input("  Resume which session? (number or name, Enter to cancel): ").strip()
+    except EOFError:
+        return None
+    if not answer:
+        return None
+    match = sessions.find(answer, found)
+    if match is None:
+        c.print(f"[yellow]No session matches '{escape(answer)}'.[/]")
+    return match
+
+
+def resume_session(agent: Agent, info: sessions.SessionInfo) -> None:
+    c = agent.console
+    if info.id == agent.session_id:
+        c.print("That's the current session.")
+        return
+    agent.save()
+    try:
+        note = agent.load(info)
+    except OSError as e:
+        c.print(f"[red]{e}[/]")
+        return
+    c.print(
+        f"[green]Resumed[/] [bold]{escape(info.label)}[/] "
+        f"[dim]({info.turns} request{'' if info.turns == 1 else 's'}, last used {sessions.age(info.updated)})[/]"
+    )
+    if note:
+        c.print(f"[yellow]{escape(note)}[/]")
+    print_recap(agent)
+
+
+def print_recap(agent: Agent) -> None:
+    """Show the last request and the start of the last answer, so it's clear where things left off."""
+    last_user = next((m for m in reversed(agent.messages) if m.get("role") == "user"), None)
+    last_answer = next(
+        (m for m in reversed(agent.messages) if m.get("role") == "assistant" and m.get("content", "").strip()), None
+    )
+    if not last_user:
+        return
+    lines = [f"[bold]You:[/] {escape(sessions.title_from([last_user]))}"]
+    if last_answer:
+        answer = " ".join(last_answer["content"].split())
+        answer = answer if len(answer) <= 300 else answer[:299].rstrip() + "…"
+        lines.append(f"[bold]lcode:[/] {escape(answer)}")
+    agent.console.print(Panel("\n".join(lines), title="Where you left off", title_align="left", border_style="dim"))
+
+
+def repl(agent: Agent, prompt: str | None, hardware: Hardware, cont: bool = False, resume: str | None = None) -> None:
+    if cont:
+        if agent.load_latest():
+            agent.console.print(f"[green]Continuing[/] [bold]{escape(agent.session_name or agent.session_title)}[/]")
+            print_recap(agent)
+        else:
+            agent.console.print("[dim]No saved session in this folder yet; starting a new one.[/]")
+    elif resume is not None:
+        info = choose_session(agent, resume)
+        if info:
+            resume_session(agent, info)
     if prompt:
         run_safely(agent, prompt)
         return
@@ -260,6 +376,8 @@ def repl(agent: Agent, prompt: str | None, resume: bool, hardware: Hardware) ->
             break
         if not line:
             continue
+        if line.lower() in sessions.EXIT_WORDS:  # people type these expecting to quit, not to ask the model
+            break
         if line.startswith("/") and not line.startswith("//"):
             if not handle_command(agent, line, hardware):
                 break

lcode/sessions.py

@@ -0,0 +1,122 @@
+"""Saved conversations: listing, naming and finding sessions to resume."""
+
+from __future__ import annotations
+
+import datetime as dt
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from lcode import config
+
+TITLE_LENGTH = 70
+SUMMARY_PREFIX = "[Summary of our conversation so far]"  # first message of a compacted conversation
+EXIT_WORDS = {"exit", "quit", ":q", ":quit"}
+
+
+@dataclass(frozen=True)
+class SessionInfo:
+    id: str
+    path: Path
+    cwd: str
+    name: str  # set with /rename; empty if never named
+    title: str  # the first request, shortened
+    model: str
+    updated: float  # modification time of the session file
+    turns: int  # number of requests from the user
+
+    @property
+    def label(self) -> str:
+        return self.name or self.title or "(no requests yet)"
+
+
+def sessions_dir() -> Path:
+    return config.STATE_DIR / "sessions"
+
+
+def title_from(messages: list[dict]) -> str:
+    """A one-line title from the first request, without attached files or compaction summaries."""
+    compacted = False
+    for message in messages:
+        if message.get("role") != "user":
+            continue
+        content = message.get("content", "")
+        if content.startswith(SUMMARY_PREFIX):
+            compacted = True
+            continue
+        text = re.split(r"\n\n<(?:file|directory) path=", content, maxsplit=1)[0]
+        text = " ".join(text.split())
+        if text:
+            return text if len(text) <= TITLE_LENGTH else text[: TITLE_LENGTH - 1].rstrip() + "…"
+    return "Compacted conversation" if compacted else ""
+
+
+def read_info(path: Path) -> SessionInfo | None:
+    try:
+        data = json.loads(path.read_text())
+        updated = path.stat().st_mtime
+    except (OSError, ValueError):
+        return None
+    messages = data.get("messages") or []
+    return SessionInfo(
+        id=path.stem,
+        path=path,
+        cwd=data.get("cwd", ""),
+        name=data.get("name", ""),
+        title=data.get("title") or title_from(messages),
+        model=data.get("model", ""),
+        updated=updated,
+        turns=sum(1 for m in messages if m.get("role") == "user"),
+    )
+
+
+def list_sessions(cwd: Path | str | None = None, limit: int = 50) -> list[SessionInfo]:
+    """Saved sessions, most recently used first; only those for `cwd` if given."""
+    directory = sessions_dir()
+    if not directory.is_dir():
+        return []
+    files = sorted(directory.glob("*.json"), key=lambda p: p.stat().st_mtime, reverse=True)
+    found = []
+    for f in files:
+        info = read_info(f)
+        if info and (info.turns or info.name) and (cwd is None or info.cwd == str(cwd)):
+            found.append(info)
+            if len(found) >= limit:
+                break
+    return found
+
+
+def find(query: str, sessions: list[SessionInfo]) -> SessionInfo | None:
+    """Match a list number (1-based), a name, a session id (or unique prefix) or a unique title fragment."""
+    q = query.strip()
+    if not q:
+        return None
+    if q.isdigit() and 1 <= int(q) <= len(sessions):
+        return sessions[int(q) - 1]
+    lowered = q.lower()
+    for s in sessions:
+        if s.name and s.name.lower() == lowered:
+            return s
+    for candidates in (
+        [s for s in sessions if s.id == q or s.id.startswith(q)],
+        [s for s in sessions if lowered in s.label.lower()],
+    ):
+        if len(candidates) == 1:
+            return candidates[0]
+    return None
+
+
+def age(timestamp: float, now: dt.datetime | None = None) -> str:
+    now = now or dt.datetime.now()
+    then = dt.datetime.fromtimestamp(timestamp)
+    seconds = (now - then).total_seconds()
+    if seconds < 60:
+        return "just now"
+    if seconds < 3600:
+        return f"{int(seconds // 60)} min ago"
+    if then.date() == now.date():
+        return f"{int(seconds // 3600)} h ago"
+    if then.date() == (now - dt.timedelta(days=1)).date():
+        return "yesterday"
+    return then.strftime("%b %d") if then.year == now.year else then.strftime("%Y-%m-%d")

lcode/tools.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import difflib
 import fnmatch
+import inspect
 import json
 import os
 import queue
@@ -265,6 +266,9 @@ class Toolbox:
         fn = getattr(self, f"t_{name}", None)
         if fn is None:
             return f"Error: unknown tool '{name}'. Available: {', '.join(sorted(TOOL_NAMES))}"
+        problem = self._argument_problem(fn, args)
+        if problem:
+            return f"Error: bad arguments for {name}: {problem}"
         try:
             return fn(**args)
         except ToolError as e:
@@ -274,6 +278,22 @@ class Toolbox:
         except Exception as e:  # surface every failure to the model instead of crashing the session
             return f"Error: {type(e).__name__}: {e}"
 
+    @staticmethod
+    def _argument_problem(fn, args: dict) -> str:
+        """Explain unknown or missing arguments in terms the model can act on."""
+        params = inspect.signature(fn).parameters
+        unknown = [a for a in args if a not in params]
+        missing = [p for p, spec in params.items() if spec.default is inspect.Parameter.empty and p not in args]
+        if not unknown and not missing:
+            return ""
+        parts = []
+        if unknown:
+            parts.append(f"unknown argument(s) {', '.join(map(repr, unknown))}")
+        if missing:
+            parts.append(f"missing required argument(s) {', '.join(map(repr, missing))}")
+        valid = ", ".join(p if params[p].default is inspect.Parameter.empty else f"{p} (optional)" for p in params)
+        return f"{'; '.join(parts)}. Valid arguments: {valid}."
+
     # -- read-only
     def t_read_file(self, path: str, offset: int = 1, limit: int = 2000) -> str:
         p = self.resolve(path)

{lcode_cli-0.1.1.dist-info → lcode_cli-0.1.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: lcode-cli
-Version: 0.1.1
+Version: 0.1.2
 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/
@@ -45,6 +45,7 @@ Description-Content-Type: text/markdown
 <p align="center">
   <a href="https://github.com/nasser1941/lcode/actions/workflows/ci.yml"><img src="https://github.com/nasser1941/lcode/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://nasser1941.github.io/lcode/"><img src="https://github.com/nasser1941/lcode/actions/workflows/docs.yml/badge.svg" alt="Docs"></a>
+  <a href="https://pypi.org/project/lcode-cli/"><img src="https://img.shields.io/pypi/v/lcode-cli.svg" alt="PyPI"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
   <img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python 3.10+">
   <img src="https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20(Apple%20Silicon)-lightgrey.svg" alt="Linux and macOS">
@@ -75,7 +76,8 @@ through [Ollama](https://ollama.com), so your code never leaves your machine.
   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.
-- **Bring your own model.** Eight curated open-weight models, or any Ollama model with tool calling.
+- **Bring your own model.** Eight curated open-weight models, all tested end to end, or any Ollama model
+  with tool calling.
 - **Private.** No telemetry, no accounts, no API keys.
 
 ## Install
@@ -88,14 +90,16 @@ curl -fsSL https://nasser1941.github.io/lcode/install.sh | bash
 
 The installer sets up lcode with its own Python via [uv](https://docs.astral.sh/uv/), checks for
 [Ollama](https://ollama.com) (0.30+) and runs `lcode setup`, which picks a model for your hardware
-and downloads it. Prefer manual steps? See the
-[installation guide](https://nasser1941.github.io/lcode/installation/), or:
+and downloads it. Prefer manual steps? lcode is on [PyPI](https://pypi.org/project/lcode-cli/) as
+`lcode-cli`:
 
 ```bash
-uv tool install git+https://github.com/nasser1941/lcode
+uv tool install lcode-cli      # or: pipx install lcode-cli
 lcode setup
 ```
 
+See the [installation guide](https://nasser1941.github.io/lcode/installation/) for details.
+
 ## Quickstart
 
 ```bash
@@ -113,9 +117,10 @@ lcode
 | | |
 |---|---|
 | `lcode -p "…"` | one request, no interaction (scripts, hooks) |
-| `lcode -c` | continue the last session in this directory |
+| `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 |
+| `/rename`, `/resume` | name the current session, resume a saved one |
 | `/model`, `/ctx 128k`, `/compact`, `/help` | switch model, resize context, summarize, list commands |
 
 ## Models
@@ -123,12 +128,12 @@ lcode
 | Key | Model | Download | Max context | |
 |---|---|---|---|---|
 | `qwen3.6-35b` | Qwen3.6 35B-A3B Coding (MoE, 3B active) | 22.6 GB | 256K | **default**, tested |
-| `qwen3.8-27b` | Qwen3.8 27B (dense) | 17.7 GB | 256K | |
-| `qwen3.6-27b` | Qwen3.6 27B Coding (dense) | 17.8 GB | 256K | |
-| `laguna-xs-2.1` | Poolside Laguna XS 2.1 (MoE, 3B active) | 20.3 GB | 256K | |
-| `nemotron-3.5-lightning` | NVIDIA Nemotron 3.5 Lightning (hybrid MoE) | 25.4 GB | 1M | |
-| `gpt-oss-20b` | OpenAI gpt-oss 20B (MoE) | 13.8 GB | 128K | |
+| `qwen3.8-27b` | Qwen3.8 27B (dense) | 17.7 GB | 256K | tested |
+| `qwen3.6-27b` | Qwen3.6 27B Coding (dense) | 17.8 GB | 256K | tested |
+| `laguna-xs-2.1` | Poolside Laguna XS 2.1 (MoE, 3B active) | 20.3 GB | 256K | tested |
+| `nemotron-3.5-lightning` | NVIDIA Nemotron 3.5 Lightning (hybrid MoE) | 25.4 GB | 1M | tested |
 | `qwen3.5-9b` | Qwen3.5 9B (dense) | 6.6 GB | 256K | tested |
+| `gpt-oss-20b` | OpenAI gpt-oss 20B (MoE) | 13.8 GB | 128K | tested |
 | `qwen3.5-4b` | Qwen3.5 4B (dense) | 3.4 GB | 256K | tested |
 
 What `lcode setup` picks for common machines:
@@ -140,7 +145,7 @@ What `lcode setup` picks for common machines:
 | Mac with M4 Pro / M4 Max, 36 GB | qwen3.6-35b | 64K |
 | Mac with M4 Pro, 48 GB · M4 Max, 64 GB+ | qwen3.6-35b | 256K |
 | NVIDIA 8–24 GB + 32 GB RAM | qwen3.6-35b | 256K |
-| NVIDIA 8 GB + 16 GB RAM | qwen3.5-4b | 64K |
+| NVIDIA 8 GB + 16 GB RAM | gpt-oss-20b | 64K |
 
 On an RTX 4080 Laptop GPU (12 GB) the default model generates 50–60 tokens/s at 256K context, and
 qwen3.5-9b 64 tokens/s at 128K. See

lcode_cli-0.1.2.dist-info/RECORD

@@ -0,0 +1,20 @@
+lcode/__init__.py,sha256=DCFKMt5wGr6X-Z5XXGSODRrKPH4BQtYY3wBJ4PTfh08,117
+lcode/__main__.py,sha256=s5N5pryX2FAu93GGZ3FxUrIXHWGzxz66lKUoaV_h8Ws,35
+lcode/agent.py,sha256=FLWZK97MH15r7feTiYFZfbhWU_EQ9PEvwGBXbGb3AfA,21807
+lcode/catalog.py,sha256=pZ1azX9OH2r4JE2c6E5OfwywpgS39-W2oXzoCHJhmtM,4141
+lcode/cli.py,sha256=kRpZNze1Gsa33Z-l7eLJYXG5vFzozqOrA-KCRduJ6tU,19337
+lcode/config.py,sha256=NvsiWFyGyDpEKHwWDrW643yYLRG4Omp8Qnp_68K2a_Y,5038
+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=6nPOlr0ARoI_ZXfugIq4r8TUZj2wE8SSvpjp9zdC578,3890
+lcode/render.py,sha256=gMvf4W3qkLUJ4Vot3az_hP_zRDAItJC9pP-68dHFkfA,1375
+lcode/repl.py,sha256=3mSNT9ku5rtqkX_h_mctiy4LuktS46ESzkcSlz2cjb4,16021
+lcode/sessions.py,sha256=wOR-J0EHgJxLSPboKPHnvBcp5VTUYTj3tZWgpsa6-K4,4013
+lcode/tools.py,sha256=TaYb1ncRO_e-XBwhB5GdAhgB6kpYlJmjetnyYFDCZzs,23198
+lcode_cli-0.1.2.dist-info/METADATA,sha256=5BhEy2IFBX3boJjBLa639QZGH4b22CM3VhR6Pn-mnR0,8536
+lcode_cli-0.1.2.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+lcode_cli-0.1.2.dist-info/entry_points.txt,sha256=pZ_uDQ98UzVAHUQeXn5HeyQWKGSH3r3T5aPHuSB89eI,41
+lcode_cli-0.1.2.dist-info/licenses/LICENSE,sha256=JWjmoL7nNIC1XUa-dZm2hwLUgjUQMFo6k8APb0idNzs,1074
+lcode_cli-0.1.2.dist-info/RECORD,,

lcode_cli-0.1.1.dist-info/RECORD

@@ -1,18 +0,0 @@
-lcode/__init__.py,sha256=czDagA2Y7vJ-F5wm2C4CrWmBci7DnShS1yCOE3nEjbQ,117
-lcode/__main__.py,sha256=s5N5pryX2FAu93GGZ3FxUrIXHWGzxz66lKUoaV_h8Ws,35
-lcode/agent.py,sha256=Tc9HYFzASMpVGYWxX_U7RWqNTZK2czaPjGBjlHs-P1I,17427
-lcode/catalog.py,sha256=pZ1azX9OH2r4JE2c6E5OfwywpgS39-W2oXzoCHJhmtM,4141
-lcode/cli.py,sha256=7Pfq_mnZ-tIhFfe_YpVohRwt236I1an2-4TN0sWqvfg,18789
-lcode/config.py,sha256=NvsiWFyGyDpEKHwWDrW643yYLRG4Omp8Qnp_68K2a_Y,5038
-lcode/hardware.py,sha256=2VbknZCxTZJwJUD8YWdQ7ryEQo_LcjtoOBOHOU9Y0fw,3085
-lcode/models.toml,sha256=23KFX9z6WPQPXZEhD1SV9OxQowHY9TEp0IDwxIPbYb4,3949
-lcode/ollama.py,sha256=fELwqw7xqLH9TM7XvdI1pxqYZFeIRJBv-VSz9REdvwA,6516
-lcode/permissions.py,sha256=6nPOlr0ARoI_ZXfugIq4r8TUZj2wE8SSvpjp9zdC578,3890
-lcode/render.py,sha256=gMvf4W3qkLUJ4Vot3az_hP_zRDAItJC9pP-68dHFkfA,1375
-lcode/repl.py,sha256=BL8bQcJ6tw4uadF2bELsFwshPe5SOKZOZQob5ybUpzM,10816
-lcode/tools.py,sha256=99XvUhNs1YjjqXORmiu3NI9jC0FX11eJkI1sENWtq5s,22206
-lcode_cli-0.1.1.dist-info/METADATA,sha256=3X8oSBoTEydGadmN0JHrpI9-EMGzLC9Df4n52Gq94Dc,8158
-lcode_cli-0.1.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-lcode_cli-0.1.1.dist-info/entry_points.txt,sha256=pZ_uDQ98UzVAHUQeXn5HeyQWKGSH3r3T5aPHuSB89eI,41
-lcode_cli-0.1.1.dist-info/licenses/LICENSE,sha256=JWjmoL7nNIC1XUa-dZm2hwLUgjUQMFo6k8APb0idNzs,1074
-lcode_cli-0.1.1.dist-info/RECORD,,