Content
# Windows Appshots
Windows Appshots is a local application snapshot MCP plugin for Windows Agent tools. It captures the current foreground window, saves PNG screenshots, JSON metadata, and optional Windows UI Automation text, allowing Agents like Codex, WorkBuddy, Cursor, Trae, Claude Code, opencode, etc., to obtain the current desktop application context.
## What It Can Do
- Capture the current Windows foreground window as a PNG
- Save window title, process, window position, output path, and other JSON metadata
- Optionally capture UI Automation text exposed by the target application
- Generate Markdown snapshot files for easy analysis by Agents
- Provide MCP tool: `take_windows_appshot`
- Provide hotkey mode: `Ctrl+Alt+PrintScreen`
Default output directory:
```text
%USERPROFILE%\.codex\appshots\windows
```
## Quick Start
For users unfamiliar with the command line, you can send this prompt to Codex, WorkBuddy, or other Agents that can operate the local command line:
```text
Please help me install Windows Appshots on Windows.
Objective:
1. Check if git and python are available on this machine.
2. Clone https://github.com/Frog1205/windows-appshots to %USERPROFILE%\plugins\windows-appshots.
3. If the directory already exists and is this repository, execute git pull to update.
4. If the current tool is Codex, run scripts\install-codex-personal.ps1, then execute codex plugin add windows-appshots@personal.
5. If the current tool supports MCP, add stdio MCP server:
- name: windows-appshots
- command: python
- args: %USERPROFILE%\plugins\windows-appshots\src\windows_appshots\mcp_server.py
6. After installation, tell me how to restart the current Agent and confirm that the tool list includes take_windows_appshot.
If you cannot directly modify the Agent configuration, output the MCP JSON that I should copy into it.
```
After installation, tell the Agent:
```text
Call windows-appshots, capture the current foreground window, and read UI text 3 seconds later.
```
Then switch to the target application window within 3 seconds.
## Manual Installation
```powershell
mkdir "$env:USERPROFILE\plugins" -Force
git clone https://github.com/Frog1205/windows-appshots.git "$env:USERPROFILE\plugins\windows-appshots"
```
Generic MCP Configuration:
```json
{
"mcpServers": {
"windows-appshots": {
"command": "python",
"args": [
"C:\\Users\\<your_username>\\plugins\\windows-appshots\\src\\windows_appshots\\mcp_server.py"
]
}
}
}
```
Codex Plugin Installation:
```powershell
powershell -NoProfile -ExecutionPolicy Bypass `
-File "$env:USERPROFILE\plugins\windows-appshots\scripts\install-codex-personal.ps1"
codex plugin add windows-appshots@personal
```
See more tool instructions in [docs/INSTALL.md](docs/INSTALL.md).
## Directory Structure
```text
windows-appshots/
.codex-plugin/ Codex plugin manifest
.mcp.json Codex plugin built-in MCP server configuration
src/windows_appshots/ Core runtime code
mcp_server.py MCP stdio server, exposing take_windows_appshot
Capture-Window.ps1 Windows foreground window screenshot and UI Automation text capture
hotkey_listener.py Ctrl+Alt+PrintScreen hotkey listener
scripts/ User-executable scripts
install-codex-personal.ps1
start-hotkey.ps1
examples/mcp/ MCP configuration examples for different Agents
generic-mcp-server.json
opencode.jsonc
docs/ Detailed documentation
skills/ Codex skill metadata
```
## Documentation
- [Installation Guide](docs/INSTALL.md)
- [Usage Instructions](docs/USAGE.md)
- [Development and Verification](docs/DEVELOPMENT.md)
- [Generic MCP Example](examples/mcp/generic-mcp-server.json)
- [opencode Example](examples/mcp/opencode.jsonc)
## Privacy and Security
Windows Appshots saves screenshots of your current foreground window and possible UI text. Avoid capturing sensitive content such as passwords, keys, private chats, financial information, customer data, etc., unless you explicitly need to provide this content to the Agent.
The project does not actively upload snapshots. Whether to send snapshot content to the Agent depends on how you call the MCP tool and handle the return path.
## License
MIT
