hexcli 2.8.0__tar.gz → 2.8.1__tar.gz

{hexcli-2.8.0 → hexcli-2.8.1}/.gitignore

@@ -53,3 +53,6 @@ docs/backend_study/data_npu_ab/
 docs/backend_study/_pre_restart/
 tools/backend_bench/.tok_*.txt
 tools/backend_bench/.battery_probe.ps1
+
+# python -m build output
+dist/

{hexcli-2.8.0 → hexcli-2.8.1}/CHANGELOG.md

@@ -6,6 +6,53 @@ the Hexagon NPU, not single-run anecdotes.
 
 ## Unreleased
 
+## 2.8.1 — 2026-09-12
+
+A patch release: nothing model-facing and nothing the launcher hands the
+server changed. Gate: CI green on main; smoke 10/10 on a fresh
+server.
+
+- Installer repairs a Windows Terminal profile whose icon path 2.8.0
+  invalidated. The icon moved into the package (`hexcli/assets/`) that
+  release, but an existing "Hex CLI" profile kept pointing at the old
+  `assets/hexcli.png`; Terminal silently falls back to its own logo on a
+  missing file. `install.ps1` now rewrites a stale `hexcli.png` icon path
+  in a user's own profile with a targeted text edit, leaving the rest of
+  the profile untouched, and the fragment it writes already uses the
+  package path.
+
+- Releases carry the wheel and the source distribution and go to PyPI
+  (`pip install hexcli`): `.github/workflows/publish.yml` runs when a
+  release is published, builds both, attaches them and publishes through
+  PyPI trusted publishing. 2.8.0's files were attached by hand.
+- README rewritten shorter: the PyPI route sits in Install next to the
+  installer, the sample transcript the clips made redundant is gone, the
+  configuration table keeps the keys people change, memory and logs are a
+  short section under Usage, and the clips use absolute links so they
+  render on PyPI, in a two-by-two grid; the edit clip plays faster
+  (23 s, was 32 s). Version and CI badges at the top.
+- Paper and CLAUDE.md current through 2.8.0: the timeline row and the
+  closing state paragraph record the package and the classifier finding,
+  and the milestones table breaks across pages instead of running off
+  one (it had been overflowing page 9).
+- Paper numbers re-audited against the code and the latest results: the
+  window figure shows the 3,696-token server budget and the ~810-token
+  history it leaves instead of the disproven 2,600-token cliff; the
+  headline is 32/44 at pass^5 (LATEST.md) and 35/48 multi-turn; the
+  "9 s per new conversation" figure is retracted as the backend study
+  found; a paragraph carries that study's numbers (15.5 tok/s, 0.8 s warm
+  first token, polling-off power). ARCHITECTURE.md gets the same pass
+  (template in prompts.py, 29 suites, 44 cases, a dated note on the
+  pre-Rewind TTFT section) and the README's suite size reads 44.
+- Paper restructured to six pages: the abstract states the v2.8.0 numbers
+  and the thesis; the runtime lever (KV rewind, the context re-read) is
+  its own section between results and negative results; the status
+  section is one paragraph; the milestones table is one line per row; a
+  positioning paragraph names what the report sits next to; three
+  figures that duplicated prose (chip diagram, prompt anatomy, NPU/CPU
+  bars) are gone and their numbers kept in the text. Every figure in the
+  paper is unchanged from the audit above.
+
 ## 2.8.0 — 2026-09-12
 
 A minor release by RELEASING.md's rule (the launcher moved and its

