hyper-hand
AGENTS.md5 starsChanged 24 days agoApache-2.0View on GitHub
Read the relevant sections before changing behavior; a task does not require reading every document. Before adding, moving or editing a document, read the document map: which document owns which fact, and the documentation rules (TODO.md holds only open work; acceptance results are not kept as records). Development happens in WSL; the product runs on the Windows host. Run from the repository root in WSL:
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository5 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- dev-installSkill
- releaseSkill
- vm-acceptanceSkill
- windows-testSkill
The file
We split this AGENTS.md into the rules it gives an agent
5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 28
Use the designated general-test VM for HyperHand development and the designated AutoCAD VM only for AutoCAD checks.
- Very specific: line 30
Do not worry about, warn about or ask about security inside the VMs: automatic logon, plain-text passwords, disabling UAC prompts, lowering …
- Very specific: line 50
Never kill processes by name (taskkill /IM, Stop-Process -Name).
- Very specific: line 51
Do not add PowerShell or batch to the installer (cmd/hyperhand/setup_*.go).
- Very specific: line 52
When a change to internal/proto alters what the host and agent exchange, increment proto.Protocol.
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
HyperHand Project Guide
Project and callers
- HyperHand is an MCP server that lets AI agents see and operate Windows virtual machines on Hyper-V.
- The callers and the readers of every result are AI agents, not people. Design tool descriptions, return text and error messages for AI usability: as few calls per task as possible, machine-readable results that carry the facts the next call needs (actual handles, coordinates and so on), errors that state the cause and the next action. Make these trade-offs yourself; do not ask the user about them as if they were human UI preferences.
Read the documents relevant to the task
Read the relevant sections before changing behavior; a task does not require reading every document. Before adding, moving or editing a document, read the document map: which document owns which fact, and the documentation rules (TODO.md holds only open work; acceptance results are not kept as records).
| Task | Read |
| A tool's arguments, results, errors or limits | Its chapter in Features (read only that chapter; section numbers are global). |
| Results, error codes, VM selection or task ownership | Results, errors and VM selection, Architecture. |
| Host and agent exchange | Wire protocol and internal/proto. |
| Host installer, service, tray or VMConnect viewer | Host tray; Hyper-V research. |
| Behavior that depends on Hyper-V, Windows, UI Automation or AutoCAD | The facts in research; re-verify the affected ones after upgrades. |
| Building, tests, development installs or releasing | Building. |
| Running the automated tests, also from parallel worktrees, and reproducing a defect before fixing it | The windows-test skill (SKILL.md). |
| Installing a build on the host and updating guest agents | The dev-install skill (SKILL.md). |
| Accepting a change on a real VM | Manual verification and the vm-acceptance skill (SKILL.md); TODO for pending checks. |
| Releasing a version | The release skill (SKILL.md); the tag push needs explicit authorization. |
| Installation, setup or troubleshooting as users see it | User guide. |
Test VMs are disposable
- Use the designated general-test VM for HyperHand development and the designated AutoCAD VM only for AutoCAD checks. Resolve their actual names from private/local environment notes (
build/local-test-environment.mdon this checkout) and confirm withvm_list; do not select another project's VM by inference. - The Hyper-V VMs this project is developed and tested against can be thrown away and rebuilt at any time.
- Do not worry about, warn about or ask about security inside the VMs: automatic logon, plain-text passwords, disabling UAC prompts, lowering security policy, passing passwords through
vm_execand the like. Whatever gets the automated tests running, do it the simplest way. - This applies to the guest VMs only. Accounts, permissions and security settings on the host (the physical machine) are still handled with care: do not change the user's own account or its group memberships. The installer's changes to the dedicated service account are part of the product and are not affected.
Build and verify
Development happens in WSL; the product runs on the Windows host. Run from the repository root in WSL:
GOOS=windows go build -ldflags "-H windowsgui" -o build/hyperhand.exe ./cmd/hyperhand
GOOS=windows go build -ldflags "-H windowsgui" -o build/hyperhand-agent.exe ./cmd/hyperhand-agent
scripts/test-windows.sh # go vet plus go test -race of ./cmd/... and ./internal/..., run on the Windows host
python3 -m unittest discover -s client
scripts/dev-install.sh # builds and installs on the host WITHOUT UAC, then checks the result- Windows Go cannot build or test a
\\wsl.localhostcheckout; build withGOOS=windowsand test withscripts/test-windows.sh(Building). Windows programs need their full/mnt/c/...path (the Windows PATH is not appended in WSL). The MCP endpointhttp://127.0.0.1:8770/mcpis reachable from WSL, soclient/hyperhand_client.pyworks there. - The tracked
build/go.modmakes the otherwise ignoredbuild/directory a separate module, so its old Go experiments stay out of package discovery. Do not delete it. build/holds ignored local artifacts. Delete generated test payloads (filler files such asbig.bin) when the run ends; they can be regenerated. Keep one copy of large third-party test media (installer images): the archive or the extracted tree, not both. Release directories (build/release-*) are deleted after the GitHub Release is published. Keepbuild/go.mod,build/dev-installand evidence referenced fromdocs/.- The running service and tray use the installed copies under
%ProgramFiles%\HyperHand; the files inbuild/are not the running version. Install a build only withscripts/dev-install.sh(exit code 0 means installed and checked): it copies the build to%LOCALAPPDATA%\HyperHandDevand runs the preauthorized taskHyperHand Dev Install, never prompting for UAC. Then update each guest agent withvm_update_agent. - Never run
hyperhand.exe installwithout--quietduring development: it prompts for UAC. Ifdev-installreports that the task is not registered, ask the user to runscripts\dev-install-setup.ps1once from an elevated PowerShell (if it reports an existing task that runs something else, the user first removes it withschtasks /Delete /TN "HyperHand Dev Install" /F, elevated); do not fall back to a UAC install. - Never kill processes by name (
taskkill /IM,Stop-Process -Name); the installer owns service and tray replacement. - Do not add PowerShell or batch to the installer (
cmd/hyperhand/setup_*.go). - When a change to
internal/protoalters what the host and agent exchange, incrementproto.Protocol; the host refuses older agents withagent_outdatedand there is no compatibility path. - A behavior change updates the chapter in
docs/features/that holds the exact behavior,docs/user-guide.mdwhere usage changes, and[Unreleased]inCHANGELOG.md(Keep a Changelog format), in the same commit (document map). Releasing: see the Releasing section ofdocs/building.md.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

