lcode-cli 0.23.0__tar.gz → 0.25.0__tar.gz

{lcode_cli-0.23.0 → lcode_cli-0.25.0}/CHANGELOG.md

@@ -6,6 +6,38 @@ All notable changes to lcode are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.25.0] - 2026-10-10
+
+### Changed
+
+- The model is told what counts as checking its work: run what it changed the way it will be used,
+  reproduce each reported problem before fixing it, check what it can't see (GUIs, web pages,
+  layouts) without a screen, for example with Qt's `offscreen` platform, a headless browser or a
+  rendered image, and never call something tested or done without having run it. See
+  [Checking its own work](https://nasser1941.github.io/lcode/how-it-works/#checking-its-own-work).
+
+### Added
+
+- `lcode bench --tasks runtime-bug`: a bug that shows only when the code runs, a camera wall whose
+  window grows with every video frame. Reading the code suggests band-aids that fail its hidden
+  test. It isn't in the default set.
+
+## [0.24.0] - 2026-10-10
+
+### Added
+
+- Ctrl+V in lcode's prompt pastes a screenshot: lcode reads the clipboard (with `wl-paste` on
+  Wayland, `xclip` on X11, `pngpaste` or `osascript` on macOS), saves the image and attaches it as
+  `@path`. Other clipboard content is pasted as text. `lcode doctor` shows whether it works here.
+- Image paths in a message are attached without `@`: absolute and `~` paths, quoted paths with
+  spaces, and `file://` paths dragged into the terminal. `@"path with spaces"` works for any file.
+
+### Fixed
+
+- An image path that doesn't exist is no longer ignored: lcode says so, and tells the model it can't
+  see that image, so it asks instead of guessing what the picture shows. See
+  [Images](https://nasser1941.github.io/lcode/usage/#images).
+
 ## [0.23.0] - 2026-10-10
 
 ### Added
@@ -508,7 +540,9 @@ 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.23.0...HEAD
+[Unreleased]: https://github.com/nasser1941/lcode/compare/v0.25.0...HEAD
+[0.25.0]: https://github.com/nasser1941/lcode/compare/v0.24.0...v0.25.0
+[0.24.0]: https://github.com/nasser1941/lcode/compare/v0.23.0...v0.24.0
 [0.23.0]: https://github.com/nasser1941/lcode/compare/v0.22.0...v0.23.0
 [0.22.0]: https://github.com/nasser1941/lcode/compare/v0.21.0...v0.22.0
 [0.21.0]: https://github.com/nasser1941/lcode/compare/v0.20.0...v0.21.0

{lcode_cli-0.23.0 → lcode_cli-0.25.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: lcode-cli
-Version: 0.23.0
+Version: 0.25.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.23.0 → lcode_cli-0.25.0}/docs/bench.md

@@ -38,8 +38,10 @@ A model usually takes 4 to 12 minutes; each task stops after 5 minutes (`--timeo
 ### More tasks and features
 
 `--tasks find-concept` adds a task in a larger repository: 40 files of a small backend where the
-model has to find a function by what it does. It isn't in the default set, so results stay
-comparable with earlier versions. `--repo-map` gives the model the [repository map](search.md) and
+model has to find a function by what it does. `--tasks runtime-bug` adds a bug that shows only
+when the code runs: a camera wall's window grows taller with every video frame and can't be made
+smaller again. Reading the code suggests band-aids that fail the hidden test; running it shows the
+cause. Neither is in the default set, so results stay comparable with earlier versions. `--repo-map` gives the model the [repository map](search.md) and
 `--code-search` indexes each task's folder for [semantic search](search.md#semantic-code-search);
 both are off in `lcode bench` by default, for the same reason.
 

{lcode_cli-0.23.0 → lcode_cli-0.25.0}/docs/how-it-works.md

@@ -29,6 +29,19 @@ All tools return text, and failures come back to the model as `Error: …` messa
 crashing the session, so the model can correct itself (for example re-read a file when an edit
 didn't match).
 
+### Checking its own work
+
+Small models like to call work done after a syntax check. The system prompt tells the model what
+counts as checked:
+
+- run what it changed the way it will be used;
+- reproduce a bug before fixing it, then show it's gone;
+- check what it can't see (a GUI, a web page, a layout) without a screen: Qt's `offscreen`
+  platform, a headless browser, or a script that prints sizes or renders an image it then looks
+  at;
+- never mark a task done or call something tested without having run it, and tell you what to
+  look at when it couldn't check.
+
 ### When the model repeats itself
 
 Small models sometimes fall into a loop: they make a call, get a result, and make the very same call

{lcode_cli-0.23.0 → lcode_cli-0.25.0}/docs/quickstart.md

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

{lcode_cli-0.23.0 → lcode_cli-0.25.0}/docs/usage.md

@@ -154,8 +154,19 @@ lcode can look at screenshots, mockups, diagrams and photos:
 ❯ make the settings page match @design/settings.png
 ```
 
-- Attach an image with `@path`, like a file. lcode describes it in detail, with all visible text
-  transcribed and with your question in mind, and the model works from that description.
+- **Paste a screenshot with ++ctrl+v++.** A terminal can only paste text, so lcode reads the
+  clipboard itself, saves the image in its state folder (`~/.local/state/lcode/pasted/`, the last
+  50) and puts `@path` in the prompt. Anything else on the clipboard is pasted as text. It needs
+  `wl-clipboard` on Wayland or `xclip` on X11 (`sudo apt install wl-clipboard`); on macOS it works
+  as is, and faster with `brew install pngpaste`. `lcode doctor` shows whether it works.
+- Attach an image with `@path`, like a file, or just write its path: `/tmp/shot.png`,
+  `~/Pictures/bug.png`, `'./shots/My Shot.png'` and `file://` paths dragged into the terminal are
+  attached too. lcode describes the image in detail, with all visible text transcribed and with your
+  question in mind, and the model works from that description.
+- **A path to an image that doesn't exist** is reported right away
+  (`/tmp/pasted-image-.png doesn't exist, so the model can't see it`), and the model is told it
+  can't see the image, so it asks instead of guessing what it shows. A bare name such as `logo.png`
+  may be a file you want created, so it's left alone.
 - The model can open images itself with the `view_image` tool, for example a screenshot a test wrote.
 - Screenshots that [MCP](mcp.md) tools return, such as the Playwright browser's, are described too.
 

{lcode_cli-0.23.0 → lcode_cli-0.25.0}/pyproject.toml

@@ -82,6 +82,7 @@ ignore = [
 "src/lcode/context.py" = ["E501"]
 "src/lcode/lsp.py" = ["E501"]
 "src/lcode/repomap.py" = ["E501"]
+"src/lcode/bench_runtime.py" = ["E501"] # the task's files and hidden test
 "src/lcode/codesearch.py" = ["E501"]
 "src/lcode/bench_backend.py" = ["E501"]
 "src/lcode/backends.py" = ["E501"]

{lcode_cli-0.23.0 → lcode_cli-0.25.0}/src/lcode/__init__.py

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

{lcode_cli-0.23.0 → lcode_cli-0.25.0}/src/lcode/agent.py

@@ -11,6 +11,7 @@ import shutil
 import subprocess
 import threading
 import time
+import urllib.parse
 import uuid
 from collections.abc import Callable
 from dataclasses import dataclass
@@ -63,6 +64,15 @@ MAX_MALFORMED_CALL_RETRIES = 2  # Ollama rejects tool calls whose arguments aren
 MALFORMED_CALL = ("error parsing tool call", "XML syntax error")
 AUTO_COMPACT_RATIO = 0.85  # summarize the history when the context is this full
 PRUNED_ENOUGH = 0.6  # after pruning old tool output, summarize only if the context is still this full
+# @path, @"path with spaces" or @'path'
+MENTION = re.compile(r"""(?<!\S)@(?:"([^"\n]+)"|'([^'\n]+)'|([\w./~\-]+))""")
+# An image path written in a message: in quotes, or without spaces (a space escaped as "\ " is fine), or as a
+# file:// address, the way terminals paste a dragged file.
+IMAGE_PATH = re.compile(
+    r"""(['"])((?:file://)?[^'"\n]+?\.(?:png|jpe?g|webp|gif))\1"""
+    r"""|(?<![^\s(])((?:[^\s\\'"(]|\\ )+?\.(?:png|jpe?g|webp|gif))(?=[\s,;:!?)\]]|\.(?:\s|$)|$)""",
+    re.IGNORECASE,
+)
 PROJECT_FILES = ("AGENTS.md", "LCODE.md", "CLAUDE.md")
 
 SYSTEM_PROMPT = """You are lcode, an autonomous software-engineering agent running in the user's terminal on their own machine, powered by the local model {model}. You help the user understand codebases, answer questions about code, write scripts (Python by default), fix bugs, refactor, and run commands.
@@ -71,14 +81,18 @@ SYSTEM_PROMPT = """You are lcode, an autonomous software-engineering agent runni
 - Use your tools to gather facts. Never guess file contents, APIs, or command output — read, search, or run them.
 - 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).
-- After writing or changing code, verify it: run the script, the tests, or at least a syntax check (e.g. `{python} -m py_compile file.py`). Fix what fails.
 - 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.
 - 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.
-- Never claim something works without having run it. If something fails, say so and show the relevant error.
 - If the user denies a tool call, don't retry the same thing; adjust or ask.
 
+# Verifying your work
+- A syntax check or an import only shows that code loads. Run what you changed the way it will be used (the script, the tests, the app) and fix what fails.
+- To fix a bug, first reproduce each problem the user reports with a test, a command or a short script, then run the same checks to show they're gone.
+- For what you can't see, like a GUI, a web page or a layout, check it without a screen where you can: `QT_QPA_PLATFORM=offscreen` for Qt, a headless browser, or a script that prints sizes and positions or renders to an image{look}. Measure instead of assuming.
+- Never claim something works, mark a todo done, or call it tested unless you ran it. If you couldn't check something, say so and tell the user exactly what to look for. If something fails, say so and show the relevant error.
+
 # Communication
 - Be concise and direct; no filler. Use GitHub-flavored markdown.
 - When you finish, give a short summary of what you found or changed and anything the user needs to do.
@@ -307,6 +321,7 @@ class Agent:
             skills=extensions.skills_prompt(self.extensions().skills, self.settings.context),
             code=self.code_prompt(),
             map=self.map_prompt(),
+            look=" you look at with view_image" if self.vision_model() else "",
         )
 
     def repo_map(self) -> repomap.RepoMap | None:
@@ -965,30 +980,68 @@ class Agent:
         )
 
     def expand_mentions(self, text: str) -> str:
