<p align="center">
  <img src="assets/aipc_banner_en_v1_1.png" alt="AiPC by SYSIK">
</p>

<h1 align="center">AiPC by SYSIK</h1>

<h1 align="center">This tool is for personal automation and testing on your own machine. Do not use it for unauthorized access.</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%20%7C%20macOS%20%7C%20Linux-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-70-brightgreen" alt="tools">
  <img src="https://img.shields.io/badge/license-MIT-lightgrey" alt="license">
  <a href="https://aipc.sysik.mom"><img src="https://img.shields.io/badge/website-aipc.sysik.mom-3DDC84" alt="website"></a>
</p>

<p align="center">
  <b>🌐 Site: <a href="https://aipc.sysik.mom">aipc.sysik.mom</a></b> · RU README: <a href="README_RU.md">Russian version</a> · Skills: <a href="SKILL.md">SKILL.md</a> · IDE matrix: <a href="docs/IDES.md">docs/IDES.md</a>
</p>

<div align="center">
  <video src="https://github.com/user-attachments/assets/7cd96d2e-84bc-418c-90c8-cc13f923b69f" data-canonical-src="https://github.com/user-attachments/assets/7cd96d2e-84bc-418c-90c8-cc13f923b69f" controls="controls" width="640"></video><br>
  <b>Video overview</b> · <a href="https://github.com/user-attachments/assets/7cd96d2e-84bc-418c-90c8-cc13f923b69f">direct link</a>
</div>

---

## Contents

