windows-terminal-hygiene

Pre-flight checklist that keeps agent terminal commands from hanging on Windows — timeouts, non-interactive flags, pty, encoding, path separators, plus a 3-minute recovery flow for when something still gets stuck.

• Install: hermes skills install vollegrewar/windows-terminal-hygiene
• Works with any SKILL.md-compatible agent (Hermes, Codex, Claude Code, OpenClaw)
• Language: Chinese (targets the worst-hit audience — zh-CN Windows users live with GBK code pages, proxy setups, and MSYS quirks)

Why this exists

Running agent-generated terminal commands on Windows has a class of failures that has nothing to do with the model being dumb:

1. A curl without --max-time hangs forever when the proxy dies.
2. git commit without -m opens vim in a non-interactive shell and freezes.
3. python run bare opens a REPL that waits for stdin silently.
4. Approval-triggering commands wait on a notification button that doesn't work.
5. python -c "..." nested quotes explode in every shell on Windows.

The agent eventually fixes each one — after 3-6 rounds of probe → diagnose → rewrite. This skill front-loads the prevention so the first command already has --max-time, -m, </dev/null, and the rest.

It also answers a common misconception: upgrading PowerShell (or adding it to PATH) does not fix escaping problems. Which shell executes a command is decided by the agent's own config, not by what's installed. The fix is knowing which shell you're actually in and quoting for it.

What's inside

Section	Content
环境自测	30-second probes to discover your real shell, proxy vars, and stdout encoding
六大根源	Six hang causes with fixed command patterns (timeout / stdin / editor / approval / pty / quoting)
5 秒自检	Six yes/no checks to run before every command
快速恢复	3-minute triage: locate → network probe → kill → change approach
Pitfalls	MSYS path conversion, python -c quoting, PowerShell backslash, ps variants

Example

Instead of:

python -c "import json,sys; d=json.load(sys.stdin); print(d['total_count'])"
curl https://api.github.com/repos/x/y

Write:

curl --connect-timeout 15 --max-time 60 -s "https://api.github.com/repos/x/y" | python parse.py

License

MIT — see LICENSE.

---

中文说明

Windows 上 agent 终端命令防卡死清单：超时参数、非交互标志、pty、编码、路径分隔符的固定写法 + 执行前 5 秒自检 + 卡死后 3 分钟恢复流程。适用于 Hermes / Codex / Claude Code / OpenClaw 等任何读 SKILL.md 的 agent。

安装：

hermes skills install vollegrewar/windows-terminal-hygiene

背景：agent 在 Windows 上跑命令的卡死，大多不是模型能力问题，而是命令里埋着"会等待的东西"——没超时的 curl（代理一挂就吊死）、忘带 -m 的 git commit（打开 vim 僵死）、裸跑的 python（等 stdin 的 REPL）。模型每次都能事后修好，但要花 3-6 轮往返。本 skill 把这些坑前置到"生成命令时"就避开。

一个常见误解也在这里澄清：升级 PowerShell 版本、配置 PATH 解决不了转义问题——命令由哪个 shell 执行取决于 agent 自己的配置，与系统装了什么无关。