-        """Inline files referenced as @path in the user's message; @name of an agent asks for that agent."""
-        attached = []
-        for ref in re.findall(r"(?<!\S)@([\w./~\-]+)", text):
+        """Attach what the user's message points to: files and folders written as @path, image paths (with or
+        without @), and @name of an agent asks for that agent. An image path that doesn't exist is reported to
+        the user and the model, so the model doesn't guess what the image shows."""
+        attached: list[str] = []
+        seen: set[Path] = set()
+        question = MENTION.sub("", text)
+
+        def attach_image(p: Path) -> None:
+            try:
+                description = self.look(p, question)
+                who = f' described_by="{self.vision_model()}"'
+            except ToolError as e:
+                description, who = f"(lcode couldn't look at this image: {e})", ""
+                self.console.print(Text(f"  ⎿ {e}", style="yellow"))
+            else:
+                self.console.print(Text(f"  ⎿ looked at {self.tools.rel(p)}", style="dim"))
+            attached.append(f'<image path="{self.tools.rel(p)}"{who}>\n{description}\n</image>')
+
+        def missing_image(shown: str) -> None:
+            self.console.print(
+                Text(f"  ⎿ {shown} doesn't exist, so the model can't see it. Paste images with Ctrl+V.", style="yellow")
+            )
+            attached.append(
+                f"[lcode: the user's message mentions the image {shown}, but there's no such file, so it wasn't "
+                "attached and you can't see it. Don't guess what it shows: ask the user to paste it again (Ctrl+V "
+                "in lcode's prompt) or to describe it.]"
+            )
+
+        for match in MENTION.finditer(text):
+            ref = next(g for g in match.groups() if g)
             p = self.tools.resolve(ref)
