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

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

@@ -6,6 +6,18 @@ All notable changes to lcode are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.32.0] - 2026-10-14
+
+### Added
+
+- A review before the answer. After a request that changed files, the model checks its change
+  against your request, from the diff and its own answer, and real problems (part of the request
+  not done, an untested claim, a leftover debug print) go back to it once. One line says what the
+  review found. It's off by default: measured with qwen3.6-35b on a 12 GB laptop, it made requests
+  73% slower for one real catch. Turn it on with `lcode config set review auto`. `lcode -p --output
+  json` reports it in `review`, and `lcode bench --review` compares. See
+  [A review before the answer](https://nasser1941.github.io/lcode/usage/#a-review-before-the-answer).
+
 ## [0.31.0] - 2026-10-14
 
 ### Added
@@ -679,7 +691,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.31.0...HEAD
+[Unreleased]: https://github.com/nasser1941/lcode/compare/v0.32.0...HEAD
+[0.32.0]: https://github.com/nasser1941/lcode/compare/v0.31.0...v0.32.0
 [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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: lcode-cli
-Version: 0.31.0
+Version: 0.32.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.31.0 → lcode_cli-0.32.0}/docs/automation.md

@@ -55,6 +55,7 @@ went: `0` success, `1` an error, `3` stopped at `--max-steps`, `4` stopped becau
 | `tool_calls` | Every tool call, with its arguments and output (the first 4,000 characters). `error` is true when the call failed or wasn't allowed |
 | `files_changed` | Files the request added (`A`), modified (`M`) or deleted (`D`), shell commands included |
 | `usage` | Model requests and tokens; `prompt_tokens` includes tokens served from the prompt cache |
+| `review` | What the [review](usage.md#a-review-before-the-answer) sent back to the model (`[]` when it found nothing; `null` when no review ran) |
 | `checks` | The [checks](usage.md#checks-before-done) that ran after the change: `command`, `exit_code` (`null` when they weren't allowed to run) and `by` (`lcode`, or `model` when the model ran them itself) |
 | `error` | What went wrong, when `status` is `error` |
 | `session_id` | Continue the conversation later with `lcode --resume <id>` |

{lcode_cli-0.31.0 → lcode_cli-0.32.0}/docs/configuration.md

@@ -43,6 +43,7 @@ lcode config path                      # print the file location
 | `max_parallel_agents` | `1` | Subagents that run at the same time; more needs `OLLAMA_NUM_PARALLEL` on the Ollama server ([details](agents.md#several-at-once)) |
 | `notify` | `true` | A desktop [notification](usage.md#notifications) when a long request is done or waits for your answer |
 | `notify_after` | `30` | Seconds a request runs before it notifies |
+| `review` | `off` | Before the answer, [review a change](usage.md#a-review-before-the-answer) against the request and send problems back to the model: `auto` or `off` |
 | `checks` | `auto` | Run the project's [checks](usage.md#checks-before-done) after a request changed files: `auto` (found from the project), `off`, or a command |
 | `repeat_limit` | `3` | Identical tool calls with identical results before lcode [steps in](how-it-works.md#when-the-model-repeats-itself); `0` turns it off |
 | `secret_check` | `true` | Before `git commit` and `git push`, look for passwords, keys and tokens they'd add ([details](usage.md#secrets-in-commits)) |

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

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

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

@@ -179,6 +179,32 @@ command = "uv run pytest -q && uv run ruff check ."
 Or set it for yourself with `lcode config set checks "make check"`; `lcode config set checks off`
 turns checks off.
 
+## A review before the answer
+
+Models claim more than they did: half of a two-part request done, "it works now" without having
+checked, a debug print left behind. So after a request that changed files (and after the
+[checks](#checks-before-done)), lcode asks the model to step back and review its change against your
+request. It's told to judge only from what you asked, the diff, and its own answer:
+
+```text
+◆ Review: the change does what was asked.
+⚠ Review: 1 point(s) sent back to the model. First: README.md isn't changed, though …
+```
+
+Problems it can point to go back to the model once; it fixes them, or says why a point is wrong.
+`lcode -p --output json` reports what the review found in `review`.
+
+**It's off by default,** because it's an extra model answer after every change. On the 12 GB laptop
+with qwen3.6-35b, the 8 `lcode bench` tasks took 416 s with the review against 240 s without
+(8/8 against 7/8, within run-to-run noise). It found a real gap in one run of `runtime-bug` ("it can't
+be made smaller" left undone), which the model then argued away. Without reasoning, the review was
+no faster and missed that gap every time, so it reasons like the model does. Turn it on with
+`lcode config set review auto` when a stronger or faster model makes the extra look worth it.
+
+The review is asked on top of the conversation rather than in a fresh one. The model server keeps
+the processed conversation cached, and a separate review would push it out, so the next request
+would have to read the whole conversation again. On a small GPU that's tens of seconds.
+
 ## Background commands
 
 Some commands keep running: a dev server, a test watcher, a build in watch mode. The model starts

{lcode_cli-0.31.0 → lcode_cli-0.32.0}/pyproject.toml

@@ -78,6 +78,7 @@ ignore = [
 "src/lcode/memory.py" = ["E501"]
 "src/lcode/subagents.py" = ["E501"]
 "src/lcode/planning.py" = ["E501"]
+"src/lcode/review.py" = ["E501"] # the review prompt is prose
 "src/lcode/extensions.py" = ["E501"]
 "src/lcode/context.py" = ["E501"]
 "src/lcode/lsp.py" = ["E501"]

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

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

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

@@ -35,6 +35,7 @@ from lcode import (
     planning,
     repomap,
     residency,
+    review,
     sessions,
     subagents,
     vision,
@@ -276,6 +277,7 @@ class Settings:
     compact_at: int = 0  # tokens: make room at this size even when the window is larger (0: only at 85%)
     repeat_limit: int = 3  # identical calls with identical results before the model is told (lcode.repeats)
     checks: str = "off"  # the project's checks after a change (lcode.checks): auto, off or a command
+    review: str = "off"  # check a change against the request before the answer (lcode.review): auto or off
 
 
 class Agent:
@@ -334,6 +336,7 @@ class Agent:
         self.autosave = False  # save the session after every step (sessions people resume; not the bench's)
         self._check: tuple[Path, checks.Check | None] | None = None
         self.check_results: list[dict] = []  # the checks of the last request: command, exit code, who ran them
+        self.review_results: list[str] | None = None  # what the last request's review found (None: no review)
         self.sent_chars = 0  # characters of the conversation the model had already read
         self.counted_chars: int | None = None  # characters that ctx_used covers (None: all of them)
         self.turn_status = ""  # how the last request ended: success, max_steps, loop
@@ -831,6 +834,48 @@ class Agent:
             self.last_speed = final.get("eval_count", 0) / seconds if seconds else 0.0
         return message
 
+    def reviewing(self) -> bool:
+        return (
+            self.settings.review != "off" and self.allowed_tools is None and not self.planning() and not self.no_changes
+        )
+
+    def self_review(self, answer: str) -> list[str]:
+        """Check the request's change against the request before the answer counts; the problems found."""
+        budget = int(self.settings.context * 3 * 0.25)
+        diff, changed = review.diff_of(self.tools.before, self.current_text, budget)
+        if changed < review.MIN_CHANGED_LINES:
+            return []
+        request = next(
+            (
+                context_tools.request_text(str(m.get("content", "")))
+                for m in reversed(self.messages)
+                if m.get("role") == "user"
+                and not str(m.get("content", "")).startswith(("[lcode]", sessions.SUMMARY_PREFIX))
+            ),
+            "",
+        )
+        try:
+            with self.console.status("Reviewing the change against your request…", spinner="dots"):
+                problems = review.run(self, request, answer, diff)
+        except OllamaError as e:
+            self.say(f"The review didn't run: {e}", warning=True)
+            return []
+        self.review_results = problems
+        if problems:
+            self.say(
+                f"Review: {len(problems)} point(s) sent back to the model. First: {problems[0][:160]}", warning=True
+            )
+        else:
+            self.say("Review: the change does what was asked.")
+        return problems
+
+    def current_text(self, path: str) -> str | None:
+        p = self.tools.resolve(path)
+        try:
+            return self.tools.read_text(p) if p.is_file() else None
+        except OSError:
+            return None
+
     def checks_prompt(self) -> str:
         check = self.project_check()
         if check is None:
@@ -1026,6 +1071,9 @@ class Agent:
         self.messages.append({"role": "user", "content": self.expand_mentions(user_text) + note})
         self.repeats.reset()
         self.check_results = []
+        self.review_results = None
+        self.tools.before = {}
+        reviewed = False
         changed = verified = False  # files changed in this request; the checks passed since
         check_rounds = 0
         malformed = 0
@@ -1087,6 +1135,12 @@ class Agent:
                         changed = False  # run them again only if the model changes something more
                         continue
                     verified = True
+                if not reviewed and self.tools.before and self.reviewing():
+                    reviewed = True
+                    problems = self.self_review(reply.get("content") or "")
+                    if problems:
+                        self.messages.append({"role": "user", "content": review.feedback(problems)})
+                        continue
                 break
             done: dict[int, str] = {}  # results of subagents that ran together
             together = [

{lcode_cli-0.31.0 → lcode_cli-0.32.0}/src/lcode/api.py

@@ -77,6 +77,7 @@ class Result:
     files_changed: list[dict] = field(default_factory=list)  # {"status": "A" | "M" | "D", "path"}
     usage: dict = field(default_factory=dict)  # requests, prompt_tokens, output_tokens
     checks: list[dict] = field(default_factory=list)  # {"command", "exit_code", "by": "lcode" | "model"}
+    review: list[str] | None = None  # problems the review sent back ([] when it found none; None: no review)
     seconds: float = 0.0
     error: str = ""
 
@@ -198,6 +199,7 @@ def open_agent(cwd: Path, options: Options, console: Console, hw: Hardware | Non
         secret_check=cfg["secret_check"],
         repeat_limit=cfg["repeat_limit"],
         checks=cfg["checks"],
+        review=cfg["review"],
         compact_at=cfg["compact_at"],
     )
     agent = Agent(ollama, settings, cwd, console=console)
@@ -306,6 +308,7 @@ def run_request(agent: Agent, prompt: str) -> Result:
         files_changed=files,
         usage=usage,
         checks=list(agent.check_results),
+        review=agent.review_results,
         seconds=round(time.monotonic() - started, 2),
         error=error,
     )

{lcode_cli-0.31.0 → lcode_cli-0.32.0}/src/lcode/cli.py

@@ -581,6 +581,7 @@ def cmd_bench(args) -> None:
             prune=not args.no_prune,
             compact_at=cfg["compact_at"] if args.compact_at is None else args.compact_at,
             checks=cfg["checks"] if args.checks is None else args.checks,
+            review=cfg["review"] if args.review is None else args.review,
             repo_map=args.repo_map,
             embed_model=cfg["embed_model"] if args.code_search else "off",
         )
@@ -775,6 +776,9 @@ def build_subparsers() -> dict[str, argparse.ArgumentParser]:
     p.add_argument("--repo-map", action="store_true", help="give the model the repository map (off by default)")
     p.add_argument("--code-search", action="store_true", help="index each task's folder and offer semantic code search")
     p.add_argument("--no-prune", action="store_true", help="don't remove old tool output (to compare, with --session)")
+    p.add_argument(
+        "--review", choices=["auto", "off"], help="review each change before it counts (default: the setting)"
+    )
     p.add_argument(
         "--checks",
         metavar="auto|off|COMMAND",

{lcode_cli-0.31.0 → lcode_cli-0.32.0}/src/lcode/config.py

@@ -59,6 +59,7 @@ SETTINGS: dict[str, tuple[object, type, str]] = {
     "subagents": (True, bool, "let the model hand tasks to subagents that have their own context"),
     "notify": (True, bool, "desktop notification when a long request is done or waits for you"),
     "notify_after": (30, int, "seconds a request runs before it notifies (with notify on)"),
+    "review": ("off", str, "before the answer, check a change against the request and send problems back: auto | off"),
     "checks": ("auto", str, "run the project's checks before calling work done: auto | off | a command"),
     "repeat_limit": (3, int, "identical tool calls with identical results before lcode steps in (0: never)"),
     "secret_check": (True, bool, "before git commit and git push, look for passwords, keys and tokens they'd add"),

lcode_cli-0.32.0/src/lcode/review.py

@@ -0,0 +1,103 @@
+"""A second look at a change before the answer goes to the user.
+
+Models claim more than they did: "users can now shrink the window" without having checked, half of a
+two-part request done, a debug print left behind. So when a request changed files, lcode asks the model to
+step back and check its change against the request (what was asked, what the diff shows, what the answer
+claims) before the answer counts. Real problems go back to the model once; the user sees a line about it.
+
+The review is asked on top of the conversation, not in a fresh one: the model server keeps the processed
+conversation cached, and a separate review prompt would push it out, so the next step would have to read the
+whole conversation again, tens of seconds on a small GPU. The question tells the model to judge only from the
+request and the diff.
+"""
+
+from __future__ import annotations
+
+import difflib
+from typing import TYPE_CHECKING
+
+from lcode.gitflow import parse_json
+
+if TYPE_CHECKING:
+    from lcode.agent import Agent
+
+MIN_CHANGED_LINES = 1  # even one line: a one-line bug fix is where a wrong fix hides
+MAX_PROBLEMS = 5
+SCHEMA = {
+    "type": "object",
+    "properties": {"problems": {"type": "array", "items": {"type": "string"}}},
+    "required": ["problems"],
+}
+PROMPT = """[lcode] Before your answer goes to the user, review your change as a strict reviewer would: judge it only by what the user asked and what the diff shows, not by what you meant to do.
+
+The user's request:
+<request>
+{request}
+</request>
+
+Your answer to them:
+<answer>
+{answer}
+</answer>
+
+{checks}The change (unified diff of the files changed in this request):
+<diff>
+{diff}
+</diff>
+
+Find real problems only, each one you can point to in the request or the diff:
+1. Something the user asked for that the change doesn't do, or only partly does.
+2. A claim in your answer that the diff doesn't support, or something called tested or working that nothing shows was run.
+3. A mistake in the diff: a bug, a broken edge case the request mentions, leftover debugging (prints, commented-out code), an unfinished TODO.
+No style preferences, no suggestions beyond the request. Answer in JSON: {{"problems": ["…"]}}, with an empty list when the change does what was asked."""
+
+FEEDBACK = """[lcode] A review of your change against the user's request found:
+{problems}
+
+Fix what's real; if a point is wrong, say why in your answer. Then finish."""
+
+
+def diff_of(before: dict[str, str | None], read, budget: int) -> tuple[str, int]:
+    """The unified diff of the files changed in the request, and how many lines it changes."""
+    parts, changed = [], 0
+    for path, old in before.items():
+        new = read(path)
+        if new is None or new == old:
+            continue
+        lines = list(
+            difflib.unified_diff((old or "").splitlines(True), new.splitlines(True), f"a/{path}", f"b/{path}", n=2)
+        )
+        changed += sum(1 for line in lines if line[:1] in "+-" and not line.startswith(("+++", "---")))
+        parts.append("".join(lines))
+    text = "".join(parts)
+    if len(text) > budget:
+        text = text[:budget] + f"\n[… the rest of the diff ({len(text) - budget} characters) is cut]"
+    return text, changed
+
+
+def run(agent: Agent, request: str, answer: str, diff: str) -> list[str]:
+    """Ask for the review; the problems it found (empty when none, or when the answer can't be read)."""
+    checks = ""
+    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})"
+        checks = f"The project's checks (`{last.get('command')}`) {state} after the change.\n\n"
+    prompt = PROMPT.format(request=request[:4000], answer=answer[:3000] or "(none)", checks=checks, diff=diff)
+    payload = {
+        "model": agent.settings.model,
+        "messages": [*agent.messages, {"role": "user", "content": prompt}],
+        "tools": agent.tool_schemas(),  # as in the session, so the cached conversation is reused
+        "think": agent.settings.think,  # without reasoning it missed every gap it caught with it, and wasn't faster
+        "format": SCHEMA,
+        "keep_alive": agent.settings.keep_alive,
+        "options": agent.options(),
+    }
+    reply = agent.ollama.chat(payload)
+    data = parse_json((reply.get("message") or {}).get("content") or "")
+    problems = data.get("problems") if isinstance(data.get("problems"), list) else []
+    return [str(p).strip()[:500] for p in problems if str(p).strip()][:MAX_PROBLEMS]
+
+
+def feedback(problems: list[str]) -> str:
+    return FEEDBACK.format(problems="\n".join(f"- {p}" for p in problems))

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

@@ -448,6 +448,7 @@ class Toolbox:
         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.before: dict[str, str | None] = {}  # files changed in this request: their text before (None: new)
         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
@@ -870,6 +871,8 @@ class Toolbox:
         p.parent.mkdir(parents=True, exist_ok=True)
         fmt = self.formats.get(str(p)) or (decode(p.read_bytes())[1] if p.exists() else TextFormat())
         data = encode(content, fmt)  # before anything is written: it may not be possible
+        if self.rel(p) not in self.before:
+            self.before[self.rel(p)] = decode(p.read_bytes())[0] if p.exists() else None
         if self.writer is not None:
             self.writer(p, content)  # the editor updates its buffer (and the file)
         if not p.exists() or p.read_bytes() != data:

lcode_cli-0.32.0/tests/test_review.py

@@ -0,0 +1,94 @@
+"""Self-review (#114): a change is checked against the request before the answer counts."""
+
+import json
+
+from conftest import call, output, reply
+from lcode import api, review
+from lcode.ollama import OllamaError
+
+NEW = (
+    "import sys\n\n\ndef main(argv):\n    verbose = '--verbose' in argv\n"
+    "    print(sum(int(a) for a in argv if a != '--verbose'))\n"
+)
+
+
+def text(agent):
+    return " ".join(output(agent).split())
+
+
+def changing(make_agent, *after, **settings):
+    return make_agent(
+        [
+            reply(tool_calls=[call("write_file", path="app.py", content=NEW)]),
+            reply("Added --verbose and documented it."),
+            *after,
+        ],
+        **{"review": "auto", **settings},
+    )
+
+
+def test_problems_go_back_to_the_model_once(make_agent):
+    agent = changing(make_agent, reply("Fixed: the flag now prints each number, and README.md documents it."))
+    agent.ollama.chat_replies = [
+        json.dumps({"problems": ["README.md isn't changed, though the user asked to document the flag."]})
+    ]
+    agent.run_turn("add --verbose and document it in README.md")
+    note = next(
+        m["content"] for m in agent.messages if m["role"] == "user" and m["content"].startswith("[lcode] A review")
+    )
+    assert "- README.md isn't changed" in note and "Fix what's real" in note
+    assert agent.messages[-1]["content"].startswith("Fixed:")
+    assert "Review: 1 point(s) sent back to the model" in text(agent)
+    assert agent.review_results == ["README.md isn't changed, though the user asked to document the flag."]
+    asked = agent.ollama.chats[0]
+    assert "add --verbose and document it in README.md" in asked["messages"][-1]["content"]
+    assert "+    verbose = '--verbose' in argv" in asked["messages"][-1]["content"]  # the diff
+    assert asked["format"] == review.SCHEMA
+
+
+def test_a_clean_review_adds_no_step(make_agent):
+    agent = changing(make_agent)
+    agent.ollama.chat_replies = [json.dumps({"problems": []})]
+    agent.run_turn("add --verbose")
+    assert agent.messages[-1]["content"] == "Added --verbose and documented it."
+    assert "Review: the change does what was asked." in text(agent) and agent.review_results == []
+
+
+def test_no_review_without_a_change_or_when_off(make_agent):
+    reading = make_agent(
+        [reply(tool_calls=[call("read_file", path="README.md")]), reply("It's a demo.")], review="auto"
+    )
+    reading.run_turn("what is this?")
+    assert reading.ollama.chats == [] and reading.review_results is None
+    off = changing(make_agent, review="off")
+    off.run_turn("add --verbose")
+    assert off.ollama.chats == []
+    planner = make_agent(mode="plan", review="auto")
+    assert not planner.reviewing()
+
+
+def test_a_review_that_fails_doesnt_stop_the_answer(make_agent):
+    agent = changing(make_agent)
+
+    def broken(payload):
+        raise OllamaError("model crashed")
+
+    agent.ollama.chat = broken
+    agent.run_turn("add --verbose")
+    assert agent.messages[-1]["content"] == "Added --verbose and documented it."
+    assert "The review didn't run: model crashed" in text(agent)
+
+
+def test_the_diff_covers_only_this_request(tmp_path):
+    files = {"a.py": "x = 1\ny = 2\nz = 3\n", "new.py": "print('hi')\n"}
+    diff, changed = review.diff_of(
+        {"a.py": "x = 1\ny = 0\nz = 3\n", "new.py": None, "same.py": "q\n"}, files.get, 10_000
+    )
+    assert "-y = 0\n+y = 2" in diff and "+print('hi')" in diff and "same.py" not in diff and changed == 3
+    cut, _ = review.diff_of({"a.py": ""}, lambda p: "x\n" * 5000, 100)
+    assert cut.endswith("is cut]")
+
+
+def test_programs_see_the_review(make_agent):
+    result = api.Result(status="success", text="", session_id="s", model="m", review=["README.md not updated"])
+    assert result.to_json()["review"] == ["README.md not updated"]