Your agent gets
hands and eyes
on Windows.
让你的 agent
在 Windows 上
有手有眼。
winuse reads a Windows screen as a text tree, then clicks, types and runs commands — the way iPhone-use and android-use do for phones. winuse 把 Windows 屏幕读成文本树，再点击、输入、执行命令——就像 iPhone-use、android-use 之于手机。
beta · localhost + SSH · no telemetry · MIT内测版 · 只听回环 + SSH · 无遥测 · MIT
Agents can reason and browse and script. The one place they go blind is the native desktop — the apps with no API. agent 会推理、会上网、会写脚本。唯一够不到的，是原生桌面——那些没有 API 的程序。
Browser tools cover the web. Shell covers scripts. But GUI-only installers, settings panels and legacy software have no other way in.浏览器工具管网页，shell 管脚本。但只有图形界面的安装程序、设置面板、老旧软件，没有别的入口。
winuse is the hands and eyes, not the brain. It reads the accessibility layer and acts in the background where it can — without moving your mouse or stealing focus while you work.winuse 是手和眼，不是大脑。它读取无障碍层，能后台就后台——你在用电脑时，不动你的鼠标、不抢你的焦点。
How it works工作原理
A small agent in the signed-in desktop session, reachable only over your own SSH tunnel.一个常驻在登录桌面会话里的小服务，只能通过你自己的 SSH 隧道访问。
What makes it different与众不同之处
The GUI, as a text tree把界面读成文本树
Instead of guessing pixels, winuse hands your agent the accessibility tree: every control as a line with a stable reference like @e12. Cheaper than screenshots, and precise. Pixels are the fallback, not the default.winuse 不靠猜坐标，而是把无障碍树交给 agent：每个控件一行，带一个稳定引用，比如 @e12。比截图省 token，也更准。截图只是兜底，不是默认。
Acts in the background后台操作
Ref actions go through UI Automation — no pointer movement, no focus change, and they work even when the window is covered. Real input is refused while you're using the PC.对引用的操作走 UI Automation——不移动指针、不抢焦点，窗口被遮挡也能用。你在用电脑时，真实输入会被暂缓。
CLI · skill · MCP命令行 · skill · MCP
A plain CLI for shell-capable agents, a loadable skill for Claude Code, and a stdio MCP server for Codex, Cursor, Gemini CLI and the rest.给能用 shell 的 agent 一个命令行，给 Claude Code 一个可加载 skill，给 Codex、Cursor、Gemini CLI 等一个 MCP 服务。
Localhost + token回环 + 令牌
The agent binds 127.0.0.1 only and checks a token. The sole remote path is your SSH key. No telemetry, ever.服务只监听 127.0.0.1 并校验令牌，唯一的远程入口是你的 SSH 密钥。永不遥测。
Unicode input任意语言输入
Typing is injected as Unicode, so Chinese, Japanese and emoji work regardless of the keyboard layout or IME.输入以 Unicode 方式注入，中文、日文、emoji 都不经过输入法，直接可用。
Sleep & wake睡眠与唤醒
Prefer sleep over shutdown: winuse wake sends a magic packet and the signed-in session comes right back — no sign-in screen.优先睡眠而非关机：winuse wake 发一个魔术包，登录会话立刻回来，不经过登录界面。
Quickstart快速上手
One install on the Windows PC, one config on your machine, then connect your agent.Windows 上装一次，你的机器上配一次，然后接上你的 agent。
On the Windows PC在 Windows 上
# PowerShell, one line: irm https://winuse.ozlab.xyz/install.ps1 ` | iex
Finds or installs Python, sets up a venv, a token and a logon task, and starts the agent. Needs OpenSSH with key login. It prints the token.自动找到或安装 Python，建好虚拟环境、令牌和登录自启任务并启动。需要 OpenSSH 密钥登录。结束时会打印令牌。
On your machine在你的机器上
# macOS / Linux, one line: curl -fsSL https://winuse.ozlab\ .xyz/install.sh | sh winuse status
Installs the CLI into ~/.local and asks for the PC's SSH host and the token. Add -s -- --skill for the Claude skill.把命令行装到 ~/.local，并询问 PC 的 SSH 主机名和令牌。加 -s -- --skill 可一并装 Claude skill。
Connect your agent接上你的 agent
# install with the skill in one go curl -fsSL https://winuse\ .ozlab.xyz/install.sh | sh -s -- --skill
claude mcp add winuse -- \ ~/.local/bin/winuse-mcp
# any shell-capable agent
winuse snap --window chromeSecurity model安全模型
Full desktop control is powerful. Here's exactly where the boundaries are.完全的桌面控制权力很大，这里讲清楚边界在哪。
Localhost only只听回环
The agent binds 127.0.0.1; nothing listens on the LAN. Remote access is your SSH tunnel — your key is the real boundary.服务只绑定 127.0.0.1，局域网上没有监听。远程入口就是你的 SSH 隧道——密钥才是真正的边界。
Token on every call每次调用都带令牌
A bearer token readable only by Administrators and SYSTEM stops other local processes from using the agent.令牌只有管理员和 SYSTEM 可读，防止 PC 上的其他进程借用这个服务。
User-present guard用户在场保护
Real mouse and keyboard input is refused while you're actively using the PC, unless forced. Background actions don't touch the pointer.你在用电脑时，真实键鼠输入会被拒绝（除非强制）。后台操作则完全不碰指针。
No telemetry, no stored secrets无遥测，不存密码
Nothing leaves the machine. Typed text is never logged — only its length — and password fields are masked.没有任何数据离开本机。输入的文字从不记录（只记长度），密码框会被遮蔽。
Limits & FAQ限制与常见问题
Beta. Verified so far on one Windows 11 machine, single monitor at 100% scale, agent run as administrator. Not yet tested: multi-monitor, non-100% DPI, non-admin mode, and a fresh install from the installer script end-to-end. No PyPI package yet — install from GitHub. The legacy-combobox fallback briefly borrows the real cursor.内测版。目前仅在一台 Windows 11、单显示器 100% 缩放、以管理员运行的机器上验证过。尚未测试：多显示器、非 100% DPI、非管理员模式，以及用安装脚本从零安装的完整流程。暂无 PyPI 包，请从 GitHub 安装。老式下拉框的兜底会短暂借用真实鼠标。
Does it work on the lock screen?锁屏时能用吗？
No — when the session is locked the desktop isn't interactive, and winuse reports it and refuses input. Prefer sleep over shutdown: a sleeping PC keeps its session and winuse wake brings it back with no sign-in screen.不能——会话锁定时桌面不可交互，winuse 会报告并拒绝输入。建议优先睡眠而非关机：睡眠的机器会话还在，winuse wake 唤醒后直接可用，不经过登录界面。
Is it tied to one PC or vendor?只能用于某一台电脑吗？
No. The host, port and wake address are config, not code — point it at any Windows 10/11 machine you can reach over SSH.不是。主机、端口、唤醒地址都是配置而非写死的代码——指向任何你能通过 SSH 访问的 Windows 10/11 机器即可。
Can it play games?能用来玩游戏吗？
It's not built for that, and you shouldn't: injecting input into anti-cheat-protected games can get accounts banned. winuse is for productivity apps, settings and GUI tools.不是为此设计的，也不建议：向有反作弊的游戏注入输入可能导致封号。winuse 面向效率软件、设置和图形工具。
What about multi-monitor and high-DPI?多显示器和高 DPI 呢？
Coordinates are physical pixels across the whole virtual desktop and the code is DPI-aware, but it's been tested mainly on a single 100%-scaled monitor — treat multi-monitor as early and report issues.坐标是整个虚拟桌面的物理像素，代码也做了 DPI 适配，但目前主要在单块 100% 缩放的屏幕上测过——多显示器还算早期，遇到问题欢迎反馈。
Is winuse the agent itself?winuse 自己是 agent 吗？
No. It's the hands and eyes — the tools. Your AI agent (Claude Code, Codex, Cursor, …) does the reasoning and decides what to do.不是。它只是手和眼——是工具。思考和决策由你的 AI agent（Claude Code、Codex、Cursor 等）完成。