+            seen.add(p)
             name = ref.removeprefix("agent-")
             if not p.exists() and self.settings.subagents and name in self.agent_types():
                 attached.append(f'[The user wants the {name} agent for this: call the agent tool with type "{name}".]')
                 continue
             if p.is_file() and vision.is_image(p):
-                try:
-                    description = self.look(p, re.sub(r"(?<!\S)@[\w./~\-]+", "", text))
-                    who = f' described_by="{self.vision_model()}"'
-                except ToolError as e:
-                    description, who = f"(lcode couldn't look at this image: {e})", ""
-                    self.console.print(Text(f"  ⎿ {e}", style="yellow"))
-                else:
-                    self.console.print(Text(f"  ⎿ looked at {self.tools.rel(p)}", style="dim"))
-                attached.append(f'<image path="{self.tools.rel(p)}"{who}>\n{description}\n</image>')
+                attach_image(p)
             elif p.is_file() and not is_binary(p) and p.stat().st_size < 200_000:
                 attached.append(f'<file path="{self.tools.rel(p)}">\n{p.read_text(errors="replace")}\n</file>')
                 self.tools.read_mtimes[str(p)] = p.stat().st_mtime
                 self.console.print(Text(f"  ⎿ attached {self.tools.rel(p)}", style="dim"))
             elif p.is_dir():
                 attached.append(f'<directory path="{self.tools.rel(p)}">\n{tree(p, 2)}\n</directory>')