- [What it is](#what-it-is)
- [Why AiPC](#why-aipc)
- [Read this first: risks](#read-this-first-risks)
- [Quick start](#quick-start)
- [The `aipc` menu](#the-aipc-menu)
- [70 tools](#70-tools-for-the-model)
- [Token efficiency](#token-efficiency)
- [MCP connection](#mcp-connection)
- [Self-update](#self-update)
- [Safety](#safety)
- [What can go wrong](#what-can-go-wrong)
- [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)
tells it to use the tools when they are available — or honestly say what's missing.

## Why AiPC

<p align="center">
  <img src="assets/aipc_poster_long_en_v1.1.png" alt="AiPC by SYSIK">
</p>

| 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) |

---

## Read this first: risks

AiPC gives an AI model **real control over your PC**: it sees the screen,
moves the mouse, types, runs terminal commands, reads files, uses SSH.
That is the point — and the risk.

- Keep the default `ask` mode: the server shows **you** a Yes/No dialog for
  every dangerous action. The model cannot click "Yes" for you.
- Never switch to `auto` for tasks involving strangers' files, links or
  email attachments — prompt injection is real (see `docs/THREAT_MODEL.md`).
- Know the kill switch: `aipc panic` or **Ctrl+Alt+Shift+K** freezes everything.
- This tool is for **your own machine** (see the note at the top).

---

## Quick start

**Windows:** download **`AiPC_Win_1.1.1.exe`** from [Releases](https://github.com/SysikNagibator/AiPC/releases) and double-click it.

| Step | What to do |
|------|------------|
| 1 | 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 → opens the menu (MCP registration into IDEs is **explicit**: `aipc install --ide cursor` or menu → Settings → Connect IDE) |
| 2 | In your IDE refresh MCP servers (Refresh / restart) and give the agent a plain-language task |

**macOS / Linux:** binaries come from the same [Releases](https://github.com/SysikNagibator/AiPC/releases) page (`AiPC_macOS_*`, `AiPC_Linux_*`), or install from source:

```
npm i -g aipc-sysik   # easiest: downloads the binary for your OS
# or: pip install aipc-sysik
# or: pipx install aipc-sysik
# mirror (needs npm login): npm i -g @sysiknagibator/aipc-sysik
aipc mcp                 # MCP command for your IDE
aipc install --dry-run   # preview IDE changes before applying
```

> The exe above is just the convenient bundle. On macOS grant Accessibility + Screen Recording when asked; on Linux prefer an X11 session (Wayland blocks synthetic input) — details in `docs/PLATFORM.md`.

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

<p align="center">
  <img src="assets/aipc_poster_before_after_en_v2.png" alt="AiPC menu" width="640">
</p>

Open a regular `cmd` and type `aipc`. One `rich.Live` frame in an alternate
buffer, redrawn only on events — no flicker, no leftover lines. A rounded card
holds the logo, slogan and status (`core ● running`, mode, tools count);
below it a frameless numbered list with inline descriptions, groups split by
blank lines, the `❯` marker on the selection (danger items turn red when
selected, no fills anywhere). One dim footer line with the keys.
Controls: **W/S**, arrows **↑/↓**, **Home/End**, **Enter** open, digits 1–8
quick select, **Q** exit, **L** toggles language (wraps around the edges).
Russian layout works by key position. Themes: green/mono/amber
(Setup → Theme), `NO_COLOR` and ASCII fallback respected. Narrow windows hide
descriptions automatically; a background check notifies about new releases.

| Item | What it does |
|------|--------------|
| Launch AiPC-Core | Background server, IDE-style handshake |
| Stop | Only our own process |
| Status & self-test | Screen, mouse, terminal, MCP |
| Diagnostics | Install, PATH, IDE configs |
| Check updates | Compare with GitHub releases |
| Setup | Mode `ask/auto/read-only`, IDE, browser (CDP flag), SSH hosts, language, theme |
| 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`.

---

## 70 tools for the model

**Vision (18):** `screen_see`, `screen_region`, `screen_burst`, `window_shot`, `pixel_color`, `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 (19):** `mouse_move/click/drag/double_click/right_click/middle_click`, `mouse_position`
(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 (7):** `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`.

**Audio (1):** `audio_listen` (loopback — system sound, or mic; 1-30 s, WAV,
native audio block or saved file).

**Video (2):** `video_info` (duration/size/fps/codec), `video_frames`
(1-12 frames as image blocks — watch a clip frame by frame).

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.
- **Profiles** (`aipc mcp --profile ...`): `minimal` (12 tools: see→do→verify
  loop), `browser` (20 tools: + web), `full` (70, default). Measured tool-schema
  size: full ~12.9K chars, browser ~3.8K, minimal ~2.5K (**−81%** vs full).

---

## 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.1.1.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

| Mode | File writes/deletes | Commands/SSH | Typing in password managers | Who decides |
|------|--------------------|--------------|------------------------------|-------------|
| `ask` (default) | popup to YOU | popup to YOU | popup to YOU | human, every time |
| `auto` | allowed | allowed | allowed | model (except after untrusted input — taint-guard asks) |
| `read-only` | blocked server-side | blocked server-side | blocked server-side | nobody |

- Modes: `ask` (default — the **server** pops a Yes/No dialog to YOU for every
  file-write/delete, command, SSH, download, browser-JS call; the model cannot
  bypass it; silence for 120 s = denied), `auto` (no dialogs),
  `read-only` (all mutating tools blocked **server-side**, not just by prompt).
- Risk classes: every tool is tagged `read/interact/mutate/exec/network`
  (`policy.TOOL_RISK`). read-only passes only `read`; ask confirms
  `mutate/exec/network`; typing/clicking inside password-manager, crypto-wallet
  or banking windows also asks. The dialog offers time choices — once,
  10 min, 1 hour (`safety.allow_presets`) — never forever.
- **Honest note:** deny-lists only *reduce* risk, they are not a security
  boundary (obfuscation always evolves). The real boundary is modes +
  server-side confirmations. For strict setups use `run_cmd_policy: allowlist`
  — only listed command prefixes run, everything else asks.
- Admin rights needed **once** — copying into Program Files + writing PATH.
- Deny-lists for commands (mimikatz, ransomware patterns, encoded PowerShell,
  quotes/`^`/env-var/chain-obfuscation normalized) and paths (browser secrets,
  private keys, hives, `System32`) live in `~/.aipc/config.yaml` and **auto-upgrade**
  (`safety.version`) without wiping your additions. Paths inside `run_cmd`
  (`type ...\Login Data`) are checked too.
- 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).

---

## What can go wrong

- **Prompt injection**: a web page, document or chat message tells the agent
  to delete/send/run something. Mitigations: `untrusted` markers, taint-guard
  confirmations, `ask` by default. Still — read the confirmation dialogs.
- **Wrong window, wrong click**: the agent acts on what it sees; a changed
  layout means a wrong button. `focus_type` refuses to type blind, but stay
  nearby for destructive tasks.
- **Update without signature**: `aipc update` downloads an exe checked only
  for the MZ header. Don't update over hostile networks.
- **Secrets in context**: the agent may paste a token it read into chat.
  `audit.log`, `env_get` and `fs_read` mask known patterns; everything else
  is your eyes on the screen.

Full version: [`docs/THREAT_MODEL.md`](docs/THREAT_MODEL.md).

---

## 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.1.1.exe` → UAC → updated |
| MCP not in IDE | Run `aipc install --list-ides`, then `aipc install --ide cursor` (or `--all`); preview with `--dry-run` |
| Remove AiPC | `aipc uninstall` (removes our MCP entries, PATH, Program Files copy; `--yes` for scripts) |
| GitHub page/API 404s or rate-limits | Wait a minute and retry; check your token scopes and proxy; if the outage persists, open an issue with the timestamp |

---

## 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 (AiPC_Logo.svg/png) + app icons: AiPC.ico (Windows),
                   # AiPC.icns (macOS) — visible on light and dark themes;
                   # AiPC_promo*.mp4 — video overviews (EN/RU) for README
  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.1.1.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).