{hexcli-2.8.0 → hexcli-2.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hexcli
-Version: 2.8.0
+Version: 2.8.1
 Summary: Local Hexagon NPU terminal agent for Snapdragon X Elite Windows ARM64
 Project-URL: Homepage, https://github.com/NathanL15/Hex-CLI
 Project-URL: Repository, https://github.com/NathanL15/Hex-CLI
@@ -27,61 +27,37 @@ Description-Content-Type: text/markdown
 
 # Hex CLI
 
+[![PyPI](https://img.shields.io/pypi/v/hexcli)](https://pypi.org/project/hexcli/)
+[![CI](https://github.com/NathanL15/Hex-CLI/actions/workflows/ci.yml/badge.svg)](https://github.com/NathanL15/Hex-CLI/actions/workflows/ci.yml)
+
 Hex CLI is a coding agent for the Windows terminal, similar to aider or
 Claude Code, that runs a local model on the Snapdragon Hexagon NPU. It reads
 and edits files, runs commands, and checks its own work. The model is
 Qwen3-4B, served by [npurun](https://github.com/bpbonker/npurun). After
 setup it works offline.
 
-**Ask something.** The answer streams in, markdown and all, above an input
-box that stays on the last rows.
-
-![A question answered in bullet points](docs/gifs/ask.gif)
-
-**Ask about the machine.** Live state comes from a real command, shown as
-it runs.
-
-![The CPU name read with a PowerShell command](docs/gifs/machine.gif)
-
-**Change code.** Every file change prints a diff; when you ask for the
-tests, they run; `/diff` shows the turn's changes and `/undo` takes them
-back, files included.
-
-![A docstring added, the tests run, then undone](docs/gifs/edit.gif)
-
-**Nothing destructive runs unasked.** Commands are classified before they
-run; a delete asks first.
-
-![A delete command waits for a y/N before running](docs/gifs/safety.gif)
-
-```
-> the median calc in processor.py is wrong for even-length lists, fix it
-
-◆ read_file
-▸ [read] processor.py  (lines 1-40 of 40)
-
-◆ edit_file
-▸ [edit] processor.py  (+2 lines)
-~ processor.py  (+3 −1)
-@@ -12,4 +12,6 @@
--    return sorted(data)[len(data) // 2]
-+    mid = len(data) // 2
-+    if len(data) % 2 == 0:
-+        return (sorted(data)[mid - 1] + sorted(data)[mid]) / 2
-
-◆ run_code
-
-Fixed: even-length lists now average the two middle values. The test file
-prints 3.5 for [1, 2, 5, 6].
-
-──────────────────────────────────────────────────────────────────
-> ask, or / for commands
-──────────────────────────────────────────────────────────────────
-context ◔ 21%   npu 0%   mem 12.5/15.6 GB              ~\proj (main)
-```
-
-Your messages sit on a light band, the input box and status line stay on
-the last rows, and the answer streams in above them.
+<table>
+<tr>
+<td width="50%" valign="top">
+<b>Ask something.</b> The answer streams in, markdown and all, above an input box that stays on the last rows.<br><br>
+<img src="https://raw.githubusercontent.com/NathanL15/Hex-CLI/main/docs/gifs/ask.gif" alt="A question answered in bullet points" width="100%">
+</td>
+<td width="50%" valign="top">
+<b>Ask about the machine.</b> Live state comes from a real command, shown as it runs.<br><br>
+<img src="https://raw.githubusercontent.com/NathanL15/Hex-CLI/main/docs/gifs/machine.gif" alt="The CPU name read with a PowerShell command" width="100%">
+</td>
+</tr>
+<tr>
+<td width="50%" valign="top">
+<b>Change code.</b> Every file change prints a diff; when you ask for the tests, they run; <code>/diff</code> shows the turn's changes and <code>/undo</code> takes them back, files included.<br><br>
+<img src="https://raw.githubusercontent.com/NathanL15/Hex-CLI/main/docs/gifs/edit.gif" alt="A docstring added, the tests run, then undone" width="100%">
+</td>
+<td width="50%" valign="top">
+<b>Nothing destructive runs unasked.</b> Commands are classified before they run; a delete asks first.<br><br>
+<img src="https://raw.githubusercontent.com/NathanL15/Hex-CLI/main/docs/gifs/safety.gif" alt="A delete command waits for a y/N before running" width="100%">
+</td>
+</tr>
+</table>
 
 ## Requirements
 
@@ -93,33 +69,42 @@ Tested on a Snapdragon X Elite. It will not run on x86 machines or on Macs.
 
 ## Install
 
+The installer does everything the machine allows:
+
 ```powershell
 git clone https://github.com/NathanL15/Hex-CLI
 cd Hex-CLI
 .\install.ps1
 ```
 
-The installer checks the machine, installs the package (`pip install .`,
-which gives you the `hex` and `hexcli` commands), downloads npurun, the
-model and the small embedding model that semantic memory uses, and runs
-`--doctor` when it finishes. It skips steps that are already done, so run
-it again after fixing anything it reports. Everything it writes for you
-lives in `~\.shellai`.
-
-It cannot download the QAIRT SDK for you, because Qualcomm does not allow
-redistribution. It prints instructions for that step and picks the SDK up on
-the next run. See [Setup by hand](#setup-by-hand) if you want to do the
-steps yourself.
-
-The Start Menu shortcut opens Hex in Windows Terminal when it is installed,
-through a "Hex CLI" profile the installer registers. It starts in your home
-folder; `/cwd <path>` moves into a project, whose `AGENTS.md` then applies. Text selection, copy
-and paste work there as in any other tab. Without Windows Terminal the
-shortcut uses the classic console, where drag-select is off because Hex
-disables QuickEdit (a click would otherwise freeze output); use the window
-menu's Edit, Mark to copy there. To have `hex` itself open in Windows
-Terminal from any shell, set it as the default terminal in its Settings,
-Startup.
+It checks the machine, installs the package, downloads npurun, the model
+and the small embedding model that memory uses, and runs `--doctor` when it
+finishes. It skips steps that are already done, so run it again after
+fixing anything it reports. Everything it writes for you lives in
+`~\.shellai`.
+
+The one thing it cannot download is the QAIRT SDK, because Qualcomm does
+not allow redistribution. It prints the instructions for that step and
+picks the SDK up on the next run.
+
+Or install from PyPI. The package is the same one the installer uses; you
+install the SDK yourself and the rest downloads itself:
+
+```powershell
+pip install hexcli       # the hex and hexcli commands
+hexcli --update          # downloads npurun
+hex                      # the first run downloads the model, about 2.5 GB
+```
+
+`hexcli --doctor` lists what is still missing and the command that fixes
+each item. Every [release](https://github.com/NathanL15/Hex-CLI/releases)
+also carries the wheel and the source distribution.
+
+The Start Menu shortcut opens Hex in Windows Terminal, through a profile
+the installer registers, starting in your home folder; `/cwd <path>` moves
+into a project. Without Windows Terminal it uses the classic console, where
+drag-select is off because Hex disables QuickEdit (a click would otherwise
+freeze output); use the window menu's Edit, Mark to copy there.
 
 ## Usage
 
@@ -133,14 +118,11 @@ hexcli --doctor                      # check the install
 hexcli --update                      # refresh npurun (and pull the source in a checkout)
 ```
 
-In a checkout without the package installed, `python launcher.py` and
-`python -m hexcli.agent` are the same two commands.
-
 Piped input is added to the request as context, or used as the request if
-there is no argument. Long input is trimmed to fit the context window.
-When stdout is not a terminal the answer is printed alone, with no
-progress text, so `hexcli "..." > answer.txt` and `hexcli "..." | clip`
-work.
+there is no argument. When stdout is not a terminal the answer is printed
+alone, so `hexcli "..." > answer.txt` and `hexcli "..." | clip` work. In a
+checkout without the package installed, `python launcher.py` and
+`python -m hexcli.agent` are the same two commands.
 
 ### Commands
 
@@ -165,10 +147,10 @@ work.
 | `/doctor` | check the install |
 | `Esc` | cancel the running step |
 
-You can add your own commands. Put a `.md` file in `.shellai/commands/` in
-the project, or `~/.shellai/commands/` for all projects, and `/<filename>`
-sends its content as the prompt. `$ARGUMENTS` in the file is replaced with
-whatever follows the command.
+You can add your own. Put a `.md` file in `.shellai/commands/` in the
+project, or `~/.shellai/commands/` for all projects, and `/<filename>`
+sends its content as the prompt, with `$ARGUMENTS` replaced by whatever
+follows the command:
 
 ```powershell
 # .shellai/commands/review.md contains: Review $ARGUMENTS for bugs and style issues.
@@ -188,21 +170,15 @@ whatever follows the command.
 | `Ctrl+V` | paste a block. Nothing is sent until you press Enter |
 | `Shift+Enter` | new line inside the entry |
 | `\` then `Enter` | continue on a new line |
-| `Ctrl+Plus` `Ctrl+Minus` | text size in the classic console |
 
-History is saved in `~/.shellai/input_history`. When stdin is not a
-terminal the agent falls back to plain `input()`, so pipes and CI work.
-
-The input box stays on the last rows of the window, and the conversation
-scrolls up above it. The status line under it
-shows how full the context is, the NPU load (the counter behind Task
-Manager's NPU graph), memory in use, and the working directory and branch.
-Set `status_bar` to `false` for the old inline prompt.
+The status line under the input box shows how full the context is, the
+NPU load, memory in use, and the working directory and branch. Set
+`status_bar` to `false` for a plain inline prompt.
 
 ### Project instructions
 
 If a project has an `AGENTS.md`, the agent reads it every turn. Keep it
-under about 1,200 characters. The model has a 4K token context and your
+under about 1,200 characters: the model has a 4K token context and your
 request has to fit in there too.
 
 ### Tools
@@ -213,9 +189,19 @@ request has to fit in there too.
 for the full signatures.
 
 `edit_file` tries an exact match first, then a whitespace-tolerant match,
-then a close match if there is exactly one. If the match is ambiguous it
-returns an error rather than guessing. `read_file` reads large files in
-pages. Every file change prints a diff and can be reverted with `/undo`.
+then a close match if there is exactly one; an ambiguous match returns an
+error rather than a guess. `read_file` reads large files in pages. Every
+file change prints a diff and can be reverted with `/undo`.
+
+### Memory and logs
+
+Memory is two local stores, one per project and one global, built on
+MiniLM embeddings. When idle, the agent condenses recent turns into short
+notes that later prompts include; `/memory` shows what is stored.
+
+Each session is written to `~/.shellai/chatlog/` as a JSONL file: every
+request, every message sent to the model, every reply with its latency,
+every tool call with its output. Secrets in the config are redacted.
 
 ## Safety
 
@@ -223,18 +209,16 @@ Commands are classified before they run:
 
 | Level | Examples | Behaviour |
 |---|---|---|
-| destructive | `Remove-Item`, `git reset --hard`, `format-*`, `iex` | asks first |
+| destructive | `Remove-Item`, `git reset --hard`, `Format-Volume`, `iex` | asks first |
 | sensitive | ssh/gpg/aws keys, hosts file, registry hives, credential stores, `-EncodedCommand` | asks first, denied when non-interactive |
 | safe | `Get-*`, `ls`, `git status` | runs |
 | caution | anything else | runs |
 
 File writes stay inside the working directory unless you widen the scope
 with `workspace_write_allow`. Reads can go anywhere. Key and credential
-paths are blocked for all file tools.
-
-`fetch_url` is the only tool that touches the network. It asks before every
-fetch, and is refused when non-interactive. Set `network_access` to
-`"deny"` to remove the tool or `"allow"` to skip the prompt.
+paths are blocked for all file tools. `fetch_url` is the only tool that
+touches the network; it asks before every fetch and is refused when
+non-interactive.
 
 Each classified command is appended to `.shellai/audit.log`. Text inside
 files and tool output is treated as data, not instructions. A 4B model does
@@ -244,45 +228,20 @@ doing so.
 ## Configuration
 
 Config is optional. `~\.shellai\shellai.json` and `.shellai/config.json`
-in a project are merged over the defaults, so you only need to write the
-keys you change. `shellai.example.json` lists every key with its default,
-and `/setup` writes the file for you.
+in a project are merged over the defaults, so you only write the keys you
+change. The ones people change:
 
 | Key | Default | Effect |
 |---|---|---|
 | `max_agent_steps` | `15` | tool calls per turn |
-| `live_streaming` | `true` | show the answer as it arrives |
-| `rich_input` | `true` | history, Tab completion, multi-line paste |
-| `side_padding` | `2` | left margin in columns |
-| `status_bar` | `true` | input box and status line at the bottom |
-| `user_highlight` | `true` | light band behind your messages in the transcript |
 | `show_diffs` | `true` | print a diff after each file change |
+| `status_bar` | `true` | input box and status line at the bottom |
 | `workspace_write_scope` | `true` | keep writes inside the working directory |
-| `autopilot_confirm_sensitive` | `true` | ask before touching keys and credentials |
-| `network_access` | `"ask"` | `"deny"` or `"allow"` |
-| `require_verification` | `true` | ask the agent to check its own edits |
-| `prompt_split` | `true` | answer plain questions without the tool loop |
-| `escalation_local_model` | `""` | a larger local model to consult when stuck |
+| `network_access` | `"ask"` | `"deny"` removes `fetch_url`, `"allow"` skips the prompt |
 | `memory_enabled` | `true` | semantic memory |
-| `chat_log_enabled` | `true` | write full session logs |
-| `protocol` | `"v1"` | `"v2"` is experimental |
 
-## Logs and memory
-
-Each session is written to `~/.shellai/chatlog/` as a JSONL file: every
-request, every message sent to the model, every reply with its latency,
-every tool call with its output. Secrets in the config are redacted.
-`/stats` prints the path of the current file.
-
-```powershell
-python tools/chatlog_report.py                  # summary across all sessions
-python tools/chatlog_report.py --last           # replay the most recent session
-python tools/chatlog_report.py --session 1a2b   # replay one session by id prefix
-```
-
-Memory is two local stores, one per project and one global, built on MiniLM
-embeddings. When idle, the agent condenses recent turns into short notes
-that are included in later prompts. `/memory` shows what is stored.
+`shellai.example.json` lists every key with its default, and `/setup`
+writes the file for you.
 
 ## Setup by hand
 
@@ -291,7 +250,7 @@ These are the steps `install.ps1` performs. `--doctor` checks each one.
 **1. The package**
 
 ```powershell
-pip install .        # from the checkout: the hex and hexcli commands, numpy, onnxruntime
+pip install hexcli   # or, from the checkout: pip install .
 ```
 
 `ruff` is optional and enables the `lint_code` tool.
@@ -313,22 +272,26 @@ setx ADSP_LIBRARY_PATH "C:\Qualcomm\AIStack\QAIRT_2.50.0\lib\hexagon-v73\unsigne
 If `ADSP_LIBRARY_PATH` is missing, npurun crashes with
 `STATUS_STACK_BUFFER_OVERRUN`.
 
-**3. npurun and a model**
-
-The NPU server is a fork of npurun, at
-[NathanL15/npurun](https://github.com/NathanL15/npurun) on the
-`hexcli-fork` branch. Each release there has a prebuilt `npurun-arm64.exe`.
-Hex CLI expects one specific build, set by `REQUIRED_NPURUN` in
-`hexcli/launcher.py`. `--doctor` fails on an older build and `--update`
-replaces it (the download goes to `~\.shellai\bin`).
+**3. npurun and the model**
 
-To build from source, use the fork. It has the prompt cache rewind, usage
-reporting, exact `max_tokens`, and request watchdog that Hex CLI relies on.
+The NPU server is a fork of npurun at
+[NathanL15/npurun](https://github.com/NathanL15/npurun), branch
+`hexcli-fork`, with a prebuilt `npurun-arm64.exe` on each release. Hex CLI
+expects one specific build, set by `REQUIRED_NPURUN` in
+`hexcli/launcher.py`; `hexcli --update` downloads it to `~\.shellai\bin`
+and `--doctor` fails on an older one. The fork adds the prompt cache
+rewind, usage reporting, exact `max_tokens` and the request watchdog that
+Hex CLI relies on, so upstream npurun will not do. To build it yourself:
 
 ```powershell
 git clone -b hexcli-fork https://github.com/NathanL15/npurun
 cd npurun
 cmd /c "scripts\dev-shell-local.bat cargo install --path crates\npurun-cli"
+```
+
+The model downloads on the first `hex` run, or by hand:
+
+```powershell
 npurun pull qwen3-4b-instruct-2507      # about 2.5 GB
 ```
 
@@ -357,7 +320,7 @@ curl -L -o ~\.shellai\onnx\tokenizer.json https://huggingface.co/sentence-transf
 
 ## Development
 
-CI runs `ruff` and 25 offline test suites against a mock backend, so no NPU
+CI runs `ruff` and 29 offline test suites against a mock backend, so no NPU
 is needed for those:
 
 ```powershell
@@ -369,14 +332,15 @@ python evals/test_lineedit.py
 
 The live evals need the NPU server. They check what the model actually did,
 by looking at the filesystem and the answer, and run each case several
-times because the model is not deterministic.
+times because the model is not deterministic:
 
 ```powershell
 python evals/cases_smoke.py                        # quick check
-python evals/cases_extended.py --runs 3            # 41 cases
+python evals/cases_extended.py --runs 3            # 44 cases
 python evals/cases_multiturn.py --runs 3 --think-time 15
 python evals/compare.py <before.json> <after.json>
 python evals/gate.py --baseline <base.json> <candidate.json>
+python tools/chatlog_report.py --last             # replay the most recent session
 ```
 
 Restart the NPU server before each suite. After an hour or two of steady

{hexcli-2.8.0 → hexcli-2.8.1}/README.md

@@ -1,60 +1,36 @@
 # Hex CLI
 
+[![PyPI](https://img.shields.io/pypi/v/hexcli)](https://pypi.org/project/hexcli/)
+[![CI](https://github.com/NathanL15/Hex-CLI/actions/workflows/ci.yml/badge.svg)](https://github.com/NathanL15/Hex-CLI/actions/workflows/ci.yml)
+
 Hex CLI is a coding agent for the Windows terminal, similar to aider or
 Claude Code, that runs a local model on the Snapdragon Hexagon NPU. It reads
 and edits files, runs commands, and checks its own work. The model is
 Qwen3-4B, served by [npurun](https://github.com/bpbonker/npurun). After
 setup it works offline.
 
-**Ask something.** The answer streams in, markdown and all, above an input
-box that stays on the last rows.
-
-![A question answered in bullet points](docs/gifs/ask.gif)
-
-**Ask about the machine.** Live state comes from a real command, shown as
-it runs.
-
-![The CPU name read with a PowerShell command](docs/gifs/machine.gif)
-
-**Change code.** Every file change prints a diff; when you ask for the
-tests, they run; `/diff` shows the turn's changes and `/undo` takes them
-back, files included.
-
-![A docstring added, the tests run, then undone](docs/gifs/edit.gif)
-
-**Nothing destructive runs unasked.** Commands are classified before they
-run; a delete asks first.
-
-![A delete command waits for a y/N before running](docs/gifs/safety.gif)
-
-```
-> the median calc in processor.py is wrong for even-length lists, fix it
-
-◆ read_file
-▸ [read] processor.py  (lines 1-40 of 40)
-
-◆ edit_file
-▸ [edit] processor.py  (+2 lines)
-~ processor.py  (+3 −1)
-@@ -12,4 +12,6 @@
--    return sorted(data)[len(data) // 2]
-+    mid = len(data) // 2
-+    if len(data) % 2 == 0:
-+        return (sorted(data)[mid - 1] + sorted(data)[mid]) / 2
-
-◆ run_code
-
-Fixed: even-length lists now average the two middle values. The test file
-prints 3.5 for [1, 2, 5, 6].
-
-──────────────────────────────────────────────────────────────────
-> ask, or / for commands
-──────────────────────────────────────────────────────────────────
-context ◔ 21%   npu 0%   mem 12.5/15.6 GB              ~\proj (main)
-```
-
-Your messages sit on a light band, the input box and status line stay on
-the last rows, and the answer streams in above them.
+<table>
+<tr>
+<td width="50%" valign="top">
+<b>Ask something.</b> The answer streams in, markdown and all, above an input box that stays on the last rows.<br><br>
+<img src="https://raw.githubusercontent.com/NathanL15/Hex-CLI/main/docs/gifs/ask.gif" alt="A question answered in bullet points" width="100%">
+</td>
+<td width="50%" valign="top">
+<b>Ask about the machine.</b> Live state comes from a real command, shown as it runs.<br><br>
+<img src="https://raw.githubusercontent.com/NathanL15/Hex-CLI/main/docs/gifs/machine.gif" alt="The CPU name read with a PowerShell command" width="100%">
+</td>
+</tr>
+<tr>
+<td width="50%" valign="top">
+<b>Change code.</b> Every file change prints a diff; when you ask for the tests, they run; <code>/diff</code> shows the turn's changes and <code>/undo</code> takes them back, files included.<br><br>
+<img src="https://raw.githubusercontent.com/NathanL15/Hex-CLI/main/docs/gifs/edit.gif" alt="A docstring added, the tests run, then undone" width="100%">
+</td>
+<td width="50%" valign="top">
+<b>Nothing destructive runs unasked.</b> Commands are classified before they run; a delete asks first.<br><br>
+<img src="https://raw.githubusercontent.com/NathanL15/Hex-CLI/main/docs/gifs/safety.gif" alt="A delete command waits for a y/N before running" width="100%">
+</td>
+</tr>
+</table>
 
 ## Requirements
 
@@ -66,33 +42,42 @@ Tested on a Snapdragon X Elite. It will not run on x86 machines or on Macs.
 
 ## Install
 
+The installer does everything the machine allows:
+
 ```powershell
 git clone https://github.com/NathanL15/Hex-CLI
 cd Hex-CLI
 .\install.ps1
 ```
 
-The installer checks the machine, installs the package (`pip install .`,
-which gives you the `hex` and `hexcli` commands), downloads npurun, the
-model and the small embedding model that semantic memory uses, and runs
-`--doctor` when it finishes. It skips steps that are already done, so run
-it again after fixing anything it reports. Everything it writes for you
-lives in `~\.shellai`.
-
-It cannot download the QAIRT SDK for you, because Qualcomm does not allow
-redistribution. It prints instructions for that step and picks the SDK up on
-the next run. See [Setup by hand](#setup-by-hand) if you want to do the
-steps yourself.
-
-The Start Menu shortcut opens Hex in Windows Terminal when it is installed,
-through a "Hex CLI" profile the installer registers. It starts in your home
-folder; `/cwd <path>` moves into a project, whose `AGENTS.md` then applies. Text selection, copy
-and paste work there as in any other tab. Without Windows Terminal the
-shortcut uses the classic console, where drag-select is off because Hex
-disables QuickEdit (a click would otherwise freeze output); use the window
-menu's Edit, Mark to copy there. To have `hex` itself open in Windows
-Terminal from any shell, set it as the default terminal in its Settings,
-Startup.
+It checks the machine, installs the package, downloads npurun, the model
+and the small embedding model that memory uses, and runs `--doctor` when it
+finishes. It skips steps that are already done, so run it again after
+fixing anything it reports. Everything it writes for you lives in
+`~\.shellai`.
+
+The one thing it cannot download is the QAIRT SDK, because Qualcomm does
+not allow redistribution. It prints the instructions for that step and
+picks the SDK up on the next run.
+
+Or install from PyPI. The package is the same one the installer uses; you
+install the SDK yourself and the rest downloads itself:
+
+```powershell
+pip install hexcli       # the hex and hexcli commands
+hexcli --update          # downloads npurun
+hex                      # the first run downloads the model, about 2.5 GB
+```
+
+`hexcli --doctor` lists what is still missing and the command that fixes
+each item. Every [release](https://github.com/NathanL15/Hex-CLI/releases)
+also carries the wheel and the source distribution.
+
+The Start Menu shortcut opens Hex in Windows Terminal, through a profile
+the installer registers, starting in your home folder; `/cwd <path>` moves
+into a project. Without Windows Terminal it uses the classic console, where
+drag-select is off because Hex disables QuickEdit (a click would otherwise
+freeze output); use the window menu's Edit, Mark to copy there.
 
 ## Usage
 
@@ -106,14 +91,11 @@ hexcli --doctor                      # check the install
 hexcli --update                      # refresh npurun (and pull the source in a checkout)
 ```
 
-In a checkout without the package installed, `python launcher.py` and
-`python -m hexcli.agent` are the same two commands.
-
 Piped input is added to the request as context, or used as the request if
-there is no argument. Long input is trimmed to fit the context window.
-When stdout is not a terminal the answer is printed alone, with no
-progress text, so `hexcli "..." > answer.txt` and `hexcli "..." | clip`
-work.
+there is no argument. When stdout is not a terminal the answer is printed
+alone, so `hexcli "..." > answer.txt` and `hexcli "..." | clip` work. In a
+checkout without the package installed, `python launcher.py` and
+`python -m hexcli.agent` are the same two commands.
 
 ### Commands
 
@@ -138,10 +120,10 @@ work.
 | `/doctor` | check the install |
 | `Esc` | cancel the running step |
 
-You can add your own commands. Put a `.md` file in `.shellai/commands/` in
-the project, or `~/.shellai/commands/` for all projects, and `/<filename>`
-sends its content as the prompt. `$ARGUMENTS` in the file is replaced with
-whatever follows the command.
+You can add your own. Put a `.md` file in `.shellai/commands/` in the
+project, or `~/.shellai/commands/` for all projects, and `/<filename>`
+sends its content as the prompt, with `$ARGUMENTS` replaced by whatever
+follows the command:
 
 ```powershell
 # .shellai/commands/review.md contains: Review $ARGUMENTS for bugs and style issues.
@@ -161,21 +143,15 @@ whatever follows the command.
 | `Ctrl+V` | paste a block. Nothing is sent until you press Enter |
 | `Shift+Enter` | new line inside the entry |
 | `\` then `Enter` | continue on a new line |
-| `Ctrl+Plus` `Ctrl+Minus` | text size in the classic console |
 
-History is saved in `~/.shellai/input_history`. When stdin is not a
-terminal the agent falls back to plain `input()`, so pipes and CI work.
-
-The input box stays on the last rows of the window, and the conversation
-scrolls up above it. The status line under it
-shows how full the context is, the NPU load (the counter behind Task
-Manager's NPU graph), memory in use, and the working directory and branch.
-Set `status_bar` to `false` for the old inline prompt.
+The status line under the input box shows how full the context is, the
+NPU load, memory in use, and the working directory and branch. Set
+`status_bar` to `false` for a plain inline prompt.
 
 ### Project instructions
 
 If a project has an `AGENTS.md`, the agent reads it every turn. Keep it
-under about 1,200 characters. The model has a 4K token context and your
+under about 1,200 characters: the model has a 4K token context and your
 request has to fit in there too.
 
 ### Tools
@@ -186,9 +162,19 @@ request has to fit in there too.
 for the full signatures.
 
 `edit_file` tries an exact match first, then a whitespace-tolerant match,
-then a close match if there is exactly one. If the match is ambiguous it
-returns an error rather than guessing. `read_file` reads large files in
-pages. Every file change prints a diff and can be reverted with `/undo`.
+then a close match if there is exactly one; an ambiguous match returns an
+error rather than a guess. `read_file` reads large files in pages. Every
+file change prints a diff and can be reverted with `/undo`.
+
+### Memory and logs
+
+Memory is two local stores, one per project and one global, built on
+MiniLM embeddings. When idle, the agent condenses recent turns into short
+notes that later prompts include; `/memory` shows what is stored.
+
+Each session is written to `~/.shellai/chatlog/` as a JSONL file: every
+request, every message sent to the model, every reply with its latency,
+every tool call with its output. Secrets in the config are redacted.
 
 ## Safety
 
@@ -196,18 +182,16 @@ Commands are classified before they run:
 
 | Level | Examples | Behaviour |
 |---|---|---|
-| destructive | `Remove-Item`, `git reset --hard`, `format-*`, `iex` | asks first |
+| destructive | `Remove-Item`, `git reset --hard`, `Format-Volume`, `iex` | asks first |
 | sensitive | ssh/gpg/aws keys, hosts file, registry hives, credential stores, `-EncodedCommand` | asks first, denied when non-interactive |
 | safe | `Get-*`, `ls`, `git status` | runs |
 | caution | anything else | runs |
 
 File writes stay inside the working directory unless you widen the scope
 with `workspace_write_allow`. Reads can go anywhere. Key and credential
-paths are blocked for all file tools.
-
-`fetch_url` is the only tool that touches the network. It asks before every
-fetch, and is refused when non-interactive. Set `network_access` to
-`"deny"` to remove the tool or `"allow"` to skip the prompt.
+paths are blocked for all file tools. `fetch_url` is the only tool that
+touches the network; it asks before every fetch and is refused when
+non-interactive.
 
 Each classified command is appended to `.shellai/audit.log`. Text inside
 files and tool output is treated as data, not instructions. A 4B model does
@@ -217,45 +201,20 @@ doing so.
 ## Configuration
 
 Config is optional. `~\.shellai\shellai.json` and `.shellai/config.json`
-in a project are merged over the defaults, so you only need to write the
-keys you change. `shellai.example.json` lists every key with its default,
-and `/setup` writes the file for you.
+in a project are merged over the defaults, so you only write the keys you
+change. The ones people change:
 
 | Key | Default | Effect |
 |---|---|---|
 | `max_agent_steps` | `15` | tool calls per turn |
-| `live_streaming` | `true` | show the answer as it arrives |
-| `rich_input` | `true` | history, Tab completion, multi-line paste |
-| `side_padding` | `2` | left margin in columns |
-| `status_bar` | `true` | input box and status line at the bottom |
-| `user_highlight` | `true` | light band behind your messages in the transcript |
 | `show_diffs` | `true` | print a diff after each file change |
+| `status_bar` | `true` | input box and status line at the bottom |
 | `workspace_write_scope` | `true` | keep writes inside the working directory |
-| `autopilot_confirm_sensitive` | `true` | ask before touching keys and credentials |
-| `network_access` | `"ask"` | `"deny"` or `"allow"` |
-| `require_verification` | `true` | ask the agent to check its own edits |
-| `prompt_split` | `true` | answer plain questions without the tool loop |
-| `escalation_local_model` | `""` | a larger local model to consult when stuck |
+| `network_access` | `"ask"` | `"deny"` removes `fetch_url`, `"allow"` skips the prompt |
 | `memory_enabled` | `true` | semantic memory |
-| `chat_log_enabled` | `true` | write full session logs |
-| `protocol` | `"v1"` | `"v2"` is experimental |
 
-## Logs and memory
-
-Each session is written to `~/.shellai/chatlog/` as a JSONL file: every
-request, every message sent to the model, every reply with its latency,
-every tool call with its output. Secrets in the config are redacted.
-`/stats` prints the path of the current file.
-
-```powershell
-python tools/chatlog_report.py                  # summary across all sessions
-python tools/chatlog_report.py --last           # replay the most recent session
-python tools/chatlog_report.py --session 1a2b   # replay one session by id prefix
-```
-
-Memory is two local stores, one per project and one global, built on MiniLM
-embeddings. When idle, the agent condenses recent turns into short notes
-that are included in later prompts. `/memory` shows what is stored.
+`shellai.example.json` lists every key with its default, and `/setup`
+writes the file for you.
 
 ## Setup by hand
 
@@ -264,7 +223,7 @@ These are the steps `install.ps1` performs. `--doctor` checks each one.
 **1. The package**
 
 ```powershell
-pip install .        # from the checkout: the hex and hexcli commands, numpy, onnxruntime
+pip install hexcli   # or, from the checkout: pip install .
 ```
 
 `ruff` is optional and enables the `lint_code` tool.
@@ -286,22 +245,26 @@ setx ADSP_LIBRARY_PATH "C:\Qualcomm\AIStack\QAIRT_2.50.0\lib\hexagon-v73\unsigne
 If `ADSP_LIBRARY_PATH` is missing, npurun crashes with
 `STATUS_STACK_BUFFER_OVERRUN`.
 
-**3. npurun and a model**
-
-The NPU server is a fork of npurun, at
-[NathanL15/npurun](https://github.com/NathanL15/npurun) on the
-`hexcli-fork` branch. Each release there has a prebuilt `npurun-arm64.exe`.
-Hex CLI expects one specific build, set by `REQUIRED_NPURUN` in
-`hexcli/launcher.py`. `--doctor` fails on an older build and `--update`
-replaces it (the download goes to `~\.shellai\bin`).
+**3. npurun and the model**
 
-To build from source, use the fork. It has the prompt cache rewind, usage
-reporting, exact `max_tokens`, and request watchdog that Hex CLI relies on.
+The NPU server is a fork of npurun at
+[NathanL15/npurun](https://github.com/NathanL15/npurun), branch
+`hexcli-fork`, with a prebuilt `npurun-arm64.exe` on each release. Hex CLI
+expects one specific build, set by `REQUIRED_NPURUN` in
+`hexcli/launcher.py`; `hexcli --update` downloads it to `~\.shellai\bin`
+and `--doctor` fails on an older one. The fork adds the prompt cache
+rewind, usage reporting, exact `max_tokens` and the request watchdog that
+Hex CLI relies on, so upstream npurun will not do. To build it yourself:
 
 ```powershell
 git clone -b hexcli-fork https://github.com/NathanL15/npurun
 cd npurun
 cmd /c "scripts\dev-shell-local.bat cargo install --path crates\npurun-cli"
+```
+
+The model downloads on the first `hex` run, or by hand:
+
+```powershell
 npurun pull qwen3-4b-instruct-2507      # about 2.5 GB
 ```
 
@@ -330,7 +293,7 @@ curl -L -o ~\.shellai\onnx\tokenizer.json https://huggingface.co/sentence-transf
 
 ## Development
 
-CI runs `ruff` and 25 offline test suites against a mock backend, so no NPU
+CI runs `ruff` and 29 offline test suites against a mock backend, so no NPU
 is needed for those:
 
 ```powershell
@@ -342,14 +305,15 @@ python evals/test_lineedit.py
 
 The live evals need the NPU server. They check what the model actually did,
 by looking at the filesystem and the answer, and run each case several
-times because the model is not deterministic.
+times because the model is not deterministic:
 
 ```powershell
 python evals/cases_smoke.py                        # quick check
-python evals/cases_extended.py --runs 3            # 41 cases
+python evals/cases_extended.py --runs 3            # 44 cases
 python evals/cases_multiturn.py --runs 3 --think-time 15
 python evals/compare.py <before.json> <after.json>
 python evals/gate.py --baseline <base.json> <candidate.json>
+python tools/chatlog_report.py --last             # replay the most recent session
 ```
 
 Restart the NPU server before each suite. After an hour or two of steady

{hexcli-2.8.0 → hexcli-2.8.1}/hexcli/__init__.py

@@ -3,4 +3,4 @@
 # The one place the version is written. pyproject.toml reads it (hatch
 # dynamic version), agent.VERSION re-exports it, and CI refuses a release
 # tag that does not match it.
-__version__ = "2.8.0"
+__version__ = "2.8.1"

{hexcli-2.8.0 → hexcli-2.8.1}/hexcli/compaction.py

@@ -270,7 +270,7 @@ def _maybe_auto_compact(
     The full summary is suppressed (quiet=True); only a one-line notice prints.
 
     Thrash guard: before 2.5.0's window-derived budget, a 2,200-token prompt
-    clamped the history budget to the 250-token floor (now ~850 against a
+    clamped the history budget to the 250-token floor (now ~800 against a
     3,696-token server budget), and the compacted tail usually exceeded it —
     so v2.2 re-fired every single turn, shredding the condensed block a little
     further each time while freeing almost nothing (the user-reported "by the

{hexcli-2.8.0 → hexcli-2.8.1}/install.ps1

@@ -400,6 +400,23 @@ if (-not $NoStartMenu) {
             if ($useTerminal) {
                 $wtSettings = Join-Path $env:LOCALAPPDATA "Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\settings.json"
                 $hasOwnProfile = (Test-Path $wtSettings) -and ((Get-Content $wtSettings -Raw) -match '"name"\s*:\s*"Hex CLI"')
+                if ($hasOwnProfile -and (Test-Path $iconPng)) {
+                    # The user's own copy of the profile is left alone, except
+                    # for an icon path that no longer exists (2.8.0 moved the
+                    # icon into the package): Terminal falls back to its own
+                    # logo on a missing file. A targeted text edit, so the
+                    # user's comments and formatting survive.
+                    $raw = Get-Content $wtSettings -Raw
+                    $m = [regex]::Match($raw, '"icon"\s*:\s*"((?:[^"\\]|\\.)*hexcli\.png)"')
+                    if ($m.Success) {
+                        $current = $m.Groups[1].Value.Replace('\\', '\')
+                        if (-not (Test-Path $current)) {
+                            $raw = $raw.Replace($m.Groups[1].Value, $iconPng.Replace('\', '\\'))
+                            [IO.File]::WriteAllText($wtSettings, $raw, (New-Object Text.UTF8Encoding $false))
+                            Write-Ok "Windows Terminal profile icon repaired: $iconPng"
+                        }
+                    }
+                }
                 if (-not $hasOwnProfile) {
                     $fragmentDir = Join-Path $env:LOCALAPPDATA "Microsoft\Windows Terminal\Fragments\Hex CLI"
                     New-Item -ItemType Directory -Force -Path $fragmentDir | Out-Null