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

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

@@ -28,6 +28,80 @@ the project follows [semantic versioning](https://semver.org/).
 
 ---
 
+## [0.2.6] - 2026-09-23
+
+### Added
+
+- Sign in to remote MCP servers over OAuth. A server that asks for it -
+  Atlassian's `https://mcp.atlassian.com/v2/mcp`, for one - shows as needing
+  sign-in; `/mcp login <server>` or `hx mcp login <server>` opens the browser
+  and the tools arrive without a restart. Tokens refresh on their own;
+  `/mcp logout <server>` forgets them. `"oauth": {"clientId": ...}` in
+  `mcp.json` covers servers without client registration.
+- MCP servers that change their tool list mid-session have the new list
+  swapped in, whether they announce it in a reply or on their own stream.
+- `hx mcp add NAME --url URL --header "Name: value"` saves headers, such as an
+  API token, with the server.
+- `/mcp reconnect <server>` restarts one server without restarting HX.
+- `/resume` always offers a list to switch to: this directory's sessions
+  first, then every other directory's, each row naming where it lives.
+  Picking one from elsewhere restarts HX in that directory on it, with the
+  same `--mode` and `--model`. The session already open is no longer listed,
+  and the list is no longer cut at 20.
+
+### Fixed
+
+- `/resume` said "No previous sessions in this directory" in a fresh
+  directory, or inside a session resumed from another one, instead of
+  listing anything.
+- `hx resume <id>` ran the session in whatever directory you typed it in,
+  not the one it was recorded in, so its paths and tool calls pointed at the
+  wrong project.
+- `hx mcp add NAME --url URL`, `--user`, and server arguments like `npx -y`
+  were refused as unknown options, so none of them could be run.
+- `hx mcp add` dropped headers from the entry it wrote.
+- A remote MCP server that expires its session is initialized again instead
+  of failing every call until HX restarts.
+- A multi-line shell command no longer breaks the screen. Its approval shows
+  one row per line, the tool call shows the first line and `+N lines`
+  (`ctrl+o` shows the rest), and the approval options and prompt are no longer
+  drawn several times over.
+- `/resume` from inside a resumed session showed the resumed conversation
+  pushed off the top of the screen, leaving only the "Resumed" notice.
+- A session title with a line break in it no longer splits its row in the
+  `/resume` picker.
+- Started in your home directory, the status bar named it `~/.`; it now reads
+  `~`.
+
+---
+
+## [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 +639,9 @@ 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.6...HEAD
+[0.2.6]: https://github.com/aletisunil/hx/compare/v0.2.5...v0.2.6
+[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.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hx-cli
-Version: 0.2.4
+Version: 0.2.6
 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,8 +297,9 @@ 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 resume <session-id>      # resume a specific one, in the directory it was recorded in
 hx prompt                   # print the system prompt this directory would use
 hx trace                    # write the last session here to an HTML page
 hx trace out.html           # the same, to a path you choose
@@ -309,6 +311,8 @@ hx --no-sandbox             # disable OS sandboxing (rules still apply)
 hx --system-prompt @p.md    # replace the system prompt for one run
 hx --append-system-prompt "Always run the tests"   # add to it; repeatable
 hx mcp list|add|remove      # manage MCP servers
+hx mcp login <server>       # sign in to a remote MCP server in the browser
+hx mcp logout <server>      # forget a remote MCP server's sign-in
 hx auth [set|clear]         # manage the OpenRouter key
 hx auth login [provider]    # sign in (openrouter, openai-codex, devin)
 hx auth logout <provider>   # forget a stored credential
@@ -375,6 +379,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 +411,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
@@ -437,14 +480,14 @@ than being silently resolved.
 | `/cost` | tokens, cache savings, spend |
 | `/compact [focus]` | summarise older turns now |
 | `/clear` | fresh session, same directory |
-| `/resume` | reopen a previous session, listed by name |
+| `/resume` | switch to another session - this directory's first, then the rest |
 | `/rewind` | go back to an earlier prompt, restoring the files HX changed |
 | `/title [text]` | show or set this session's name |
 | `/prompt` | the system prompt this session is running with |
 | `/todos` | show the current plan |
 | `/skills` | installed skills |
 | `/agents` | subagent types |
-| `/mcp` | server status |
+| `/mcp [login\|logout\|reconnect <server>]` | server status, and signing in to remote servers |
 | `/hooks` | configured hooks, and any that were refused |
 | `/theme [name]` | `dark`, `light`, `ansi`, or any theme in `~/.hx/themes` |
 | `/queue [steer <n>\|clear]` | messages waiting for the turn to end, and what to do with them |
@@ -660,6 +703,13 @@ if you want a cheaper model for it — and it is counted in `/cost` like any oth
 If the call fails the session is still named, from your first message. `/title
 <text>` renames it.
 
+`/resume` lists every session except the one you are in: this directory's
+first, then other directories', each row naming where it lives. A session from
+this directory is swapped in place. One from elsewhere belongs to that
+directory - its sandbox, permission rules, prompt and tools - so HX restarts
+itself there with `hx resume <id>`, keeping options like `--mode` and
+`--model`.
+
 ### Themes
 
 A theme is a JSON file: a `vars` block of raw colours, and a `colors` block
@@ -877,6 +927,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:
@@ -951,10 +1005,41 @@ construction.
 }
 ```
 
-Or `hx mcp add local python server.py`. Tools arrive namespaced
+Or `hx mcp add local python server.py`, or
+`hx mcp add remote --url https://example.com/mcp`. Tools arrive namespaced
 `mcp__<server>__<tool>` in a deterministic order. Servers connect concurrently
 with a per-server timeout; one that is broken or slow logs a warning and is
-dropped rather than taking the session with it.
+dropped rather than taking the session with it. A server that changes its tool
+list mid-session (`notifications/tools/list_changed`) has the new list swapped
+in without a restart.
+
+A remote server that asks for sign-in - Atlassian's, for one - is signed in to
+over OAuth, with nothing to configure:
+
+```json
+{ "mcpServers": { "atlassian": { "url": "https://mcp.atlassian.com/v2/mcp" } } }
+```
+
+It shows as needing sign-in until you run `/mcp login atlassian` in a session
+or `hx mcp login atlassian` in a shell. That opens the browser, and the tools
+arrive as soon as you approve - no restart. HX follows the MCP authorization
+spec: it finds the authorization server from the server's metadata, registers
+itself as a client, signs in with PKCE, and keeps the token in `~/.hx/auth.json`
+(mode 0600), refreshing it before it expires and again if the server rejects
+it. Over SSH, paste the final redirect URL into the prompt instead.
+`/mcp logout atlassian` forgets it.
+
+A server that does not offer client registration needs a client you register
+with it yourself, and anything else about the sign-in can be pinned the same
+way:
+
+```json
+"oauth": { "clientId": "...", "clientSecret": "...", "scope": "read write", "callbackPort": 33418 }
+```
+
+To send a token of your own instead - an API key - give the server an
+`Authorization` header, and OAuth stays out of the way:
+`hx mcp add jira --url https://mcp.atlassian.com/v2/mcp --header "Authorization: Basic <base64 email:token>"`.
 
 **Hooks** are shell commands HX runs at named points in a turn. Four events:
 `PreToolUse`, `PostToolUse`, `UserPromptSubmit` and `Stop`.

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

@@ -257,8 +257,9 @@ 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 resume <session-id>      # resume a specific one, in the directory it was recorded in
 hx prompt                   # print the system prompt this directory would use
 hx trace                    # write the last session here to an HTML page
 hx trace out.html           # the same, to a path you choose
@@ -270,6 +271,8 @@ hx --no-sandbox             # disable OS sandboxing (rules still apply)
 hx --system-prompt @p.md    # replace the system prompt for one run
 hx --append-system-prompt "Always run the tests"   # add to it; repeatable
 hx mcp list|add|remove      # manage MCP servers
+hx mcp login <server>       # sign in to a remote MCP server in the browser
+hx mcp logout <server>      # forget a remote MCP server's sign-in
 hx auth [set|clear]         # manage the OpenRouter key
 hx auth login [provider]    # sign in (openrouter, openai-codex, devin)
 hx auth logout <provider>   # forget a stored credential
@@ -336,6 +339,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 +371,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
@@ -398,14 +440,14 @@ than being silently resolved.
 | `/cost` | tokens, cache savings, spend |
 | `/compact [focus]` | summarise older turns now |
 | `/clear` | fresh session, same directory |
-| `/resume` | reopen a previous session, listed by name |
+| `/resume` | switch to another session - this directory's first, then the rest |
 | `/rewind` | go back to an earlier prompt, restoring the files HX changed |
 | `/title [text]` | show or set this session's name |
 | `/prompt` | the system prompt this session is running with |
 | `/todos` | show the current plan |
 | `/skills` | installed skills |
 | `/agents` | subagent types |
-| `/mcp` | server status |
+| `/mcp [login\|logout\|reconnect <server>]` | server status, and signing in to remote servers |
 | `/hooks` | configured hooks, and any that were refused |
 | `/theme [name]` | `dark`, `light`, `ansi`, or any theme in `~/.hx/themes` |
 | `/queue [steer <n>\|clear]` | messages waiting for the turn to end, and what to do with them |
@@ -621,6 +663,13 @@ if you want a cheaper model for it — and it is counted in `/cost` like any oth
 If the call fails the session is still named, from your first message. `/title
 <text>` renames it.
 
+`/resume` lists every session except the one you are in: this directory's
+first, then other directories', each row naming where it lives. A session from
+this directory is swapped in place. One from elsewhere belongs to that
+directory - its sandbox, permission rules, prompt and tools - so HX restarts
+itself there with `hx resume <id>`, keeping options like `--mode` and
+`--model`.
+
 ### Themes
 
 A theme is a JSON file: a `vars` block of raw colours, and a `colors` block
@@ -838,6 +887,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:
@@ -912,10 +965,41 @@ construction.
 }
 ```
 
-Or `hx mcp add local python server.py`. Tools arrive namespaced
+Or `hx mcp add local python server.py`, or
+`hx mcp add remote --url https://example.com/mcp`. Tools arrive namespaced
 `mcp__<server>__<tool>` in a deterministic order. Servers connect concurrently
 with a per-server timeout; one that is broken or slow logs a warning and is