+            elif not p.exists() and vision.is_image(p):
+                missing_image(ref)
+        for match in IMAGE_PATH.finditer(text):
+            quoted, raw = bool(match.group(2)), match.group(2) or match.group(3)
+            if raw.startswith("@") or "://" in raw.removeprefix("file://"):
+                continue  # attached above, or a web address
+            if raw.startswith("file://"):
+                shown = urllib.parse.unquote(raw.removeprefix("file://"))
+            else:
+                shown = raw.replace("\\ ", " ")
+            p = self.tools.resolve(shown)
+            if p in seen:
+                continue
+            seen.add(p)
+            if p.is_file():
+                attach_image(p)
+            elif quoted or raw.startswith(("/", "~", "./", "../", "file://")):
+                missing_image(shown)  # a name without a folder may be a file to create: no warning
         return text + ("\n\n" + "\n\n".join(attached) if attached else "")
 
     # -- context management

{lcode_cli-0.23.0 → lcode_cli-0.25.0}/src/lcode/bench.py

@@ -746,7 +746,7 @@ TASKS = [
 
 def extra_tasks() -> list[Task]:
     """Tasks that only run when asked for with --tasks (they're slower, or test optional features)."""
-    from lcode import bench_backend
+    from lcode import bench_backend, bench_runtime
 
     return [
         Task(
@@ -755,7 +755,14 @@ def extra_tasks() -> list[Task]:
             bench_backend.PROMPT,
             bench_backend.FILES,
             bench_backend.check,
-        )
+        ),
+        Task(
+            "runtime-bug",
+            "Fix a bug that shows only when it runs",
+            bench_runtime.PROMPT,
+            bench_runtime.FILES,
+            bench_runtime.check,
+        ),
     ]
 
 

lcode_cli-0.25.0/src/lcode/bench_runtime.py

