hexcli 2.8.0__py3-none-any.whl

hexcli-2.8.0.dist-info/METADATA

@@ -0,0 +1,394 @@
+Metadata-Version: 2.5
+Name: hexcli
+Version: 2.8.0
+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
+Project-URL: Bug Tracker, https://github.com/NathanL15/Hex-CLI/issues
+License: MIT
+License-File: LICENSE
+Keywords: agent,ai,arm64,cli,npu,snapdragon,terminal
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Terminals
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.26
+Requires-Dist: onnxruntime>=1.18
+Provides-Extra: dev
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Hex CLI
+
+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.
+
+## Requirements
+
+- Windows 11 on ARM with a Snapdragon X series chip
+- Python 3.11 or newer
+- The Qualcomm QAIRT SDK, 2.50 or newer (free developer account needed)
+
+Tested on a Snapdragon X Elite. It will not run on x86 machines or on Macs.
+
+## Install
+
+```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.
+
+## Usage
+
+```powershell
+hex                                  # start the NPU server and the REPL
+hexcli                               # REPL only, if the server is already running
+hexcli "what changed in this repo today?"
+git diff | hexcli "review this diff"
+echo "summarize README.md" | hexcli
+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.
+
+### Commands
+
+| Command | Does |
+|---|---|
+| `/help` | list all commands |
+| `/clear` | clear the screen and the chat |
+| `/new` | start a new chat, keep the scrollback |
+| `/history` | list past sessions |
+| `/resume <n>` | reopen a past session |
+| `/search <text>` | find past sessions by content |
+| `/diff` | show what the agent changed this turn |
+| `/undo` | revert the last exchange, including any files it wrote |
+| `/stats` | turns, time, tokens, context usage |
+| `/context` | how full the context is and when it will compact |
+| `/compact` | compress the history now |
+| `/memory` | inspect the memory store |
+| `/config [key [value]]` | view or set a config value for this session |
+| `/setup` | config wizard, writes the config file |
+| `/tools` | list the agent's tools |
+| `/cwd [path]` | show or change the working directory |
+| `/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.
+
+```powershell
+# .shellai/commands/review.md contains: Review $ARGUMENTS for bugs and style issues.
+/review src/parser.py
+```
+
+### Editing keys
+
+| Key | Does |
+|---|---|
+| `↑` `↓` | history. With text typed, searches by that prefix |
+| `Tab` | complete commands, config keys, and file paths |
+| `Ctrl+←` `Ctrl+→` | move by word |
+| `Home` `End` | start or end of line |
+| `Ctrl+W` `Ctrl+U` `Ctrl+K` | delete the word before, to line start, to line end |
+| `Esc` | clear the line |
+| `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.
+
+### 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
+request has to fit in there too.
+
+### Tools
+
+`run_command`, `read_file`, `edit_file`, `write_file`, `append_file`,
+`list_directory`, `search_files`, `find_files`, `verify_syntax`, `run_code`,
+`lint_code`, `search_memory`, `fetch_url`, `batch`, `delegate`. Run `/tools`
+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`.
+
+## Safety
+
+Commands are classified before they run:
+
+| Level | Examples | Behaviour |
+|---|---|---|
+| destructive | `Remove-Item`, `git reset --hard`, `format-*`, `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.
+
+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
+not reliably resist prompt injection, so none of the above depends on it
+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.
+
+| 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 |
+| `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 |
+| `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.
+
+## Setup by hand
+
+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
+```
+
+`ruff` is optional and enables the `lint_code` tool.
+
+**2. QAIRT SDK**
+
+Install version 2.50 or newer to `C:\Qualcomm\AIStack\QAIRT_<version>`.
+2.47 also works, but 2.50 lets the server keep the prompt cache between
+calls, which makes turns about 40% faster.
+
+The launcher uses the newest install it finds in that folder. To pin one,
+set both variables:
+
+```powershell
+setx QNN_SDK_ROOT "C:\Qualcomm\AIStack\QAIRT_2.50.0"
+setx ADSP_LIBRARY_PATH "C:\Qualcomm\AIStack\QAIRT_2.50.0\lib\hexagon-v73\unsigned"
+```
+
+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`).
+
+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.
+
+```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"
+npurun pull qwen3-4b-instruct-2507      # about 2.5 GB
+```
+
+**4. Embedding model**
+
+About 23 MB, into `~\.shellai\onnx`. Memory is disabled without it.
+
+```powershell
+mkdir ~\.shellai\onnx
+curl -L -o ~\.shellai\onnx\model_qint8_arm64.onnx https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/onnx/model_qint8_arm64.onnx
+curl -L -o ~\.shellai\onnx\tokenizer.json https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/tokenizer.json
+```
+
+## Limitations
+
+- A 4B model. It handles small, well-defined edits and questions about a
+  codebase. It is not a match for a hosted frontier model on large or vague
+  tasks.
+- 4,096 tokens of context. History is compacted often, and long files are
+  read in pages.
+- About 15 tokens per second on a Snapdragon X Elite. A follow-up turn takes
+  a second or two. The first turn of a new conversation takes longer while
+  the server rebuilds the prompt cache.
+- Windows on ARM only. Nothing here is portable to other platforms without
+  a different backend.
+
+## Development
+
+CI runs `ruff` and 25 offline test suites against a mock backend, so no NPU
+is needed for those:
+
+```powershell
+python evals/test_core.py
+python evals/test_agent_loop.py
+python evals/test_product_shell.py
+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.
+
+```powershell
+python evals/cases_smoke.py                        # quick check
+python evals/cases_extended.py --runs 3            # 41 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>
+```
+
+Restart the NPU server before each suite. After an hour or two of steady
+use it starts returning errors for everything, which looks like a model
+regression. The runner detects this and marks those runs invalid.
+
+`ARCHITECTURE.md` describes the module layout. `docs/V2_PLAN.md` has the
+hardware measurements, the eval method, and the reasoning behind each
+safety layer. `RELEASING.md` covers how a release is cut.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+npurun is Apache 2.0. The QAIRT SDK is Qualcomm's and has its own terms.

hexcli-2.8.0.dist-info/RECORD

@@ -0,0 +1,42 @@
+hexcli/__init__.py,sha256=C5c8rZZMGktk0oXyWJ36i4WSEjnhntt-1bvDVaYQN_c,239
+hexcli/agent.py,sha256=fKpaSkFqbuyPyVevzz9gTaxjtH1LS7Xs4t1lV3MQ_f0,83731
+hexcli/cancel.py,sha256=gZJX2dRWUrixJV-TRNmkDvhx4v4zszTT_6Ud-HKuVO0,2150
+hexcli/chatlog.py,sha256=HCbayFns_I7wwqCD43NO1EoXCshL7DPVv8FJF6kC9_0,9601
+hexcli/commands.py,sha256=1rmQavrtyTilSBvUEWNk21Femxy8r0vVghF5Jt0G9OI,2765
+hexcli/compaction.py,sha256=vIMl10lmPIdeO6egdNflZNkWGdoYfoIvYv5zdkFpO2o,12951
+hexcli/config.py,sha256=cVNfRjBNokgxPCTHBsIM9hmCpNmhMRU_mBQNRzC8C5I,9510
+hexcli/diffview.py,sha256=bzjzXi7byMKRx1yyeAJH3XHPx4Ye3vKzJ44VYEP-Ymo,3535
+hexcli/distribution.py,sha256=FOg-3xmcF9G146EFmdPWkpKl9U-xvS3Pzr_QnT1hOBU,8348
+hexcli/doctor.py,sha256=AaCAHRnq8EmvKkPWvyhb6ejZplofnxQKS50ZFnwOQJY,10783
+hexcli/escalate.py,sha256=3wn8KUOpYCa2aqJe80dqu0eKHOM6dYURHnp4_23genA,6892
+hexcli/http_client.py,sha256=ltESw9PR8ePwdexy-P8Im3eaXFdm86akVp8ijzblAl8,5857
+hexcli/launcher.py,sha256=hthUcEWFaPTDrH8YSpYco2me6j3aqvKgmwAlulg4QRE,20160
+hexcli/lineedit.py,sha256=AM5KigL4mk-3yShNpCDN8q0VfNH9wzxKzg7fCavJVfI,44745
+hexcli/llm.py,sha256=h6YF_chcDouNkpsVAiGhwXzJlqFnQgjA8XD0GVk55bM,23138
+hexcli/local_escalation.py,sha256=Q4ezDTLJRqvnpOi934aEQMTnNLQoNwA3ExP2LFEnaWs,7448
+hexcli/lockfile.py,sha256=T1AQEju_DxDdg4gfqr5tH1eOwyDIgrPygWlfrDryLGc,2343
+hexcli/loop_v2.py,sha256=CoJisB31Nh5cmuQnebYLMwlHQPLKKjn5KGfUTm5jNkw,17346
+hexcli/markdown_stream.py,sha256=7c62BO6vXFLt3EiYYXpUH6DZkDU6PfxSHLjdfUHZt8o,10132
+hexcli/memory.py,sha256=RCj0jrKmwIz2Le-HkGAsp_nH0ik0RoeAoVCtmfKehxE,15258
+hexcli/network.py,sha256=WNRyW4GJx0Y5wmUU0cfBUlCUkPXR3NKwlkrAbuMM_Ho,5201
+hexcli/parsing.py,sha256=wkm8Bt-3qbzHRHbv9mAjYCs4pcQ0jsMfNPJsdjeR4_M,8525
+hexcli/paths.py,sha256=T_9EbSR6INlgXFAxbCRnSoBktm2rLi-duKjVIcjQHZg,4006
+hexcli/prompts.py,sha256=QArEyd08lH0WoO_4ORojn_3rrDZcFsFwn0h04MI5JgI,18864
+hexcli/protocol_v2.py,sha256=3hHs_AN0RPOKOihQaUMvuC2AaUGDX1DXsxB4F4fQzUw,25405
+hexcli/repl.py,sha256=J7NAlQ_7KWEOb6mOKIkLCd41DvZ-h524EAvzlXndlsw,37227
+hexcli/safety.py,sha256=57iCipYvKDvezgdS0AvV2LkS1BynQHZF_8E_GND8JIo,5487
+hexcli/sessions.py,sha256=7TNfU4pfgnJYTICOBCzIRs6ROWids9SjOYlRlAdjhi8,8173
+hexcli/setup_wizard.py,sha256=np3RjKwyoMuxdJQSUhJ3dQGy4nbE-FininvBEOTl7us,5547
+hexcli/shell_session.py,sha256=rZ9ip2jizLtQfTck3-8mcSjTZXq6S4gJhDigb4ntER0,8307
+hexcli/statusbar.py,sha256=3CWz1e_bpjONPA7JuUvRlA-q1Suraowb3nWgvDvJ9kM,36608
+hexcli/stream_render.py,sha256=FYDwGb-XWEj13jcJJg69szHG-T0LwFlq5-kf7BoAJ3w,8932
+hexcli/telemetry.py,sha256=eghXX6yChYNp-vDKP4fwSqPZzEbvAa2G89-LblBDmZo,4756
+hexcli/tools.py,sha256=phjLMftiYn4HytvdfN7OC09CZjYMPTfMKgNIVwXa4p8,31127
+hexcli/ui.py,sha256=5FEwNHxR0QehOonRX_PvIKX_qAArzZYjCu8dh3lSG4c,43893
+hexcli/assets/hexcli.ico,sha256=LkMAk7mOShn6VCafsBq9EVQTKy-szN7OFcgbPJ3FK3w,60080
+hexcli/assets/hexcli.png,sha256=Fco7qSFwMGoXF-pnNoA10rB-o_Wij9KMx3n2b9KaSZo,31365
+hexcli-2.8.0.dist-info/METADATA,sha256=d3-XTkCXepPctfHHtB4gqtnn7vVlCGiaTZKMRYll2NM,15842
+hexcli-2.8.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+hexcli-2.8.0.dist-info/entry_points.txt,sha256=siibVCtS_CEA65VGsoGj1a7n-qNHDTi_gC3jq9McYeQ,72
+hexcli-2.8.0.dist-info/licenses/LICENSE,sha256=1mfF8m8fVppTDYGH79GTtUb4Jl_qBDXJGweqNxXHCqQ,1066
+hexcli-2.8.0.dist-info/RECORD,,

hexcli-2.8.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

hexcli-2.8.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+hex = hexcli.launcher:main
+hexcli = hexcli.agent:main

hexcli-2.8.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 NathanL15
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.