-dropped rather than taking the session with it.
+dropped rather than taking the session with it. A server that changes its tool
+list mid-session (`notifications/tools/list_changed`) has the new list swapped
+in without a restart.
+
+A remote server that asks for sign-in - Atlassian's, for one - is signed in to
+over OAuth, with nothing to configure:
+
+```json
+{ "mcpServers": { "atlassian": { "url": "https://mcp.atlassian.com/v2/mcp" } } }
+```
+
+It shows as needing sign-in until you run `/mcp login atlassian` in a session
+or `hx mcp login atlassian` in a shell. That opens the browser, and the tools
+arrive as soon as you approve - no restart. HX follows the MCP authorization
+spec: it finds the authorization server from the server's metadata, registers
+itself as a client, signs in with PKCE, and keeps the token in `~/.hx/auth.json`
+(mode 0600), refreshing it before it expires and again if the server rejects
+it. Over SSH, paste the final redirect URL into the prompt instead.
+`/mcp logout atlassian` forgets it.
+
+A server that does not offer client registration needs a client you register
+with it yourself, and anything else about the sign-in can be pinned the same
+way:
+
+```json
+"oauth": { "clientId": "...", "clientSecret": "...", "scope": "read write", "callbackPort": 33418 }
+```
+
+To send a token of your own instead - an API key - give the server an
+`Authorization` header, and OAuth stays out of the way:
+`hx mcp add jira --url https://mcp.atlassian.com/v2/mcp --header "Authorization: Basic <base64 email:token>"`.
 
 **Hooks** are shell commands HX runs at named points in a turn. Four events:
 `PreToolUse`, `PostToolUse`, `UserPromptSubmit` and `Stop`.

{hx_cli-0.2.4 → hx_cli-0.2.6}/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.6}/src/hx/__init__.py

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