AiPC

<p align="center"> <img src="https://files.catbox.moe/e9o2sz.png" alt="AiPC by SYSIK"> </p> <h1 align="center">AiPC by SYSIK</h1> <p align="center"> <b>Give the agent "this" — and it gets a real PC.</b><br> Screen, mouse, keyboard, your browser, files, terminal, SSH — via the model's native tools. </p> <p align="center"> <a href="https://github.com/SysikNagibator/AiPC/releases"><img src="https://img.shields.io/github/v/release/SysikNagibator/AiPC?label=release" alt="release"></a> <img src="https://img.shields.io/badge/platform-Windows%2010%2F11-blue" alt="platform"> <img src="https://img.shields.io/badge/python-3.10%2B-green" alt="python"> <img src="https://img.shields.io/badge/tools-63-brightgreen" alt="tools"> <img src="https://img.shields.io/badge/license-MIT-lightgrey" alt="license"> </p> <p align="center"> <b>RU README: <a href="README_RU.md">Russian version</a></b> · Skills: <a href="SKILL.md">SKILL.md</a> · IDE matrix: <a href="docs/IDES.md">docs/IDES.md</a> </p> --- ## Contents - [What it is](#what-it-is) - [Why AiPC](#why-aipc) - [Quick start](#quick-start) - [The `aipc` menu](#the-aipc-menu) - [63 tools](#63-tools-for-the-model) - [Token efficiency](#token-efficiency) - [MCP connection](#mcp-connection) - [Self-update](#self-update) - [Safety](#safety) - [Troubleshooting](#troubleshooting) - [Project structure](#project-structure) - [Build from source](#build-from-source) - [License](#license) --- ## What it is **AiPC** is a local service + console utility that gives any AI agent full access to your computer over the open **MCP** (Model Context Protocol) standard. ``` [ Agent in any IDE ] --MCP/stdio--> [ AiPC-Core: one local service ] | +------------------+----------------+------------------+ | | | | Vision Control Browser System/Net screenshots, mouse+keyboard, your Chrome via files, terminal, UI tree, apps, CDP + history, processes, SSH, windows clipboard JS eval search, sysinfo ``` The agent stops being "text in a chat" and starts working like a human at the PC: it looks at the monitor, clicks, types, opens apps, googles in **your** browser, runs commands, uses SSH — and verifies every step with a new screenshot. If a model says "I have no computer access", the built-in system prompt (`aipc/server.py:SYSTEM_PROMPT`, also served as the `aipc_instructions` MCP prompt) forbids that answer and requires acting through AiPC tools. ## Why AiPC | Usual agent limits | With AiPC | |--------------------|-----------| | Blind: no screen | `screen_see` — screenshot as a native image block, cursor marked | | Clicks by guessing | `ui_snapshot` / `ui_find` — ready-made x/y coordinates (0–1000) | | Typing into the void | `focus_type` — verified focus + atomic typing; refuses to type blind | | Sleeps and hopes | `wait_for_window` / `wait_for_ui_element` / `wait_for_change` | | "Did it work?" unknown | `screenshot_diff`, `assert_ui`, `logs_tail`, `audit.log` | | No machine access | Files, terminal, processes, SSH/SFTP, browser, clipboard | | Token burn on screenshots | Native image blocks (~65 chars + image vs 55K chars of base64) | --- ## Quick start | Step | What to do | |------|------------| | 1 | Download **`AiPC_Win_1.0.7.exe`** from [Releases](https://github.com/SysikNagibator/AiPC/releases) and double-click it | | 2 | On first run it **sets everything up itself**: asks for admin once (UAC) → copies itself to `C:\Program Files\AiPC\` → adds the `aipc` command to PATH → registers itself in the MCP configs of all detected IDEs (`.bak` backup first) → opens the menu | | 3 | In your IDE refresh MCP servers (Refresh / restart) and give the agent a plain-language task | Example tasks: ``` look at my screen, what is this error? open YouTube and find a review of ... connect via SSH to 192.168.1.10 and fetch yesterday's log ``` Works with any tool-capable 2026 model: `claude-opus-5-5`, `gpt-6-astra`, `gpt-6-sol` / `luna`, `gemini-3.8-flash`, `claude-fable-5-1`. --- ## The `aipc` menu Open a regular `cmd` and type `aipc`. Green theme, no flicker (single-threaded `rich.Live` in an alternate buffer), gradient title, pulsing selection marker, danger items in red, status bar (`mode • version • tools`), quick splash on entry. Controls: **W** up, **S** down, arrows **↑/↓**, **Enter** select, digits 1–9, **Q** back/exit. Russian layout works by key position. No emoji, ASCII fallback included. | Item | What it does | |------|--------------| | Launch AiPC-Core | Handshake-check as an IDE would, then background Core (stdio detached) | | Stop | Stops Core (never touches foreign PIDs) | | Status / Self-test | Screen, mouse, terminal, config, MCP, browser | | Diagnostics (doctor) | Install, PATH, every IDE config, Chrome, disk — flags stale installs | | Check updates | Looks at GitHub releases; asks before downloading + installing | | Setup | Mode `ask/auto/read-only`, IDE, browser (CDP flag), SSH hosts | | Service | Reinstall + PATH, reconfigure MCP, kill Core, where-am-I info | | Logs | Last 20 lines of `audit.log` | | Exit | — | No menu at hand? Same actions as commands: `aipc update`, `aipc doctor`, `aipc kill`, `aipc keys` (keyboard diagnostics), `aipc status`, `aipc selftest`, `aipc setup`, `aipc install`, `aipc mcp`. --- ## 63 tools for the model **Vision (15):** `screen_see`, `screen_region`, `ui_snapshot` (active window by default: 0.69s / 17 nodes vs 1.7s / 200 desktop), `ui_find`, `assert_ui`, `windows_list`, `window_focus` (verified), `window_manage`, `window_find`, `get_active_window`, `wait_for_window`, `wait_for_ui_element`, `wait_for_change`, `screenshot_diff`, `screen_info`. **Mouse & keyboard (17):** `mouse_move/click/drag/double_click/right_click/middle_click` (drag with ctrl/shift/alt), `scroll`, `type_text` (auto-chunked, Cyrillic-safe), `press_key`, `key_down/up`, `clipboard_set/get` (+images), `sleep`, `open_app`, `focus_type` (verified focus + atomic type — the only correct way to type). **Browser (6):** `browser_tabs`, `browser_goto`, `browser_eval` (JS via CDP — more reliable than coordinate clicks), `browser_active_tab`, `browser_close_tab`, `browser_history_search` (read-only copy of the History DB). **Files & system (13):** `fs_list/read/write/find/stat/mkdir/delete/move` (atomic writes + `.bak`, binary guard, pagination, deny-lists), `run_cmd` (split stdout/stderr, Russian OEM decoding, deny-list), `process_list/find`, `wait_for_process`, `download_file` (streamed, no size cap). **Network & machine (5):** `web_search_pc`, `ssh_exec`, `ssh_sftp_get/put` (200 MB+ friendly streaming), `sys_info` (battery/memory/CPU/disks), `net_check`, `env_get` (refuses secret-like names). **Human & debug (4):** `notify_user` (popup, non-blocking), `ask_user` (Yes/No, blocks for a human decision), `aipc_status`, `logs_tail`. Agent loop: **see (`screen_see`) → do → re-see to verify**. Errors are structural: `{"ok": false, "reason": "not_found|timeout|denied|..."}`. Every call runs exactly once, serialized; every call lands in `~/.aipc/audit.log` (2 MB rotation). ## Token efficiency - Screenshots travel as **native MCP image blocks**: ~65 chars of JSON + image instead of ~55K chars of base64 text (~10x cheaper per screenshot). `raw=true` returns legacy base64 if a client can't render images. - UI nodes are compact: `{"t","n","x","y"}` instead of long keys. - `ui_snapshot` defaults to the active window; role/name filters cut tokens further. - Prefer search over listing: `ui_find` / `window_find` / `fs_find` / `process_find`. - All tool descriptions fit in one short line. --- ## MCP connection AiPC registers itself on every menu launch (19 configs across 14 IDE families). Manual reference format: ```json { "mcpServers": { "aipc": { "command": "C:\\Program Files\\AiPC\\AiPC_Win_1.0.7.exe", "args": ["mcp"] } } } ``` Full 40-IDE matrix (auto / preset / bridge): [docs/IDES.md](docs/IDES.md). Ready-made files: [mcp_presets/](mcp_presets/). Skill-style install: [SKILL.md](SKILL.md). Cloud IDEs without localhost access (Claude.ai, Manus, Devin, Bolt, v0, Lovable, Replit…) can't reach `127.0.0.1` — see the "Bridge" section in `docs/IDES.md`. ## Self-update Menu → "Check updates" (or `aipc update`): compares with the latest GitHub release, shows the changelog, and only with your explicit **Yes** downloads and reinstalls itself (UAC). Version is always visible in the menu title; `aipc doctor` flags a stale install in Program Files. --- ## Safety - Modes: `ask` (default — the model must confirm via `ask_user`), `auto`, `read-only` (all mutating tools blocked **server-side**, not just by prompt). - Admin rights needed **once** — copying into Program Files + writing PATH. - Deny-lists for commands (mimikatz, ransomware patterns, encoded PowerShell, `^`-obfuscation normalized) and paths (browser secrets, private keys, hives, `System32`) live in `~/.aipc/config.yaml` and **auto-upgrade** (`safety.version`) without wiping your additions. - Typing goes only into a **verified** foreground window (`focus_type`). - Secrets guard: `env_get` refuses `*KEY/*TOKEN/*SECRET/*PASSWORD*` names. - Emergency stop: menu → Stop, or `aipc kill` (verifies the PID is ours first). --- ## Troubleshooting | Symptom | Fix | |---------|-----| | Model says "no PC access" | Reconnect MCP (Refresh / restart IDE), remind: "you have aipc.* tools, start with screen_see" | | Menu doesn't respond to keys | Run `aipc keys`, press W/S/arrows/Enter/Esc — paste the 5 lines to us | | `aipc` command unknown | Open a **new** cmd (PATH applies to new shells); reinstall via `dist\aipc.exe` | | Right wall of the menu drifts | Update: frames render only via fixed-width `rich.Panel` since 1.0.4.4 | | Chrome tabs invisible | Menu → Setup → Browser (adds `--remote-debugging-port=9222`), restart Chrome | | Old version in Program Files | `aipc doctor` tells you; run fresh `dist\AiPC_Win_1.0.7.exe` → UAC → updated | | GitHub page/API 404s | Our repo was once throttled by GitHub abuse heuristics; mirror + support appeal process in issues | --- ## Project structure ``` AiPC/ aipc/ # server.py (MCP) · vision/control/os_ops/browser/net/sysinfo # notify · installer (self-install + 19 IDE configs) # maintenance (update/doctor/kill) · menu · policy/audit mcp_presets/ # ready-made MCP configs (16 files) assets/ # logo + exe icon (visible on light and dark themes) tools/ # build_exe.bat · build_icon.py · sign.bat · version_info.txt tests/ # pytest: policy, installer merge, server (19 tests) docs/ # IDES.md (40 IDEs) · SIGNING.md (SmartScreen) SKILL.md # one-file skill install · CHANGELOG.md · LICENSE (MIT) ``` --- ## Build from source ```bat python -m pip install -r requirements.txt python -m pytest tests -q python -m aipc selftest tools\build_exe.bat ``` Output: `dist\AiPC_Win_1.0.7.exe` (~36 MB, icon + publisher version-info) and `dist\AiPC-Setup.exe`. Signing away the blue SmartScreen: see [docs/SIGNING.md](docs/SIGNING.md) (needs a code-signing certificate: Certum Open Source ~€25/yr is the cheapest start). --- ## License MIT. Author — SYSIK. See [LICENSE](LICENSE).