lcode-cli 0.30.0__tar.gz → 0.31.0__tar.gz

{lcode_cli-0.30.0 → lcode_cli-0.31.0}/CHANGELOG.md

@@ -6,6 +6,17 @@ All notable changes to lcode are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.31.0] - 2026-10-14
+
+### Added
+
+- A task sheet that survives long sessions. The plan (the todo list), the model's notes (decisions,
+  findings, open questions, kept in `todo_write`'s new `notes`, or inside a todo item, where small
+  models tend to put them), the files changed and the last check are pinned next to the summary and
+  next to your request when old output is removed. It's saved with the session, so `lcode -c`
+  brings it back (the todo list used to be lost), and `/status` shows it. See
+  [Context management](https://nasser1941.github.io/lcode/how-it-works/#context-management).
+
 ## [0.30.0] - 2026-10-13
 
 ### Added
@@ -668,7 +679,8 @@ First public release.
 - `AGENTS.md` project instructions and `/init` to generate them.
 - One-line installer for Linux and macOS.
 
-[Unreleased]: https://github.com/nasser1941/lcode/compare/v0.30.0...HEAD
+[Unreleased]: https://github.com/nasser1941/lcode/compare/v0.31.0...HEAD
+[0.31.0]: https://github.com/nasser1941/lcode/compare/v0.30.0...v0.31.0
 [0.30.0]: https://github.com/nasser1941/lcode/compare/v0.29.0...v0.30.0
 [0.29.0]: https://github.com/nasser1941/lcode/compare/v0.28.1...v0.29.0
 [0.28.1]: https://github.com/nasser1941/lcode/compare/v0.28.0...v0.28.1

{lcode_cli-0.30.0 → lcode_cli-0.31.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: lcode-cli
-Version: 0.30.0
+Version: 0.31.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/

{lcode_cli-0.30.0 → lcode_cli-0.31.0}/docs/how-it-works.md

@@ -97,6 +97,16 @@ context is old tool output, so:
    findings, files changed, next steps) and continues from it. Your latest requests (up to eight)
    are kept word for word under the summary, so the goal isn't lost in the retelling.
 
+**The task sheet.** Next to the summary, and next to your request when old tool output is removed,
+lcode pins a short sheet, so the state of the work survives:
+
+- the plan (the model's todo list);
+- the notes the model keeps with it (decisions and why, findings, open questions);
+- the files changed in the session;
+- the last check.
+
+It's saved with the session, so `lcode -c` brings it back, and `/status` shows it to you.
+
 `lcode config set compact_at 128k` moves the ceiling, and `0` turns it off, leaving only the 85%
 rule. `/context` shows where the current session makes room.
 

{lcode_cli-0.30.0 → lcode_cli-0.31.0}/docs/quickstart.md

@@ -12,7 +12,7 @@ lcode
 
 ```text
 ╭──────────────────────────────────────────────╮
-│ lcode v0.30.0 — local coding agent           │
+│ lcode v0.31.0 — local coding agent           │
 │                                              │
 │ model    lcode-qwen3.6-35b                   │
 │ context  256K tokens                         │

{lcode_cli-0.30.0 → lcode_cli-0.31.0}/docs/usage.md

@@ -80,6 +80,7 @@ reasoning is on.
 | `/mode [ask\|plan\|auto-edit\|yolo]` | Set the permission mode |
 | `/cd DIR` | Change the working directory |
 | `/todos` | Show the model's task list |
+| `/status` | The task sheet: your latest requests, the plan and the model's notes, files changed, the last check |
 | `/jobs [stop ID]` | The [background commands](#background-commands) the model started; stop one |
 | `/commit [notes]` | [Commit](git.md#commit) the changes with a message in the repository's style, once you approve it |
 | `/review [base]` | [Review](git.md#review) the uncommitted changes, or the branch against a base |
@@ -99,7 +100,7 @@ reasoning is on.
 | `grep` | Regex search with ripgrep (falls back to Python if ripgrep is missing) |
 | `bash` | Run a shell command with live output, a timeout and a persistent working directory; with `background`, keep it running ([details](#background-commands)) |
 | `bash_output`, `bash_stop` | Read what a background command printed since last time; stop it |
-| `todo_write` | Keep a visible task list for multi-step work |
+| `todo_write` | Keep a visible task list for multi-step work, with notes (decisions, findings) that survive when old messages are removed; `/status` shows them |
 | `web_search` | Search the web for current information (needs a [search provider](#web-search)) |
 | `web_fetch` | Read a web page or text file by URL as clean text |
 | `view_image` | Look at an image: a model that can see describes it ([Images](#images)) |

{lcode_cli-0.30.0 → lcode_cli-0.31.0}/src/lcode/__init__.py

@@ -3,7 +3,7 @@
 From a program: `from lcode import Session` (see lcode.api).
 """
 
-__version__ = "0.30.0"
+__version__ = "0.31.0"
 
 API = ("Session", "Result", "Options", "SetupError")
 

{lcode_cli-0.30.0 → lcode_cli-0.31.0}/src/lcode/agent.py

@@ -112,7 +112,7 @@ SYSTEM_PROMPT = """You are lcode, an autonomous software-engineering agent runni
 - To understand a repository: look at the layout, README/docs, entry points and config, then grep and read the relevant files. Cite code as `path:line`.
 - Read a file before editing it. Use edit_file for targeted changes and write_file for new files or full rewrites. old_string must be copied exactly from the file (without the line-number prefixes).
 - Match the existing code style, naming and structure. Don't add unrequested features.
-- For multi-step tasks, plan with todo_write and keep it updated.
+- For multi-step tasks, plan with todo_write and keep it updated; put decisions and findings you must not lose in its notes.
 - Work autonomously until the task is done. Only stop to ask the user when you are genuinely blocked or the decision is theirs.
 - Don't run destructive or irreversible commands (rm -rf, git reset --hard, git push --force, dropping data) unless the user explicitly asked.
 - If the user denies a tool call, don't retry the same thing; adjust or ask.
@@ -613,6 +613,9 @@ class Agent:
             "title": self.session_title,
             "messages": self.messages,
             "checkpoints": self.checkpoints.to_json(),
+            "todos": self.tools.todos,
+            "notes": self.tools.notes,
+            "changed": list(self.tools.changed),
         }
         # Written next to it and then renamed: a crash halfway leaves the previous version, not a broken file.
         partial = f.with_name(f".{f.name}.partial")
@@ -626,6 +629,8 @@ class Agent:
         self.session_name = ""
         self.session_title = ""
         self.checkpoints.reset(self.session_id)
+        self.tools.todos, self.tools.notes, self.tools.changed = [], [], {}
+        self.check_results = []
 
     def rename(self, name: str) -> None:
         self.session_name = " ".join(name.split())
@@ -652,6 +657,9 @@ class Agent:
         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.tools.todos = list(data.get("todos") or [])
+        self.tools.notes = [str(n) for n in data.get("notes") or []]
+        self.tools.changed = dict.fromkeys(str(f) for f in data.get("changed") or [])
         self.reflected = len(self.messages)  # checked for notes to remember when that session ended
         self.ctx_used = sum(len(json.dumps(m)) for m in self.messages) // 3
         self.counted_chars = None
@@ -1289,6 +1297,8 @@ class Agent:
                     self.messages, keep=1, removed=removed
                 )  # not enough: before the last request
             context_tools.note_removed(self.messages, removed)
+            if saved:
+                context_tools.pin(self.messages, context_tools.task_sheet(self))
             if saved:
                 self.sent_chars = 0  # the conversation changed: the model reads it again
                 self.pruned += 1
@@ -1333,7 +1343,9 @@ class Agent:
             {"role": "system", "content": self.system_prompt()},
             {
                 "role": "user",
-                "content": f"{sessions.SUMMARY_PREFIX}\n\n{summary}" + context_tools.requests_block(requests),
+                "content": f"{sessions.SUMMARY_PREFIX}\n\n{summary}"
+                + context_tools.requests_block(requests)
+                + (f"\n\n{sheet}" if (sheet := context_tools.task_sheet(self)) else ""),
             },
             {"role": "assistant", "content": "Got it — I have the context from the summary and will continue."},
         ]

{lcode_cli-0.30.0 → lcode_cli-0.31.0}/src/lcode/context.py

@@ -49,7 +49,9 @@ REQUESTS_HEADER = "[The user's requests in this conversation, word for word, old
 MAX_REQUESTS = 8  # the most recent ones are kept through a summary
 MAX_REQUEST_CHARS = 1500
 # What lcode appends to the user's words: attached files, images and folders, and its own notes.
-ATTACHED = re.compile(r"\n\n(?:<file path=|<image path=|<directory path=|\[lcode[:\]] |\[The user wants the )")
+ATTACHED = re.compile(
+    r"\n\n(?:<file path=|<image path=|<directory path=|\[lcode[:\]] |\[The user wants the )"
+)  # also the sheet
 
 
 def request_text(content: str) -> str:
@@ -187,6 +189,51 @@ def prune(messages: list[dict], keep: int = KEEP_RECENT_REQUESTS, removed: list[
     return saved
 
 
+SHEET_HEADER = "[lcode] Task sheet: the plan, notes and changes so far, kept when old messages are removed"
+MAX_SHEET = 3000  # characters
+
+
+def task_sheet(agent: Agent) -> str:
+    """The state of the work, from lcode's own records: the todo list and the model's notes (todo_write), the
+    files changed in the session and the last check. Pinned where old messages go: in summaries and next to the
+    request when tool output is removed."""
+    tools = agent.tools
+    parts = []
+    if tools.todos:
+        marks = {"completed": "[x]", "in_progress": "[>]", "pending": "[ ]"}
+        plan = "\n".join(f"{marks.get(t.get('status', ''), '[ ]')} {t.get('content', '')}" for t in tools.todos)
+        parts.append(f"Plan:\n{plan}")
+    if tools.notes:
+        parts.append("Notes:\n" + "\n".join(f"- {note}" for note in tools.notes))
+    if tools.changed:
+        files = list(tools.changed)
+        more = f" and {len(files) - 30} more" if len(files) > 30 else ""
+        parts.append("Files changed in this session: " + ", ".join(files[-30:]) + more)
+    if agent.check_results:
+        last = agent.check_results[-1]
+        code = last.get("exit_code")
+        state = "passed" if code == 0 else "didn't run" if code is None else f"failed (exit code {code})"
+        parts.append(f"Last check: `{last.get('command')}` {state}")
+    if not parts:
+        return ""
+    sheet = "\n\n".join(parts)
+    if len(sheet) > MAX_SHEET:
+        sheet = sheet[: MAX_SHEET - 20] + "\n[…cut]"
+    return f"{SHEET_HEADER}\n{sheet}"
+
+
+def pin(messages: list[dict], text: str) -> None:
+    """Put a note next to the request the model is working on, replacing an earlier sheet there."""
+    if not text:
+        return
+    for message in reversed(messages):
+        content = str(message.get("content", ""))
+        if message.get("role") == "user" and not content.startswith(("[lcode]", SUMMARY_PREFIX)):
+            content = content.split("\n\n" + SHEET_HEADER, 1)[0]
+            message["content"] = f"{content}\n\n{text}"
+            return
+
+
 def note_removed(messages: list[dict], removed: list[str]) -> None:
     """Tell the model, next to the request it's working on, which files it no longer has: a stub deep in the
     conversation is easy to overlook, and models then answer from memory instead of reading again."""

{lcode_cli-0.30.0 → lcode_cli-0.31.0}/src/lcode/repl.py

@@ -63,6 +63,7 @@ COMMANDS = {
     "/mode": "Permission mode: ask | plan | auto-edit | yolo (Shift+Tab cycles)",
     "/cd": "Change the working directory",
     "/todos": "Show the current todo list",
+    "/status": "The task sheet: your requests, the plan and notes, files changed, the last check",
     "/jobs": "Background commands the model started: /jobs, /jobs stop <id>",
     "/commit": "Commit the changes with a message in the repository's style, after you approve it",
     "/review": "Review the uncommitted changes, or the branch against a base: /review [base]",
@@ -109,6 +110,31 @@ def mention(path: Path) -> str:
     return f'@"{shown}"' if " " in shown else f"@{shown}"
 
 
+def status_command(agent: Agent) -> None:
+    """What the session is doing, as lcode keeps it for the model (the task sheet)."""
+    c = agent.console
+    requests = context_tools.user_requests(agent.messages)
+    if not requests and not agent.tools.todos and not agent.tools.changed:
+        c.print("Nothing yet: no requests in this session.")
+        return
+    if requests:
+        latest = requests[-3:]
+        lines = [f"[dim]{len(requests) - len(latest) + i + 1}.[/] {escape(r[:300])}" for i, r in enumerate(latest)]
+        c.print(Panel("\n".join(lines), title="Requests (latest)", title_align="left", border_style="cyan"))
+    if agent.tools.todos or agent.tools.notes:
+        agent.tools.show_todos()
+    if agent.tools.changed:
+        c.print(f"[bold]Files changed:[/] {escape(', '.join(agent.tools.changed))}")
+    if agent.check_results:
+        last = agent.check_results[-1]
+        code = last.get("exit_code")
+        state = (
+            "[green]passed[/]" if code == 0 else "didn't run" if code is None else f"[red]failed[/] (exit code {code})"
+        )
+        c.print(f"[bold]Last check:[/] {escape(str(last.get('command')))} {state}")
+    c.print("[dim]The model keeps this too, even when old messages are removed or summarized.[/]")
+
+
 def build_session(agent: Agent) -> PromptSession:
     kb = KeyBindings()
 
@@ -978,6 +1004,8 @@ def handle_command(agent: Agent, line: str, hardware: Hardware) -> bool:
             c.print(f"Working directory: {p}")
         else:
             c.print(f"[red]Not a directory: {p}[/]")
+    elif cmd == "/status":
+        status_command(agent)
     elif cmd == "/todos":
         agent.tools.show_todos()
     elif cmd == "/jobs":

{lcode_cli-0.30.0 → lcode_cli-0.31.0}/src/lcode/tools.py

@@ -24,6 +24,7 @@ from pathlib import Path
 from typing import TYPE_CHECKING
 
 from rich.console import Group
+from rich.markup import escape
 from rich.panel import Panel
 from rich.syntax import Syntax
 from rich.text import Text
@@ -45,6 +46,7 @@ NO_NETWORK = re.compile(
 )
 MAX_TOOL_OUTPUT = 30_000  # characters returned to the model per tool call
 PENDING_LINES = 5000  # output lines waiting to be read, at most
+MAX_NOTES, MAX_NOTE = 12, 300  # the model's task notes: how many, how long each
 LEFTOVER_GRACE = 0.5  # seconds to wait for output after a command ends, before stopping what it left running
 IGNORE_DIRS = {
     ".git", "node_modules", "__pycache__", ".venv", "venv", "env", ".mypy_cache", ".pytest_cache",
@@ -161,7 +163,8 @@ SCHEMAS = [
     _fn(
         "todo_write",
         "Create or update your task list for multi-step work. Pass the full list every time. Keep exactly one "
-        "item in_progress while working.",
+        "item in_progress while working. In `notes`, keep what you must not forget: decisions and why, findings, "
+        "open questions. The list and the notes stay with you even when old messages are removed.",
         {
             "todos": {
                 "type": "array",
@@ -173,7 +176,12 @@ SCHEMAS = [
                     },
                     "required": ["content", "status"],
                 },
-            }
+            },
+            "notes": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Short notes, the full list each time (omit to keep the current ones)",
+            },
         },
         ["todos"],
     ),
@@ -438,6 +446,8 @@ class Toolbox:
         self.agent = agent
         self.read_mtimes: dict[str, float] = {}
         self.formats: dict[str, TextFormat] = {}  # encoding and line endings of the files read
+        self.notes: list[str] = []  # the model's notes on the task (todo_write): decisions, findings, questions
+        self.changed: dict[str, None] = {}  # files lcode wrote in this session, in order
         self.todos: list[dict] = []
         # An editor's buffers (lcode acp): read unsaved changes and write through the editor.
         self.reader: Callable[[Path], str | None] | None = None
@@ -865,6 +875,7 @@ class Toolbox:
         if not p.exists() or p.read_bytes() != data:
             p.write_bytes(data)  # the file on disk must match, for checkpoints and the tools
         self.read_mtimes[str(p)] = p.stat().st_mtime
+        self.changed[self.rel(p)] = None
 
     def t_write_file(self, path: str, content: str) -> str:
         p = self.path(path)
@@ -1248,12 +1259,29 @@ class Toolbox:
         return f"[{describe(job)}]" + (f"\nIts last output:\n{last}" if last else "")
 
     # -- planning
-    def t_todo_write(self, todos: list | str) -> str:
+    def t_todo_write(self, todos: list | str, notes: list | str | None = None) -> str:
         if isinstance(todos, str):
             todos = json.loads(todos)
         self.todos = list(todos)
+        # Small models often put a note inside an item instead of in `notes`: keep it either way.
+        attached = [
+            str(todo.get(key)).strip()
+            for todo in self.todos
+            if isinstance(todo, dict)
+            for key in ("notes", "note", "details")
+            if str(todo.get(key) or "").strip()
+        ]
+        if attached:
+            notes = [*([] if notes is None else ([notes] if isinstance(notes, str) else list(notes))), *attached]
+        if notes is not None:
+            if isinstance(notes, str):
+                try:
+                    notes = json.loads(notes)
+                except ValueError:
+                    notes = [notes]
+            self.notes = [str(n).strip()[:MAX_NOTE] for n in notes if str(n).strip()][:MAX_NOTES]
         self.show_todos()
-        return "Todo list updated."
+        return "Todo list updated." + (f" {len(self.notes)} note(s) kept." if notes is not None else "")
 
     def show_todos(self) -> None:
         icons = {"completed": "[green]✔[/]", "in_progress": "[yellow]◐[/]", "pending": "[dim]○[/]"}
@@ -1265,4 +1293,6 @@ class Toolbox:
             elif status == "in_progress":
                 text = f"[bold]{text}[/]"
             rows.append(f"{icons.get(status, '○')} {text}")
+        if self.notes:
+            rows += ["", *(f"[dim]•[/] {escape(note)}" for note in self.notes)]
         self.console.print(Panel("\n".join(rows) or "(empty)", title="Todos", title_align="left", border_style="blue"))

{lcode_cli-0.30.0 → lcode_cli-0.31.0}/tests/test_context.py

@@ -1,6 +1,6 @@
 import pytest
 
-from conftest import output, reply
+from conftest import call, output, reply
 from lcode import context
 from lcode.hardware import Hardware
 from lcode.repl import handle_command
@@ -245,3 +245,56 @@ def test_the_model_is_told_next_to_its_request_what_it_no_longer_has(make_agent)
         "conversation any more: read it again"
     )
     assert context.user_requests(agent.messages)[-1] == "third request"
+
+
+TODOS = [
+    {"content": "Port the parser", "status": "completed"},
+    {"content": "Keep the old flags", "status": "in_progress"},
+]
+
+
+def test_the_task_sheet_survives_a_summary_and_a_resume(make_agent, repo):
+    agent = make_agent(
+        [
+            reply(tool_calls=[call("read_file", path="README.md")]),
+            reply(tool_calls=[call("edit_file", path="README.md", old_string="Demo", new_string="Demo app")]),
+            reply(tool_calls=[call("todo_write", todos=TODOS, notes=["Decided: keep --legacy as an alias"])]),
+            reply("Working on it."),
+            reply("Summary."),
+        ]
+    )
+    agent.run_turn("port the parser")
+    agent.save()
+    agent.compact()
+    summary = agent.messages[1]["content"]
+    assert context.SHEET_HEADER in summary and "[>] Keep the old flags" in summary
+    assert "- Decided: keep --legacy as an alias" in summary and "Files changed in this session: README.md" in summary
+    other = make_agent()
+    other.load_latest()
+    assert other.tools.todos == TODOS and other.tools.notes == ["Decided: keep --legacy as an alias"]
+    assert list(other.tools.changed) == ["README.md"]
+    other.new_session()
+    assert other.tools.todos == [] and other.tools.notes == [] and not other.tools.changed
+
+
+def test_the_sheet_is_pinned_next_to_the_request_when_output_is_removed(make_agent):
+    agent = make_agent([reply("ok")], context=16384)
+    agent.messages = conversation(BIG * 10)
+    agent.tools.todos = TODOS
+    agent.ctx_used = int(0.9 * 16384)
+    agent.maybe_compact()
+    agent.maybe_compact()  # pinned again: replaced, not added
+    latest = agent.messages[11]["content"]
+    assert latest.startswith("third request") and latest.count(context.SHEET_HEADER) == 1
+    assert context.user_requests(agent.messages)[-1] == "third request"  # the sheet isn't the user's words
+
+
+def test_status_shows_the_sheet(make_agent):
+    from lcode.repl import handle_command
+
+    agent = make_agent([reply(tool_calls=[call("todo_write", todos=TODOS, notes=["Open: --strict?"])]), reply("ok")])
+    agent.run_turn("port the parser")
+    handle_command(agent, "/status", HW)
+    text = output(agent)
+    assert "Requests (latest)" in text and "port the parser" in text and "Keep the old flags" in text
+    assert "Open: --strict?" in text

{lcode_cli-0.30.0 → lcode_cli-0.31.0}/tests/test_tools.py

@@ -138,3 +138,11 @@ def test_edits_in_ask_mode(make_agent, repo: Path, monkeypatch):
     out = agent.tools.run("edit_file", {"path": "src/pkg/math.py", "old_string": "a - b", "new_string": "b - a"})
     assert out.startswith("Edited src/pkg/math.py")
     assert "return b - a" in (repo / "src/pkg/math.py").read_text()
+
+
+def test_notes_inside_a_todo_item_are_kept(agent):
+    todos = [{"content": "Add --format", "status": "completed", "notes": "Decision: JSON with sorted keys, indent 2"}]
+    assert agent.tools.run("todo_write", {"todos": todos}).endswith("1 note(s) kept.")
+    assert agent.tools.notes == ["Decision: JSON with sorted keys, indent 2"]
+    agent.tools.run("todo_write", {"todos": todos, "notes": ["Open: does --strict apply?"]})
+    assert agent.tools.notes == ["Open: does --strict apply?", "Decision: JSON with sorted keys, indent 2"]