@@ -0,0 +1,156 @@
+"""A bug that only shows when the code runs, for `lcode bench --tasks runtime-bug`.
+
+A camera wall lays out video panels in a window. While video plays, the window grows taller frame after
+frame, past the screen, and can't be made smaller again: each panel's minimum size is taken from the
+frame it shows, and the frame is scaled to the whole cell, status bar included. Reading the code, the
+obvious fixes are band-aids (ignore the minimum sizes, or only fix the scaling) that fail part of the
+hidden test. Running it, the window sizes show the ratchet. It's the kind of bug a GUI has, without
+needing one, and rewards reproducing a problem before fixing it.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+WALL = '''\
+"""A camera wall: a window with a grid of panels, each showing its camera's latest video frame."""
+
+SPACING = 8  # pixels between and around the panels
+STATUS_BAR = 20  # under its video, each panel shows the camera's name and status
+
+
+class Panel:
+    def __init__(self, name):
+        self.name = name
+        self.min_width = self.min_height = 1  # the panel can't get smaller than this
+        self.video = (0, 0)  # the size of the frame on screen
+
+    def show(self, frame_width, frame_height, cell_width, cell_height):
+        """Show a frame scaled to fit the panel's cell, keeping its aspect ratio."""
+        scale = min(cell_width / frame_width, cell_height / frame_height)
+        self.video = (int(frame_width * scale), int(frame_height * scale))
+        # The video and the status bar under it must stay visible.
+        self.min_width, self.min_height = self.video[0], self.video[1] + STATUS_BAR
+
+
+class Wall:
+    def __init__(self, names, rows, cols):
+        self.rows, self.cols = rows, cols
+        self.panels = [Panel(name) for name in names]
+        self.width = self.height = 0
+
+    def resize(self, width, height):
+        """Ask for a window size. The window can't be smaller than its panels need."""
+        need_width = max(p.min_width for p in self.panels) * self.cols + SPACING * (self.cols + 1)
+        need_height = max(p.min_height for p in self.panels) * self.rows + SPACING * (self.rows + 1)
+        self.width, self.height = max(width, need_width), max(height, need_height)
+
+    def cell(self):
+        """The size of one panel's cell."""
+        return (
+            (self.width - SPACING * (self.cols + 1)) // self.cols,
+            (self.height - SPACING * (self.rows + 1)) // self.rows,
+        )
+
+    def new_frame(self, frame_width, frame_height):
+        """Every camera delivered a frame: show it in each panel, then let the layout settle."""
+        cell_width, cell_height = self.cell()
+        for panel in self.panels:
+            panel.show(frame_width, frame_height, cell_width, cell_height)
+        self.resize(self.width, self.height)
+'''
+
+SIMULATE = '''\
+"""Play the camera wall without a screen: python simulate.py [WIDTH HEIGHT [ROWSxCOLS]]"""
+
+import sys
+
+from wall import Wall
+
+
+def main():
+    width, height = (int(sys.argv[1]), int(sys.argv[2])) if len(sys.argv) > 2 else (2560, 1080)
+    rows, cols = map(int, sys.argv[3].split("x")) if len(sys.argv) > 3 else (3, 3)
+    wall = Wall([f"camera {n + 1}" for n in range(rows * cols)], rows, cols)
+    wall.resize(width * 9 // 10, height * 9 // 10)
+    print(f"{rows}x{cols} wall on a {width}x{height} screen, window {wall.width}x{wall.height}")
+    for n in range(1, 6):
+        wall.new_frame(1920, 1080)
+        print(f"after frame {n}: window {wall.width}x{wall.height}, video {wall.panels[0].video}")
+
+
+if __name__ == "__main__":
+    main()
+'''
+
+FILES = {"wall.py": WALL, "simulate.py": SIMULATE}
+
+PROMPT = (
+    "Users say the camera wall in wall.py keeps growing taller while video plays, until it's bigger than "
+    "their screen, and after that it can't be made smaller again. Fix it."
+)
+
+HIDDEN_TEST = """\
+import unittest
+
+from wall import SPACING, STATUS_BAR, Wall
+
+SCREENS = [(2560, 1080, 3, 3), (1920, 1080, 2, 3), (1366, 768, 3, 3), (3440, 1440, 2, 4), (1280, 1024, 2, 2)]
+
+
+def play(width, height, rows, cols, frames=30, frame=(1920, 1080)):
+    wall = Wall([f"camera {n}" for n in range(rows * cols)], rows, cols)
+    wall.resize(width, height)
+    for _ in range(frames):
+        wall.new_frame(*frame)
+    return wall
+
+
+class HiddenTest(unittest.TestCase):
+    def test_keeps_its_size(self):
+        for width, height, rows, cols in SCREENS:
+            with self.subTest(screen=(width, height), grid=(rows, cols)):
+                wall = play(width * 9 // 10, height * 9 // 10, rows, cols)
+                self.assertEqual((wall.width, wall.height), (width * 9 // 10, height * 9 // 10))
+
+    def test_can_be_made_smaller(self):
+        wall = play(2304, 972, 3, 3)
+        wall.resize(1280, 720)
+        wall.new_frame(1920, 1080)
+        self.assertEqual((wall.width, wall.height), (1280, 720))
+
+    def test_video_fits_and_fills_its_cell(self):
+        for width, height, rows, cols in SCREENS:
+            for frame in [(1920, 1080), (1280, 960), (720, 1280)]:
+                with self.subTest(screen=(width, height), grid=(rows, cols), frame=frame):
+                    wall = play(width * 9 // 10, height * 9 // 10, rows, cols, frames=3, frame=frame)
+                    cell_width = (wall.width - SPACING * (cols + 1)) // cols
+                    cell_height = (wall.height - SPACING * (rows + 1)) // rows
+                    for panel in wall.panels:
+                        video_width, video_height = panel.video
+                        self.assertLessEqual(video_width, cell_width)
+                        self.assertLessEqual(video_height + STATUS_BAR, cell_height)
+                        fills = video_width >= cell_width - 2 or video_height + STATUS_BAR >= cell_height - 2
+                        self.assertTrue(fills, "the video doesn't use the room it has")
+                        self.assertAlmostEqual(video_width / video_height, frame[0] / frame[1], delta=0.02)
+"""
+
+PROBLEMS = {
+    "test_keeps_its_size": "the window still grows",
+    "test_can_be_made_smaller": "the window can't be made smaller",
+    "test_video_fits_and_fills_its_cell": "the video doesn't fit its cell above the status bar (or doesn't fill it)",
+}
+
+
+def check(folder: Path, answer: str):
+    from lcode.bench import Check, last_line, run_python
+
+    if not (folder / "wall.py").is_file():
+        return Check(False, "wall.py is missing")
+    (folder / "test_hidden_wall.py").write_text(HIDDEN_TEST)
+    r = run_python(folder, "-m", "unittest", "-q", "test_hidden_wall")
+    if r.returncode == 0:
+        return Check(True, "keeps its size, can be made smaller, and the video fits")
+    failed = [text for name, text in PROBLEMS.items() if re.search(rf"\b{name}\b", r.stderr)]
+    return Check(False, "; ".join(failed) or last_line(r.stderr) or last_line(r.stdout))

{lcode_cli-0.23.0 → lcode_cli-0.25.0}/src/lcode/cli.py

@@ -346,6 +346,10 @@ def cmd_doctor(args) -> None:
             line("Vision", "off; set vision_model to a model the server serves that can see images", None)
         else:
             line("Vision", "off" if cfg["vision_model"] == "off" else vision.INSTALL_HINT, None)
+        if seer:
+            from lcode import clipboard
+
+            line("Clipboard", *clipboard.status())
         if limits.get(model):
             line(
                 "Limit",

lcode_cli-0.25.0/src/lcode/clipboard.py

@@ -0,0 +1,139 @@
+"""Paste from the clipboard with Ctrl+V, images included.
+
+A terminal can only paste text, so a screenshot never reaches lcode that way. On Ctrl+V lcode reads the
+clipboard itself: with wl-paste on Wayland, xclip on X11, and pngpaste or osascript on macOS. An image is
+saved in lcode's state folder and goes into the prompt as `@path`, so it's attached like any other image;
+anything else is pasted as text.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from lcode import config
+
+TIMEOUT = 5  # seconds for a clipboard tool
+IMAGE_TYPES = ("image/png", "image/jpeg", "image/webp", "image/gif")
+SUFFIXES = {"image/png": ".png", "image/jpeg": ".jpg", "image/webp": ".webp", "image/gif": ".gif"}
+KEEP = 50  # pasted images kept; older ones are removed
+
+
+@dataclass
+class Paste:
+    image: Path | None = None  # a saved image
+    text: str = ""  # or text
+    problem: str = ""  # why nothing could be pasted
+
+
+def run(argv: list[str]) -> bytes | None:
+    try:
+        done = subprocess.run(argv, capture_output=True, timeout=TIMEOUT, check=False)
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return done.stdout if done.returncode == 0 else None
+
+
+def folder() -> Path:
+    return config.STATE_DIR / "pasted"
+
+
+def save(data: bytes, suffix: str) -> Path:
+    where = folder()
+    where.mkdir(parents=True, exist_ok=True)
+    old = sorted(where.glob("pasted-*"))  # the names sort by time
+    for path in old[: max(0, len(old) - KEEP + 1)]:
+        path.unlink(missing_ok=True)
+    now = time.time_ns()
+    stamp = f"{time.strftime('%Y%m%d-%H%M%S', time.localtime(now / 1e9))}-{now % 1_000_000_000:09d}"
+    path = where / f"pasted-{stamp}{suffix}"
+    n = 1
+    while path.exists():
+        n += 1
+        path = where / f"pasted-{stamp}-{n}{suffix}"
+    path.write_bytes(data)
+    return path
+
+
+def pick(types: list[str]) -> str | None:
+    return next((t for t in IMAGE_TYPES if t in types), None)
+
+
+def paste() -> Paste:
+    """Whatever is on the clipboard: an image (saved to a file) or text."""
+    if sys.platform == "darwin":
+        return paste_mac()
+    if os.environ.get("WAYLAND_DISPLAY") and shutil.which("wl-paste"):
+        return paste_with(
+            ["wl-paste", "--list-types"],
+            lambda kind: ["wl-paste", "--no-newline", "--type", kind],
+            ["wl-paste", "--no-newline"],
+        )
+    if os.environ.get("DISPLAY") and shutil.which("xclip"):
+        return paste_with(
+            ["xclip", "-selection", "clipboard", "-t", "TARGETS", "-o"],
+            lambda kind: ["xclip", "-selection", "clipboard", "-t", kind, "-o"],
+            ["xclip", "-selection", "clipboard", "-o"],
+        )
+    return Paste(problem=status()[0])
+
+
+def status() -> tuple[str, bool | None]:
+    """Whether Ctrl+V can paste images here, and if not, what to do (for the paste and `lcode doctor`)."""
+    if sys.platform == "darwin":
+        return "Ctrl+V pastes images" + (" (with pngpaste)" if shutil.which("pngpaste") else ""), True
+    if os.environ.get("WAYLAND_DISPLAY"):
+        if shutil.which("wl-paste"):
+            return "Ctrl+V pastes images (with wl-paste)", True
+        return "To paste images with Ctrl+V, install wl-clipboard (for example `sudo apt install wl-clipboard`).", None
+    if os.environ.get("DISPLAY"):
+        if shutil.which("xclip"):
+            return "Ctrl+V pastes images (with xclip)", True
+        return "To paste images with Ctrl+V, install xclip (for example `sudo apt install xclip`).", None
+    return "There's no clipboard here (no desktop session), so give an image by its path.", None
+
+
+def paste_with(list_types: list[str], get, get_text: list[str]) -> Paste:
+    types = (run(list_types) or b"").decode(errors="replace").split()
+    kind = pick(types)
+    if kind:
+        data = run(get(kind))
+        if data:
+            return Paste(image=save(data, SUFFIXES[kind]))
+    text = run(get_text)
+    if text:
+        return Paste(text=text.decode(errors="replace"))
+    return Paste(problem="The clipboard is empty.")
+
+
+def paste_mac() -> Paste:
+    if shutil.which("pngpaste"):
+        data = run(["pngpaste", "-"])
+        if data:
+            return Paste(image=save(data, ".png"))
+    else:
+        target = folder() / ".clipboard.png"
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.unlink(missing_ok=True)
+        script = [
+            "try",
+            "set png to (the clipboard as «class PNGf»)",
+            f'set f to open for access POSIX file "{target}" with write permission',
+            "write png to f",
+            "close access f",
+            "end try",
+        ]
+        run(["osascript", *[arg for line in script for arg in ("-e", line)]])
+        if target.exists() and target.stat().st_size:
+            data = target.read_bytes()
+            target.unlink(missing_ok=True)
+            return Paste(image=save(data, ".png"))
+    text = run(["pbpaste"])
+    if text:
+        return Paste(text=text.decode(errors="replace"))
+    return Paste(problem="The clipboard is empty.")