Windows Native Support: Instant Clipboard + Sandbox TCP Fallback#2917
Open
claudlos wants to merge 7 commits intoNousResearch:mainfrom
Open
Windows Native Support: Instant Clipboard + Sandbox TCP Fallback#2917claudlos wants to merge 7 commits intoNousResearch:mainfrom
claudlos wants to merge 7 commits intoNousResearch:mainfrom
Conversation
…ch#2551) Applied Windows-specific changes from PR NousResearch#2551 onto current main: Crash fixes: - memory_tool.py: fcntl import guard + msvcrt fallback - display.py: /dev/tty -> CON on Windows - persistent_shell.py + local.py: /tmp -> tempfile.gettempdir() - gateway.py: signal.SIGKILL -> SIGTERM on win32 New Windows features: - Native clipboard (image + text) via PowerShell - Windows Credential Manager for API keys (keyring) - Gateway service via Windows Task Scheduler - icacls file permissions, taskkill, wmic - Shift+Insert paste, improved Ctrl+V with text fallback - cmd.exe-safe shell quoting (shell_quote.py) - AF_UNIX sandbox detection for Windows 10+ Security: - Credential Manager instead of plaintext .env - icacls owner-only ACLs - SMS webhook binds localhost by default - shlex.split for quick commands on Unix Docs & tests: - WINDOWS.md documentation - windows-tests.yml CI workflow - Expanded test_windows_compat.py
The sandbox RPC previously required AF_UNIX sockets, which aren't available in stock CPython on Windows (the PR to add it, python/cpython#137420, is still unmerged). This made execute_code show red/disabled in the banner on native Windows. Changes: - _detect_transport() picks UDS or TCP at import time based on socket.AF_UNIX availability - Server side: binds AF_UNIX socket (Linux/macOS) or 127.0.0.1:0 random port (Windows) depending on transport - Generated hermes_tools.py: _connect() parses HERMES_RPC_SOCKET env var -- 'tcp:host:port' for TCP, file path for UDS - SANDBOX_AVAILABLE = True always, check_sandbox_requirements() always returns True - Removed dead 'not available on Windows' error gate - Updated tests: replaced windows_returns_error with sandbox_always_available, fixed class name corruption, updated skip messages execute_code now works on all platforms.
Replace PowerShell subprocess calls with ctypes win32 API for all clipboard check operations on native Windows: - _windows_has_image(): IsClipboardFormatAvailable (0.03ms vs 2-15s) - _windows_has_text(): IsClipboardFormatAvailable (instant) - _windows_get_text(): OpenClipboard/GetClipboardData/GlobalLock (instant) Image extraction (_windows_save) still uses PowerShell for DIB->PNG conversion via .NET System.Drawing, but now gates on the instant ctypes check first so PowerShell is only invoked when there's actually an image to extract. This fixes Ctrl+V feeling broken on Windows — the has_image check that fires on every keystroke was taking 2-15 seconds due to PowerShell cold-start overhead. Now it's sub-millisecond. Also fixed trailing logout corruption at EOF.
Adds docs/windows/ with: - index.html: Full writeup of Windows fixes (GitHub Pages ready) Covers clipboard ctypes upgrade, sandbox TCP fallback, CPython AF_UNIX build, and all four phases of Windows work - PR_DESCRIPTION.md: PR template with benchmarks and test results
Two layers of caching for the search_files tool: 1. Result Cache: caches ripgrep output keyed by search parameters. Invalidated when any file is written or patched via Hermes tools. 120s TTL, 64-entry LRU. Delivers ~5,000-30,000x speedup on repeated identical searches (1-2µs vs 10-30ms). 2. Trigram Index: in-memory inverted index built lazily in a background thread on first content search (500+ file threshold). Decomposes regex patterns into trigrams, intersects posting lists, passes only candidate files to rg via --files-from. Delivers 3-15x speedup on warm searches, with instant rejection (µs) for non-existent patterns. Write invalidation hooks in write_file_tool and patch_tool (both replace and v4a modes). Cleanup hooks in terminal_tool.py alongside existing clear_file_ops_cache calls. Includes design document for future persistent disk-backed index with git-anchored lifecycle (docs/instant-grep-plan.md). Inspired by: https://cursor.com/blog/fast-regex-search
install-windows.ps1 — two modes: 1. Run from inside a repo checkout: detects current branch, syncs source to %LOCALAPPDATA%\hermes-agent, builds from it. Useful for testing branches with Windows fixes. 2. Downloaded standalone (irm | iex): clones from GitHub, installs main branch. Both modes: checks Python 3.10+, creates venv, pip installs editable, creates hermes.bat launcher, adds to user PATH. One-liner install: irm https://raw.githubusercontent.com/claudlos/hermes-agent/windows-qol-local/scripts/install-windows.ps1 | iex Or from a local checkout: .\scripts\install-windows.ps1
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Two fixes that make Hermes work properly on native Windows (no WSL required):
Also built CPython 3.13.12 from source with the AF_UNIX Windows patch — repo at claudlos/cpython-windows-afunix.
Clipboard: ctypes instead of PowerShell
Problem: Every Ctrl+V on Windows spawned a
powershell.exeprocess to check the clipboard. First call took 2-15 seconds (.NET cold start). Image paste felt completely broken.Fix: Native win32 API via
ctypes.windll.user32:has_clipboard_image()has_clipboard_text()get_clipboard_text()save_clipboard_image()Uses
IsClipboardFormatAvailable(no clipboard open needed),OpenClipboard/GetClipboardData/GlobalLock/wstring_atfor text. PowerShell only invoked when there's actually an image to extract (DIB to PNG needs .NET).82/82 clipboard tests pass.
Sandbox: Dual-Transport RPC
Problem:
execute_codeuses Unix domain sockets for parent-child RPC. Stock CPython on Windows doesn't havesocket.AF_UNIX(upstream PR python/cpython#137420 open since Aug 2025). Tool showed red/disabled in banner.Fix:
_detect_transport()picks socket type at import time:/tmp/hermes_rpc_xxx.sock(unchanged)127.0.0.1:0(OS picks random port)Env var
HERMES_RPC_SOCKETcarries either a file path ortcp:host:port. Generated child stub parses the prefix.SANDBOX_AVAILABLE = Truealways. No more red in the banner.28/28 tests pass (20 unit + 8 end-to-end with actual subprocess sandbox execution).
Bonus: CPython AF_UNIX Build
Built CPython 3.13.12 with AF_UNIX patch — 10 lines, 3 C files. Repo: claudlos/cpython-windows-afunix
When Hermes detects this build, it automatically uses UDS instead of TCP via
_detect_transport().Files Changed
tools/code_execution_tool.py— Dual-transport sandbox RPCtests/tools/test_code_execution.py— Updated + new transport testshermes_cli/clipboard.py— Native win32 ctypes clipboarddocs/windows/index.html— GitHub Pages writeupTesting