hx-cli 0.1.0__tar.gz → 0.1.2__tar.gz

{hx_cli-0.1.0 → hx_cli-0.1.2}/.gitignore

@@ -12,3 +12,5 @@ build/
 htmlcov/
 .DS_Store
 .hx/sessions/
+.hx/settings.json
+snapshot_report.html

{hx_cli-0.1.0 → hx_cli-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hx-cli
-Version: 0.1.0
+Version: 0.1.2
 Summary: HX - a terminal coding agent
 Project-URL: Homepage, https://github.com/aletisunil/hx
 Project-URL: Issues, https://github.com/aletisunil/hx/issues
@@ -22,9 +22,11 @@ Provides-Extra: dev
 Requires-Dist: mypy>=1.11; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
 Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest-textual-snapshot>=1.0; extra == 'dev'
 Requires-Dist: pytest>=8.2; extra == 'dev'
 Requires-Dist: ruff>=0.6; extra == 'dev'
 Requires-Dist: textual-dev>=1.5; extra == 'dev'
+Requires-Dist: types-pygments; extra == 'dev'
 Requires-Dist: types-pyyaml; extra == 'dev'
 Description-Content-Type: text/markdown
 
@@ -117,23 +119,72 @@ it pipes cleanly.
 
 ### Keys
 
+Every key below is defined once, in `src/hx/keys.py`. `/help`, the hints line
+under the prompt and this table all read from that registry, and any of them can
+be rebound (see [Keybindings](#keybindings)).
+
 | Key | Does |
 |---|---|
 | `enter` | send |
-| `ctrl+j` | newline |
+| `ctrl+j` | newline (also `shift+enter`) |
 | `esc` | interrupt the current turn |
-| `ctrl+c` | cancel the current turn |
+| `ctrl+c` | clear the prompt; twice on an empty prompt exits |
+| `ctrl+d` | exit, when the prompt is empty |
+| `ctrl+z` | suspend to the background |
 | `shift+tab` | cycle permission mode |
 | `ctrl+p` | command palette |
-| `ctrl+r` | expand the last tool output |
+| `ctrl+l` | model picker |
+| `ctrl+o` | expand tool output (also `ctrl+r`) |
 | `ctrl+t` | toggle the todo sidebar |
-| `ctrl+d` | quit |
+| `ctrl+x` | copy the selected message to the clipboard |
+| `ctrl+up` | previous message |
+| `ctrl+down` | next message |
+| `pgup` | scroll the transcript up |
+| `pgdn` | scroll the transcript down |
+| `ctrl+home` | jump to the start of the transcript |
+| `ctrl+end` | jump back to the newest output |
 | `@path` | complete a file path |
 | `!command` | run a shell command directly, no model turn |
 
 `!` still goes through the permission engine and the sandbox — it skips the
 model, not the safety layers.
 
+The prompt is a readline-style editor: `ctrl+a`/`ctrl+e` for line start and end,
+`ctrl+b`/`ctrl+f` by character, `alt+b`/`alt+f` by word, `ctrl+w` and `alt+d` to
+kill a word, `ctrl+u` and `ctrl+k` to kill to the start or end of a line, then
+`ctrl+y` to yank it back and `alt+y` to walk further down the kill ring.
+`ctrl+z` undoes, `ctrl+shift+z` redoes.
+
+Typing `/` or `@` opens a completion list above the prompt; `tab` cycles it,
+`enter` accepts, `esc` dismisses.
+
+#### Copying
+
+`ctrl+x` copies the message the cursor is on, and `/copy` copies the last reply.
+HX writes through the platform's own clipboard tool first (`pbcopy`, `wl-copy`,
+`xclip`, `xsel`) and falls back to OSC 52, which is also always sent over SSH so
+the text lands on the machine you are actually sitting at.
+
+Because `ctrl+c` clears the prompt, drag-selecting in the transcript is your
+terminal's own selection rather than the TUI's — use your terminal's copy key
+for that. HX does not emit OSC 133 prompt markers yet, so shell-integration
+features that jump between prompts will not see HX's messages.
+
+#### Keybindings
+
+Any key can be rebound in `~/.hx/keybindings.json`, keyed by the action ids in
+`src/hx/keys.py`:
+
+```json
+{
+  "app.tools.expand": "ctrl+r",
+  "app.message.copy": ["ctrl+x", "alt+c"]
+}
+```
+
+Conflicts and unknown action names are reported as a notice at startup rather
+than being silently resolved.
+
 ### Commands
 
 | Command | Does |
@@ -152,10 +203,11 @@ model, not the safety layers.
 | `/skills` | installed skills |
 | `/agents` | subagent types |
 | `/mcp` | server status |
-| `/theme [name]` | `dark`, `light`, `ansi` |
+| `/theme [name]` | `dark`, `light`, `ansi`, or any theme in `~/.hx/themes` |
+| `/copy` | copy the last reply to the clipboard |
 | `/init` | generate an `HX.md` for the project |
 | `/help` | list commands and keys |
-| `/quit` | exit |
+| `/quit` | exit (also `/exit`, `/q`) |
 
 ### The status bar
 
@@ -179,7 +231,8 @@ rule without discarding yours. Everything else is replaced.
 
 ```jsonc
 {
-  "theme": "dark",                    // dark | light | ansi
+  "theme": "dark",                    // dark | light | ansi, or a file in ~/.hx/themes
+  "quiet_startup": false,             // skip the startup header
   "telemetry": false,
 
   "models": {
@@ -214,8 +267,31 @@ rule without discarding yours. Everything else is replaced.
 ```
 
 Environment overrides: `HX_MODEL`, `HX_SUBAGENT_MODEL`, `HX_MAX_TOKENS`,
-`HX_PERMISSION_MODE`, `HX_SANDBOX`, `HX_COMPACT_AT`, `HX_THEME`. Also
-`HX_HOME` to relocate user state.
+`HX_PERMISSION_MODE`, `HX_SANDBOX`, `HX_COMPACT_AT`, `HX_THEME`,
+`HX_QUIET_STARTUP`. Also `HX_HOME` to relocate user state.
+
+### Themes
+
+A theme is a JSON file: a `vars` block of raw colours, and a `colors` block
+mapping semantic roles onto them. Drop one in `~/.hx/themes/mine.json` and
+`/theme mine` picks it up — no restart, no code change.
+
+```jsonc
+{
+  "name": "mine",
+  "dark": true,
+  "vars": { "green": "#b5bd68", "gray": "#808080" },
+  "colors": {
+    "background": "#18181e",
+    "success": "green",           // a vars key, or a literal
+    "muted": "gray"
+    // ...every role; a missing one is an error, not a silent black
+  }
+}
+```
+
+The role names are pi's, so [pi](https://github.com/earendil-works/pi) theme
+files load here unchanged. `src/hx/tui/themes/dark.json` is the reference.
 
 ### Where things live
 
@@ -224,6 +300,8 @@ Environment overrides: `HX_MODEL`, `HX_SUBAGENT_MODEL`, `HX_MAX_TOKENS`,
 | `~/.hx/settings.json` | your settings |
 | `~/.hx/auth.json` | API key, mode 0600 |
 | `~/.hx/models.json` | cached model catalogue, refreshed daily |
+| `~/.hx/themes/` | your themes, one JSON file each |
+| `~/.hx/keybindings.json` | your key overrides |
 | `~/.hx/sessions/` | transcripts, spilled tool output, subagent sessions |
 | `~/.hx/skills/`, `~/.hx/agents/` | your skills and agents |
 | `./.hx/settings.json` | project settings, checked in if you like |
@@ -364,6 +442,13 @@ OPENROUTER_API_KEY=... uv run pytest -m live
 Tests marked `sandbox` exercise the real OS sandbox and are skipped where no
 backend exists.
 
+The TUI has SVG layout snapshots. Read the diff before accepting a change to
+them - they exist to catch a frame that quietly lost a row:
+
+```sh
+uv run pytest tests/tui/test_snapshots.py --snapshot-update
+```
+
 ### Layout
 
 ```
@@ -374,7 +459,9 @@ src/hx/
   tools/        Bash, Read, Write, Edit, Glob, Grep, TodoWrite, Task, output capping
   permissions/  rule engine, shell decomposition, Seatbelt/bubblewrap
   skills/ agents/ mcp/
-  tui/          Textual app, commands, theme, per-tool renderers, widgets
+  keys.py       keybinding registry: ids, defaults, descriptions, user overrides
+  tui/          Textual app, commands, per-tool renderers, widgets
+    themes/     the shipped palettes, as JSON
 ```
 
 The core is headless and emits events; the TUI and print mode are both just
@@ -399,8 +486,8 @@ One-time setup:
 Each release:
 
 ```sh
-# bump version in pyproject.toml, commit
-git tag v0.1.0 && git push origin main --tags
+# bump __version__ in src/hx/__init__.py, commit
+git tag v$(uv run hx --version | cut -d' ' -f2) && git push origin main --tags
 ```
 
 The `publish` job runs only on `refs/tags/v*` and only after lint, the test

{hx_cli-0.1.0 → hx_cli-0.1.2}/README.md

@@ -87,23 +87,72 @@ it pipes cleanly.
 
 ### Keys
 
+Every key below is defined once, in `src/hx/keys.py`. `/help`, the hints line
+under the prompt and this table all read from that registry, and any of them can
+be rebound (see [Keybindings](#keybindings)).
+
 | Key | Does |
 |---|---|
 | `enter` | send |
-| `ctrl+j` | newline |
+| `ctrl+j` | newline (also `shift+enter`) |
 | `esc` | interrupt the current turn |
-| `ctrl+c` | cancel the current turn |
+| `ctrl+c` | clear the prompt; twice on an empty prompt exits |
+| `ctrl+d` | exit, when the prompt is empty |
+| `ctrl+z` | suspend to the background |
 | `shift+tab` | cycle permission mode |
 | `ctrl+p` | command palette |
-| `ctrl+r` | expand the last tool output |
+| `ctrl+l` | model picker |
+| `ctrl+o` | expand tool output (also `ctrl+r`) |
 | `ctrl+t` | toggle the todo sidebar |
-| `ctrl+d` | quit |
+| `ctrl+x` | copy the selected message to the clipboard |
+| `ctrl+up` | previous message |
+| `ctrl+down` | next message |
+| `pgup` | scroll the transcript up |
+| `pgdn` | scroll the transcript down |
+| `ctrl+home` | jump to the start of the transcript |
+| `ctrl+end` | jump back to the newest output |
 | `@path` | complete a file path |
 | `!command` | run a shell command directly, no model turn |
 
 `!` still goes through the permission engine and the sandbox — it skips the
 model, not the safety layers.
 
+The prompt is a readline-style editor: `ctrl+a`/`ctrl+e` for line start and end,
+`ctrl+b`/`ctrl+f` by character, `alt+b`/`alt+f` by word, `ctrl+w` and `alt+d` to
+kill a word, `ctrl+u` and `ctrl+k` to kill to the start or end of a line, then
+`ctrl+y` to yank it back and `alt+y` to walk further down the kill ring.
+`ctrl+z` undoes, `ctrl+shift+z` redoes.
+
+Typing `/` or `@` opens a completion list above the prompt; `tab` cycles it,
+`enter` accepts, `esc` dismisses.
+
+#### Copying
+
+`ctrl+x` copies the message the cursor is on, and `/copy` copies the last reply.
+HX writes through the platform's own clipboard tool first (`pbcopy`, `wl-copy`,
+`xclip`, `xsel`) and falls back to OSC 52, which is also always sent over SSH so
+the text lands on the machine you are actually sitting at.
+
+Because `ctrl+c` clears the prompt, drag-selecting in the transcript is your
+terminal's own selection rather than the TUI's — use your terminal's copy key
+for that. HX does not emit OSC 133 prompt markers yet, so shell-integration
+features that jump between prompts will not see HX's messages.
+
+#### Keybindings
+
+Any key can be rebound in `~/.hx/keybindings.json`, keyed by the action ids in
+`src/hx/keys.py`:
+
+```json
+{
+  "app.tools.expand": "ctrl+r",
+  "app.message.copy": ["ctrl+x", "alt+c"]
+}
+```
+
+Conflicts and unknown action names are reported as a notice at startup rather
+than being silently resolved.
+
 ### Commands
 
 | Command | Does |
@@ -122,10 +171,11 @@ model, not the safety layers.
 | `/skills` | installed skills |
 | `/agents` | subagent types |
 | `/mcp` | server status |
-| `/theme [name]` | `dark`, `light`, `ansi` |
+| `/theme [name]` | `dark`, `light`, `ansi`, or any theme in `~/.hx/themes` |
+| `/copy` | copy the last reply to the clipboard |
 | `/init` | generate an `HX.md` for the project |
 | `/help` | list commands and keys |
-| `/quit` | exit |
+| `/quit` | exit (also `/exit`, `/q`) |
 
 ### The status bar
 
@@ -149,7 +199,8 @@ rule without discarding yours. Everything else is replaced.
 
 ```jsonc
 {
-  "theme": "dark",                    // dark | light | ansi
+  "theme": "dark",                    // dark | light | ansi, or a file in ~/.hx/themes
+  "quiet_startup": false,             // skip the startup header
   "telemetry": false,
 
   "models": {
@@ -184,8 +235,31 @@ rule without discarding yours. Everything else is replaced.
 ```
 
 Environment overrides: `HX_MODEL`, `HX_SUBAGENT_MODEL`, `HX_MAX_TOKENS`,
-`HX_PERMISSION_MODE`, `HX_SANDBOX`, `HX_COMPACT_AT`, `HX_THEME`. Also
-`HX_HOME` to relocate user state.
+`HX_PERMISSION_MODE`, `HX_SANDBOX`, `HX_COMPACT_AT`, `HX_THEME`,
+`HX_QUIET_STARTUP`. Also `HX_HOME` to relocate user state.
+
+### Themes
+
+A theme is a JSON file: a `vars` block of raw colours, and a `colors` block
+mapping semantic roles onto them. Drop one in `~/.hx/themes/mine.json` and
+`/theme mine` picks it up — no restart, no code change.
+
+```jsonc
+{
+  "name": "mine",
+  "dark": true,
+  "vars": { "green": "#b5bd68", "gray": "#808080" },
+  "colors": {
+    "background": "#18181e",
+    "success": "green",           // a vars key, or a literal
+    "muted": "gray"
+    // ...every role; a missing one is an error, not a silent black
+  }
+}
+```
+
+The role names are pi's, so [pi](https://github.com/earendil-works/pi) theme
+files load here unchanged. `src/hx/tui/themes/dark.json` is the reference.
 
 ### Where things live
 
@@ -194,6 +268,8 @@ Environment overrides: `HX_MODEL`, `HX_SUBAGENT_MODEL`, `HX_MAX_TOKENS`,
 | `~/.hx/settings.json` | your settings |
 | `~/.hx/auth.json` | API key, mode 0600 |
 | `~/.hx/models.json` | cached model catalogue, refreshed daily |
+| `~/.hx/themes/` | your themes, one JSON file each |
+| `~/.hx/keybindings.json` | your key overrides |
 | `~/.hx/sessions/` | transcripts, spilled tool output, subagent sessions |
 | `~/.hx/skills/`, `~/.hx/agents/` | your skills and agents |
 | `./.hx/settings.json` | project settings, checked in if you like |
@@ -334,6 +410,13 @@ OPENROUTER_API_KEY=... uv run pytest -m live
 Tests marked `sandbox` exercise the real OS sandbox and are skipped where no
 backend exists.
 
+The TUI has SVG layout snapshots. Read the diff before accepting a change to
+them - they exist to catch a frame that quietly lost a row:
+
+```sh
+uv run pytest tests/tui/test_snapshots.py --snapshot-update
+```
+
 ### Layout
 
 ```
@@ -344,7 +427,9 @@ src/hx/
   tools/        Bash, Read, Write, Edit, Glob, Grep, TodoWrite, Task, output capping
   permissions/  rule engine, shell decomposition, Seatbelt/bubblewrap
   skills/ agents/ mcp/
-  tui/          Textual app, commands, theme, per-tool renderers, widgets
+  keys.py       keybinding registry: ids, defaults, descriptions, user overrides
+  tui/          Textual app, commands, per-tool renderers, widgets
+    themes/     the shipped palettes, as JSON
 ```
 
 The core is headless and emits events; the TUI and print mode are both just
@@ -369,8 +454,8 @@ One-time setup:
 Each release:
 
 ```sh
-# bump version in pyproject.toml, commit
-git tag v0.1.0 && git push origin main --tags
+# bump __version__ in src/hx/__init__.py, commit
+git tag v$(uv run hx --version | cut -d' ' -f2) && git push origin main --tags
 ```
 
 The `publish` job runs only on `refs/tags/v*` and only after lint, the test

{hx_cli-0.1.0 → hx_cli-0.1.2}/pyproject.toml

@@ -35,6 +35,8 @@ dev = [
   "mypy>=1.11",
   "textual-dev>=1.5",
   "types-PyYAML",
+  "types-Pygments",
+  "pytest-textual-snapshot>=1.0",
 ]
 
 [project.scripts]
@@ -63,7 +65,8 @@ ignore = ["E501"]
 
 [tool.ruff.lint.per-file-ignores]
 # Blocking filesystem calls are the point in a test assertion, not a hazard.
-"tests/*" = ["B011", "ASYNC240"]
+# RUF001: the TUI's glyphs are deliberate, and a test has to spell them exactly.
+"tests/*" = ["B011", "ASYNC240", "RUF001"]
 
 [tool.mypy]
 python_version = "3.11"

{hx_cli-0.1.0 → hx_cli-0.1.2}/src/hx/__init__.py

@@ -1,5 +1,5 @@
 """HX - a terminal coding agent."""
 
-__version__ = "0.1.0"
+__version__ = "0.1.2"
 
 __all__ = ["__version__"]

{hx_cli-0.1.0 → hx_cli-0.1.2}/src/hx/cli.py

@@ -17,7 +17,7 @@ import contextlib
 import getpass
 import subprocess
 import sys
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
 
@@ -156,6 +156,8 @@ class Runtime:
     agents: Any = None
     mcp: Any = None
     tools: Any = None
+    notices: list[str] = field(default_factory=list)
+    """Startup messages for the user - shown once, in the transcript."""
 
     @property
     def sandbox_active(self) -> bool:
@@ -220,7 +222,7 @@ def build_runtime(parsed: ParsedArgs, *, resume: str | None = None) -> Runtime:
     from hx.mcp.manager import MCPManager
     from hx.mcp.manager import load_configs as load_mcp_configs
     from hx.paths import ensure_user_dirs, session_outputs_dir
-    from hx.permissions.engine import PermissionEngine, load_rules
+    from hx.permissions.engine import PermissionEngine, load_rules, migrate_legacy_rules
     from hx.permissions.sandbox import Sandbox, default_policy
     from hx.providers.models import ModelRegistry
     from hx.providers.openrouter import OpenRouterProvider, load_api_key
@@ -260,12 +262,13 @@ def build_runtime(parsed: ParsedArgs, *, resume: str | None = None) -> Runtime:
     injections.register("todos", todo_injector(todos))
     injections.register("stale_files", _stale_files_injector(tracker, Injection))
 
+    # Rules come from the settings files only, read once here: `settings`
+    # already merges those same files, and loading both would list and match
+    # every rule twice.
+    notices = migrate_legacy_rules(settings.cwd)
     permissions = PermissionEngine(
         mode=settings.permissions.mode,
-        rules=[
-            *load_rules(settings.cwd),
-            *_rules_from_settings(settings.permissions),
-        ],
+        rules=load_rules(settings.cwd),
         cwd=settings.cwd,
     )
 
@@ -330,6 +333,7 @@ def build_runtime(parsed: ParsedArgs, *, resume: str | None = None) -> Runtime:
         agents=agents,
         mcp=MCPManager(load_mcp_configs(settings.cwd)),
         tools=tools,
+        notices=notices,
     )
 
 
@@ -358,20 +362,6 @@ def _stale_files_injector(tracker: Any, injection_cls: Any) -> Any:
     return inject
 
 
-def _rules_from_settings(permissions: Any) -> list[Any]:
-    """Rules passed on the command line or via env, layered on top of the files."""
-    from hx.permissions.engine import Decision, parse_rule
-
-    rules: list[Any] = []
-    for texts, decision in (
-        (permissions.deny, Decision.DENY),
-        (permissions.ask, Decision.ASK),
-        (permissions.allow, Decision.ALLOW),
-    ):
-        rules.extend(parse_rule(str(text), "settings", decision) for text in texts)
-    return rules
-
-
 def prompt_for_api_key() -> bool:
     """First-run onboarding. Returns True once a key has been saved.
 
@@ -431,6 +421,7 @@ def run_tui_command(parsed: ParsedArgs) -> int:
                 skills=runtime.skills,
                 agents=runtime.agents,
                 mcp=runtime.mcp,
+                notices=runtime.notices,
             )
         finally:
             runtime.bus.close()
@@ -469,6 +460,8 @@ def run_print_command(parsed: ParsedArgs) -> int:
 
         renderer = asyncio.create_task(render())
         await asyncio.sleep(0)
+        for notice in runtime.notices:
+            print(f"[hx] {notice}", 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)

{hx_cli-0.1.0 → hx_cli-0.1.2}/src/hx/config.py

@@ -87,6 +87,8 @@ class Settings:
     context: ContextSettings = field(default_factory=ContextSettings)
     bash: BashSettings = field(default_factory=BashSettings)
     theme: str = "dark"
+    quiet_startup: bool = False
+    """Skip the startup header. For anyone who has read it already."""
     telemetry: bool = False
 
 
@@ -177,6 +179,7 @@ def _build_settings(data: dict[str, Any], cwd: Path) -> Settings:
             shell=bash.get("shell"),
         ),
         theme=data.get("theme", "dark"),
+        quiet_startup=bool(data.get("quietStartup", data.get("quiet_startup", False))),
         telemetry=bool(data.get("telemetry", False)),
     )
 
@@ -241,6 +244,7 @@ _ENV_MAP: dict[str, tuple[str, ...]] = {
     "HX_SANDBOX": ("permissions", "sandbox"),
     "HX_COMPACT_AT": ("context", "compact_at"),
     "HX_THEME": ("theme",),
+    "HX_QUIET_STARTUP": ("quietStartup",),
 }
 
 

{hx_cli-0.1.0 → hx_cli-0.1.2}/src/hx/core/loop.py

@@ -397,15 +397,9 @@ class AgentLoop:
             detail=_permission_detail(call),
             origin=self.origin,
         )
-        self.bus.publish(
-            PermissionRequested(
-                request_id=call.id,
-                tool_name=call.name,
-                description=request.description,
-                detail=request.detail,
-            )
+        allowed, reason = await self.permissions.request(
+            request, on_ask=lambda: self._announce_ask(call.id, request)
         )
-        allowed, reason = await self.permissions.request(request)
         if allowed:
             return None
         return ToolResultBlock(
@@ -414,6 +408,21 @@ class AgentLoop:
             is_error=True,
         )
 
+    def _announce_ask(self, call_id: str, request: Any) -> None:
+        """Announce only the calls that actually stop for approval.
+
+        Publishing on every check made the headless renderer print a permission
+        line for calls that were auto-allowed and never asked about.
+        """
+        self.bus.publish(
+            PermissionRequested(
+                request_id=call_id,
+                tool_name=request.tool_name,
+                description=request.description,
+                detail=request.detail,
+            )
+        )
+
     def _emit_progress(self, tool_use_id: str, chunk: str) -> None:
         from hx.core.events import ToolCallProgress