hx-cli 0.2.4__tar.gz → 0.2.5__tar.gz

{hx_cli-0.2.4 → hx_cli-0.2.5}/CHANGELOG.md

@@ -28,6 +28,33 @@ the project follows [semantic versioning](https://semver.org/).
 
 ---
 
+## [0.2.5] - 2026-09-23
+
+### Added
+
+- Images as input. `ctrl+v` attaches the image on the clipboard, dragging an
+  image file into the terminal attaches it, and `hx -p "..." --image PATH`
+  attaches one to a headless prompt. Each shows in the prompt as
+  `[Image #N]`.
+- `Read` returns image files as images, so the model can look at a screenshot
+  or mockup it is pointed at with `@path`.
+- Images returned by MCP tools reach the model instead of being dropped.
+- Every route carries images: OpenRouter, the Codex subscription and the Devin
+  subscription. Large images are scaled and re-encoded to fit each route's
+  limits.
+- A model that does not accept images is warned about when one is attached,
+  and is told the image was left out rather than sent a request that fails.
+  The `/model` picker marks the models that can see images.
+
+### Fixed
+
+- Background jobs are waited for, not only signalled, when a session closes.
+  An unwaited subprocess transport was collected after the event loop had
+  gone, which raised `Event loop is closed` as an unraisable warning on CI
+  runs that otherwise passed.
+
+---
+
 ## [0.2.4] - 2026-09-19
 
 ### Added
@@ -565,7 +592,8 @@ First release, published to PyPI as [`hx-cli`](https://pypi.org/project/hx-cli/)
 - `/configure` and `hx auth` for the OpenRouter key, `hx upgrade` for
   self-update, and `install.sh` bootstrapping uv with a pinned Python.
 
-[Unreleased]: https://github.com/aletisunil/hx/compare/v0.2.4...HEAD
+[Unreleased]: https://github.com/aletisunil/hx/compare/v0.2.5...HEAD
+[0.2.5]: https://github.com/aletisunil/hx/compare/v0.2.4...v0.2.5
 [0.2.4]: https://github.com/aletisunil/hx/compare/v0.2.3...v0.2.4
 [0.2.3]: https://github.com/aletisunil/hx/compare/v0.2.2...v0.2.3
 [0.2.2]: https://github.com/aletisunil/hx/compare/v0.2.1...v0.2.2

{hx_cli-0.2.4 → hx_cli-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hx-cli
-Version: 0.2.4
+Version: 0.2.5
 Summary: HX - an agent harness for the terminal
 Project-URL: Homepage, https://hx.sunilaleti.dev
 Project-URL: Documentation, https://hx.sunilaleti.dev
@@ -18,6 +18,7 @@ Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.11
 Requires-Dist: httpx>=0.27
 Requires-Dist: markdown-it-py>=3.0
+Requires-Dist: pillow>=10.4
 Requires-Dist: pydantic>=2.7
 Requires-Dist: pygments>=2.17
 Requires-Dist: pyyaml>=6.0
@@ -296,6 +297,7 @@ available through OpenRouter.
 ```sh
 hx                          # interactive TUI in the current directory
 hx -p "explain this repo"   # headless: streams to stdout, tool activity to stderr
+hx -p "why?" --image s.png  # attach an image to a headless prompt; repeatable
 hx resume                   # resume the last session here
 hx resume <session-id>      # resume a specific one
 hx prompt                   # print the system prompt this directory would use
@@ -375,6 +377,7 @@ be rebound (see [Keybindings](#keybindings)).
 | `pgdn` | scroll the transcript down (fullscreen; otherwise your terminal scrolls) |
 | `ctrl+home` | jump to the start: the viewport in fullscreen, the first message otherwise |
 | `ctrl+end` | jump back to the newest output |
+| `ctrl+v` | attach the image on the clipboard (see [Images](#images)) |
 | `@path` | complete a file path |
 | `!command` | run a shell command directly, no model turn |
 
@@ -406,6 +409,44 @@ text](#selecting-and-copying-text) for the terminal's own selection.
 HX does not emit OSC 133 prompt markers yet, so shell-integration features that
 jump between prompts will not see HX's messages.
 
+#### Images
+
+Give the model a picture three ways, and each lands in the prompt as a token
+such as `[Image #1]`:
+
+- **`ctrl+v`** attaches whatever image is on the clipboard: a screenshot copied
+  with `cmd+ctrl+shift+4`, an image copied in a browser, or an image file
+  copied in Finder or a file manager. Terminals whose own paste sends nothing
+  when the clipboard holds a picture are caught too - an empty paste is read as
+  a request for the image.
+- **Drag an image file** into the terminal. The terminal pastes its path, and a
+  paste that is nothing but paths to image files attaches them instead of
+  inserting the text. Quoted, backslash-escaped and `file://` paths all work.
+- **Mention it.** `look at @docs/mockup.png` sends the path as text, and the
+  model opens it with `Read`, which returns images as images.
+
+The token is the attachment: move it and the text refers to the picture in a
+different place, delete it (one `backspace` takes the whole token) and the
+image is not sent. Sent messages list their images underneath, with size and
+weight. Numbers run for the whole session, so a message recalled from history
+or restored by a rewind still carries its pictures.
+
+PNG, JPEG, GIF, WebP, BMP and TIFF are accepted. An image within every route's
+limits goes byte for byte; a larger one is scaled to 2000 px on its long side
+and re-encoded to stay under 5 MB, which is what a retina screenshot usually
+needs. Images an MCP tool returns - a browser screenshot, say - are handled the
+same way rather than dropped.
+
+Whether a model can see images comes from the catalogue: OpenRouter's input
+modalities, the Codex catalogue, and Devin's model config. The `/model` picker
+marks the ones that can with `images`. A model that cannot
+is warned about when you attach, and is sent a line saying an image was left
+out, rather than a request that fails. The transcript keeps the image either
+way, so `/model` to one that can see it and ask again.
+
+Over SSH the clipboard you copied into is on your own machine, so `ctrl+v`
+says so; copy the file over and drag or paste its path instead.
+
 #### Keybindings
 
 Any key can be rebound in `~/.hx/keybindings.json`, keyed by the action ids in
@@ -877,6 +918,10 @@ and is unchanged; anchors are a second shape, not a replacement. Turn the whole
 thing off with `"tools": {"hashline": false}` and reads go back to plain
 `cat -n`.
 
+**Images.** `Read` on a PNG, JPEG, GIF, WebP, BMP or TIFF - or on a file with
+no extension whose bytes are one - returns the image itself for the model to
+look at, normalised the way a pasted one is (see [Images](#images)).
+
 **Symbols** answers structural questions with a parse tree rather than a
 regex — three modes, `outline` for one file's shape, `definition` for where a
 name is defined, `references` for where it is used:

{hx_cli-0.2.4 → hx_cli-0.2.5}/README.md

@@ -257,6 +257,7 @@ available through OpenRouter.
 ```sh
 hx                          # interactive TUI in the current directory
 hx -p "explain this repo"   # headless: streams to stdout, tool activity to stderr
+hx -p "why?" --image s.png  # attach an image to a headless prompt; repeatable
 hx resume                   # resume the last session here
 hx resume <session-id>      # resume a specific one
 hx prompt                   # print the system prompt this directory would use
@@ -336,6 +337,7 @@ be rebound (see [Keybindings](#keybindings)).
 | `pgdn` | scroll the transcript down (fullscreen; otherwise your terminal scrolls) |
 | `ctrl+home` | jump to the start: the viewport in fullscreen, the first message otherwise |
 | `ctrl+end` | jump back to the newest output |
+| `ctrl+v` | attach the image on the clipboard (see [Images](#images)) |
 | `@path` | complete a file path |
 | `!command` | run a shell command directly, no model turn |
 
@@ -367,6 +369,44 @@ text](#selecting-and-copying-text) for the terminal's own selection.
 HX does not emit OSC 133 prompt markers yet, so shell-integration features that
 jump between prompts will not see HX's messages.
 
+#### Images
+
+Give the model a picture three ways, and each lands in the prompt as a token
+such as `[Image #1]`:
+
+- **`ctrl+v`** attaches whatever image is on the clipboard: a screenshot copied
+  with `cmd+ctrl+shift+4`, an image copied in a browser, or an image file
+  copied in Finder or a file manager. Terminals whose own paste sends nothing
+  when the clipboard holds a picture are caught too - an empty paste is read as
+  a request for the image.
+- **Drag an image file** into the terminal. The terminal pastes its path, and a
+  paste that is nothing but paths to image files attaches them instead of
+  inserting the text. Quoted, backslash-escaped and `file://` paths all work.
+- **Mention it.** `look at @docs/mockup.png` sends the path as text, and the
+  model opens it with `Read`, which returns images as images.
+
+The token is the attachment: move it and the text refers to the picture in a
+different place, delete it (one `backspace` takes the whole token) and the
+image is not sent. Sent messages list their images underneath, with size and
+weight. Numbers run for the whole session, so a message recalled from history
+or restored by a rewind still carries its pictures.
+
+PNG, JPEG, GIF, WebP, BMP and TIFF are accepted. An image within every route's
+limits goes byte for byte; a larger one is scaled to 2000 px on its long side
+and re-encoded to stay under 5 MB, which is what a retina screenshot usually
+needs. Images an MCP tool returns - a browser screenshot, say - are handled the
+same way rather than dropped.
+
+Whether a model can see images comes from the catalogue: OpenRouter's input
+modalities, the Codex catalogue, and Devin's model config. The `/model` picker
+marks the ones that can with `images`. A model that cannot
+is warned about when you attach, and is sent a line saying an image was left
+out, rather than a request that fails. The transcript keeps the image either
+way, so `/model` to one that can see it and ask again.
+
+Over SSH the clipboard you copied into is on your own machine, so `ctrl+v`
+says so; copy the file over and drag or paste its path instead.
+
 #### Keybindings
 
 Any key can be rebound in `~/.hx/keybindings.json`, keyed by the action ids in
@@ -838,6 +878,10 @@ and is unchanged; anchors are a second shape, not a replacement. Turn the whole
 thing off with `"tools": {"hashline": false}` and reads go back to plain
 `cat -n`.
 
+**Images.** `Read` on a PNG, JPEG, GIF, WebP, BMP or TIFF - or on a file with
+no extension whose bytes are one - returns the image itself for the model to
+look at, normalised the way a pasted one is (see [Images](#images)).
+
 **Symbols** answers structural questions with a parse tree rather than a
 regex — three modes, `outline` for one file's shape, `definition` for where a
 name is defined, `references` for where it is used:

{hx_cli-0.2.4 → hx_cli-0.2.5}/pyproject.toml

@@ -33,6 +33,7 @@ dependencies = [
   "pygments>=2.17",
   # CommonMark parsing. The renderer is ours; the parser is not worth writing.
   "markdown-it-py>=3.0",
+  "pillow>=10.4",
 ]
 
 [project.optional-dependencies]

{hx_cli-0.2.4 → hx_cli-0.2.5}/src/hx/__init__.py

@@ -1,5 +1,5 @@
 """HX - an agent harness for the terminal."""
 
-__version__ = "0.2.4"
+__version__ = "0.2.5"
 
 __all__ = ["__version__"]

{hx_cli-0.2.4 → hx_cli-0.2.5}/src/hx/cli.py

@@ -54,6 +54,7 @@ Options:
   --system-prompt TEXT      Replace the system prompt (@path reads a file)
   --append-system-prompt TEXT
                             Append to the system prompt; repeatable (@path reads a file)
+  --image PATH              Attach an image to the -p prompt; repeatable
 """
 
 
@@ -69,6 +70,7 @@ class ParsedArgs:
     rest: tuple[str, ...] = ()
     overrides: dict[str, Any] | None = None
     cwd: Path | None = None
+    images: tuple[Path, ...] = ()
 
 
 def main(argv: list[str] | None = None) -> int:
@@ -159,6 +161,13 @@ def parse_args(args: list[str]) -> ParsedArgs:
                 raise UsageError("--append-system-prompt requires a value")
             appends = overrides.setdefault("prompt", {}).setdefault("append", [])
             appends.append(_prompt_value(args[index]))
+        elif arg == "--image":
+            index += 1
+            if index >= len(args):
+                raise UsageError("--image requires a path")
+            # Against where the command was typed, not --cwd: that is where
+            # the shell completed the path.
+            parsed.images = (*parsed.images, Path(args[index]).expanduser().absolute())
         elif arg.startswith("-"):
             raise UsageError(f"unknown option {arg}")
         else:
@@ -175,6 +184,8 @@ def parse_args(args: list[str]) -> ParsedArgs:
         elif parsed.command != "print":
             raise UsageError(f"unknown command {head!r}")
 
+    if parsed.images and parsed.command != "print":
+        raise UsageError("--image goes with -p; in the TUI, paste or drag the image in")
     parsed.overrides = overrides or None
     return parsed
 
@@ -260,6 +271,12 @@ class Runtime:
 
             self.notices.append(f"Model catalogue refresh failed: {describe(exc)}")
             return
+        finally:
+            # The loop resolved its model before the refresh, from the cache
+            # being replaced. Left alone it would gauge against yesterday's
+            # context window and decide image support from a cache that did
+            # not record it - until the user happened to switch models.
+            self.loop.model_info = self.models.get_or_default(self.loop.model)
         for label, error in self.models.subscription_errors():
             self.notices.append(f"Could not list this account's {label} models: {error}")
 
@@ -631,6 +648,13 @@ def run_print_command(parsed: ParsedArgs) -> int:
     """Headless single-prompt run. Streams assistant text to stdout and tool
     activity to stderr, so stdout stays pipeable."""
     from hx.core import events as ev
+    from hx.core.images import ImageError, load_image_file
+
+    try:
+        images = [load_image_file(path) for path in parsed.images]
+    except ImageError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
 
     try:
         runtime = build_runtime(parsed, resume=_resume_target(parsed))
@@ -660,13 +684,26 @@ def run_print_command(parsed: ParsedArgs) -> int:
 
         renderer = asyncio.create_task(render())
         await asyncio.sleep(0)
+        info = runtime.loop.model_info
+        if images and (info is None or not info.supports_images):
+            # Print mode does not refresh the catalogue - a scripted run should
+            # not wait on it - but withholding an image on the word of a stale
+            # cache is worse than the wait.
+            await runtime.refresh_models_if_stale()
+            info = runtime.loop.model_info
         for notice in runtime.notices:
             print(f"[hx] {notice}", file=sys.stderr)
+        if images and (info is None or not info.supports_images):
+            name = info.name if info is not None else runtime.loop.model
+            print(
+                f"[hx] {name} does not accept images; it is told they were attached, not shown them",
+                file=sys.stderr,
+            )
         for status in await runtime.connect_mcp():
             if not status.connected:
                 print(f"[mcp] {status.name} unavailable: {status.error}", file=sys.stderr)
         try:
-            result = await runtime.loop.run(parsed.prompt)
+            result = await runtime.loop.run(parsed.prompt, images)
             await _rename_closed_session(runtime.loop)
         finally:
             await asyncio.sleep(0.05)
@@ -674,7 +711,7 @@ def run_print_command(parsed: ParsedArgs) -> int:
             await renderer
             await runtime.aclose()
 
-        print()
+        print(flush=True)
         usage = runtime.session.usage
         print(
             f"[usage] in={usage.total_input} out={usage.total_output} "

{hx_cli-0.2.4 → hx_cli-0.2.5}/src/hx/core/compaction.py

@@ -16,6 +16,7 @@ from dataclasses import dataclass
 from typing import TYPE_CHECKING, ClassVar
 
 from hx.core.messages import (
+    ImageBlock,
     Message,
     TextBlock,
     ThinkingBlock,
@@ -173,8 +174,10 @@ class Compactor:
 
     def _estimate(self, messages: list[Message]) -> int:
         if self.context is not None:
-            return sum(self.context.estimate_tokens(_message_text(m)) for m in messages)
-        return sum(len(_message_text(m)) // 4 for m in messages)
+            return sum(self.context.estimate_message_tokens(m) for m in messages)
+        from hx.core.context import message_image_tokens
+
+        return sum(len(_message_text(m)) // 4 + message_image_tokens(m) for m in messages)
 
 
 def _is_turn_edge(messages: list[Message], index: int) -> bool:
@@ -205,11 +208,23 @@ def render_transcript(messages: list[Message]) -> str:
             elif isinstance(block, ToolResultBlock):
                 marker = "error" if block.is_error else "result"
                 lines.append(f"[tool {marker}] {_clip(block.content)}")
+                lines.extend(f"[tool {marker}] {_image_line(image)}" for image in block.images)
+            elif isinstance(block, ImageBlock):
+                lines.append(f"[{message.role}] {_image_line(block)}")
             elif isinstance(block, ThinkingBlock):
                 continue
     return "\n".join(lines)
 
 
+def _image_line(image: ImageBlock) -> str:
+    """An image in the summary prompt. The summariser cannot see it, but it can
+    record that there was one - "the layout in Image #2" means nothing after
+    compaction unless the summary says what Image #2 was of."""
+    from hx.core.images import describe
+
+    return f"(attached an image: {describe(image)})"
+
+
 def _mechanical_summary(messages: list[Message]) -> str:
     """Last-resort digest when no model is available to write one."""
     users = [m.text() for m in messages if m.role == "user" and m.text()]

{hx_cli-0.2.4 → hx_cli-0.2.5}/src/hx/core/context.py

@@ -28,7 +28,7 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, ClassVar
 
-from hx.core.messages import Message
+from hx.core.messages import ImageBlock, Message, ToolResultBlock
 
 if TYPE_CHECKING:
     from hx.config import PromptSettings
@@ -139,7 +139,7 @@ class ContextBuilder:
             PromptSection(
                 "history",
                 "",
-                sum(self.estimate_tokens(_message_text(m)) for m in active),
+                sum(self.estimate_message_tokens(m) for m in active),
             ),
         ]
 
@@ -177,8 +177,7 @@ class ContextBuilder:
             self._breakpoint_b = candidate
         else:
             below = sum(
-                self.estimate_tokens(_message_text(m))
-                for m in messages[self._breakpoint_b : candidate]
+                self.estimate_message_tokens(m) for m in messages[self._breakpoint_b : candidate]
             )
             if below >= self.BREAKPOINT_HYSTERESIS_TOKENS:
                 self._breakpoint_b = candidate
@@ -196,6 +195,15 @@ class ContextBuilder:
         """
         return int(len(text) / self.CHARS_PER_TOKEN) + 1 if text else 0
 
+    def estimate_message_tokens(self, message: Message) -> int:
+        """:meth:`estimate_tokens` for a whole message, images included.
+
+        An image is charged by its pixel count, not its base64 length: a
+        screenshot is a megabyte of text to the character estimate and about
+        1,500 tokens to the model.
+        """
+        return self.estimate_tokens(_message_text(message)) + message_image_tokens(message)
+
 
 def sort_tools(tools: list[dict[str, Any]]) -> list[dict[str, Any]]:
     """Canonical tool ordering: builtins first, then ``mcp__*``, each by name.
@@ -208,6 +216,19 @@ def sort_tools(tools: list[dict[str, Any]]) -> list[dict[str, Any]]:
     )
 
 
+def message_image_tokens(message: Message) -> int:
+    """Estimated tokens for every image in a message, tool results' included."""
+    from hx.core.images import estimate_tokens
+
+    total = 0
+    for block in message.content:
+        if isinstance(block, ImageBlock):
+            total += estimate_tokens(block)
+        elif isinstance(block, ToolResultBlock):
+            total += sum(estimate_tokens(image) for image in block.images)
+    return total
+
+
 def _message_text(message: Message) -> str:
     parts: list[str] = []
     for block in message.content: