claude-kvm 2.0.7 → 2.0.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +15 -79
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,13 +1,18 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<a href="https://github.com/ARAS-Workspace/claude-kvm">
|
|
3
|
+
<img src="https://github.com/ARAS-Workspace/claude-kvm/raw/press-kit/press-kit/masters/claude-kvm-icon-animated.svg" alt="Claude KVM" width="180"/>
|
|
4
|
+
</a>
|
|
5
|
+
</p>
|
|
6
|
+
|
|
7
|
+
<h1 align="center">Claude KVM</h1>
|
|
8
|
+
|
|
9
|
+
<p align="center"><em>Remote Access, Artificial Intelligence</em></p>
|
|
2
10
|
|
|
3
11
|
Claude KVM is an MCP tool that controls remote desktop environments over VNC. It consists of a thin JS proxy layer (MCP server) and a platform-native Swift VNC daemon running on your macOS system.
|
|
4
12
|
|
|
5
13
|
[](https://github.com/ARAS-Workspace/claude-kvm/blob/main/test/README.md)
|
|
6
14
|
[](https://github.com/ARAS-Workspace/claude-kvm/blob/test/e2e/mac/test/README.md)
|
|
7
15
|
|
|
8
|
-
> [!TIP]
|
|
9
|
-
> **[Phantom-WG](https://www.phantom.tc) could be a great alternative for you.** Isolate your VNC server within your own network while enjoying self-hosted VPN performance with the extra privacy features you gain along the way.
|
|
10
|
-
|
|
11
16
|
## Live Test Runs
|
|
12
17
|
|
|
13
18
|
- [Integration Test](https://github.com/ARAS-Workspace/claude-kvm/actions/runs/22261661594)
|
|
@@ -20,70 +25,12 @@ Claude KVM is an MCP tool that controls remote desktop environments over VNC. It
|
|
|
20
25
|
- [Mac Chess Direct Test](https://github.com/ARAS-Workspace/claude-kvm/actions/runs/22286704229)
|
|
21
26
|
- [Mac Phantom-WG Install Test](https://github.com/ARAS-Workspace/claude-kvm/actions/runs/22315144741)
|
|
22
27
|
|
|
23
|
-
> [!NOTE]
|
|
24
|
-
> Tests are conducted transparently on GitHub Actions — each step is visible in the CI environment. At the end of every test, whether the integration passes or fails, you'll find screenshots of each step the agent took during the session, along with an `.mp4` video recording that captures the entire session. By reviewing these recordings and screenshots, you can observe how the agent progressed through each stage, how long the task took, and what decisions were made based on the system prompt. You can use these examples as a reference when crafting your own system prompts or instructions for the MCP server in your own environment.
|
|
25
|
-
|
|
26
|
-
> [!WARNING]
|
|
27
|
-
> Artifacts attached to these runs may have expired due to GitHub's artifact retention policy. Persistent copies are prepared via the [Persist Artifacts](https://github.com/ARAS-Workspace/claude-kvm/actions/workflows/persist-artifacts.yml) workflow and can always be accessed by run ID from the [`artifacts/`](https://github.com/ARAS-Workspace/claude-kvm/tree/press-kit/artifacts) directory on the press-kit branch.
|
|
28
|
-
|
|
29
28
|
## Architecture
|
|
30
29
|
|
|
31
|
-
```
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
end
|
|
36
|
-
|
|
37
|
-
subgraph Proxy["claude-kvm · MCP Proxy (stdio)"]
|
|
38
|
-
direction TB
|
|
39
|
-
Server["MCP Server<br/><code>index.js</code>"]
|
|
40
|
-
Tools["Tool Definitions<br/><code>tools/index.js</code>"]
|
|
41
|
-
Server --> Tools
|
|
42
|
-
end
|
|
43
|
-
|
|
44
|
-
subgraph Daemon["claude-kvm-daemon · Native VNC Client (stdin/stdout)"]
|
|
45
|
-
direction TB
|
|
46
|
-
CMD["Command Handler<br/><i>PC Dispatch</i>"]
|
|
47
|
-
Scale["Display Scaling<br/><i>Scaled ↔ Native</i>"]
|
|
48
|
-
|
|
49
|
-
subgraph Screen["Screen"]
|
|
50
|
-
Capture["Frame Capture<br/><i>PNG · Crop · Diff</i>"]
|
|
51
|
-
OCR["OCR Detection<br/><i>Apple Vision</i>"]
|
|
52
|
-
end
|
|
53
|
-
|
|
54
|
-
subgraph InputGroup["Input"]
|
|
55
|
-
Mouse["Mouse<br/><i>Click · Drag · Move · Scroll</i>"]
|
|
56
|
-
KB["Keyboard<br/><i>Tap · Combo · Type · Paste</i>"]
|
|
57
|
-
end
|
|
58
|
-
|
|
59
|
-
VNC["VNC Bridge<br/><i>LibVNCClient 0.9.15</i>"]
|
|
60
|
-
|
|
61
|
-
CMD --> Scale
|
|
62
|
-
Scale --> Capture
|
|
63
|
-
Scale --> Mouse
|
|
64
|
-
Scale --> KB
|
|
65
|
-
Capture -.->|"framebuffer"| VNC
|
|
66
|
-
Mouse -->|"pointer events"| VNC
|
|
67
|
-
KB -->|"key events"| VNC
|
|
68
|
-
end
|
|
69
|
-
|
|
70
|
-
subgraph Target["Target Machine"]
|
|
71
|
-
VNC_Server["VNC Server<br/><i>:5900</i>"]
|
|
72
|
-
Desktop["Desktop Environment"]
|
|
73
|
-
VNC_Server --> Desktop
|
|
74
|
-
end
|
|
75
|
-
|
|
76
|
-
AI <-->|"stdio<br/>JSON-RPC"| Server
|
|
77
|
-
Server <-->|"stdin/stdout<br/>PC (NDJSON)"| CMD
|
|
78
|
-
VNC <-->|"RFB Protocol<br/>TCP :5900"| VNC_Server
|
|
79
|
-
|
|
80
|
-
classDef proxy fill:#1a1a2e,stroke:#16213e,color:#e5e5e5
|
|
81
|
-
classDef daemon fill:#0f3460,stroke:#533483,color:#e5e5e5
|
|
82
|
-
classDef target fill:#1a1a2e,stroke:#e94560,color:#e5e5e5
|
|
83
|
-
|
|
84
|
-
class Server,Tools proxy
|
|
85
|
-
class CMD,Scale,VNC,Capture,Mouse,KB daemon
|
|
86
|
-
class VNC_Server,Desktop target
|
|
30
|
+
```bash
|
|
31
|
+
# Architecture
|
|
32
|
+
# Rendered as a Mermaid diagram on GitHub:
|
|
33
|
+
open "https://github.com/ARAS-Workspace/claude-kvm#architecture"
|
|
87
34
|
```
|
|
88
35
|
|
|
89
36
|
### Layers
|
|
@@ -144,13 +91,6 @@ brew tap ARAS-Workspace/tap
|
|
|
144
91
|
brew install claude-kvm-daemon
|
|
145
92
|
```
|
|
146
93
|
|
|
147
|
-
> [!NOTE]
|
|
148
|
-
> `claude-kvm-daemon` is compiled and code-signed via CI (GitHub Actions). The build output is packaged in two formats: a `.tar.gz` archive for Homebrew distribution and a `.dmg` disk image for notarization. The DMG is submitted to Apple servers for notarization within the same workflow — the process can be tracked from CI logs. The notarized DMG is available as a CI Artifact; the archived `.tar.gz` is also published as a release on the repository. Homebrew installation tracks this release.
|
|
149
|
-
>
|
|
150
|
-
> - [Release](https://github.com/ARAS-Workspace/claude-kvm/releases/tag/daemon-v1.0.1) · [Source Code](https://github.com/ARAS-Workspace/claude-kvm/tree/daemon-tool)
|
|
151
|
-
> - [LibVNC Build](https://github.com/ARAS-Workspace/claude-kvm/actions/runs/22122975416) · [LibVNC Branch](https://github.com/ARAS-Workspace/claude-kvm/tree/libvnc-build)
|
|
152
|
-
> - [Homebrew Tap](https://github.com/ARAS-Workspace/homebrew-tap)
|
|
153
|
-
|
|
154
94
|
### MCP Configuration
|
|
155
95
|
|
|
156
96
|
Create a `.mcp.json` file in your project directory:
|
|
@@ -174,9 +114,6 @@ Create a `.mcp.json` file in your project directory:
|
|
|
174
114
|
}
|
|
175
115
|
```
|
|
176
116
|
|
|
177
|
-
> [!NOTE]
|
|
178
|
-
> The tool is end-to-end tested via CI — Claude executes tasks over VNC while an independent vision model observes and verifies the results. See the [Integration Test](https://github.com/ARAS-Workspace/claude-kvm/blob/main/test/README.md) for live workflow runs, system prompts, and demo recordings.
|
|
179
|
-
|
|
180
117
|
### Configuration
|
|
181
118
|
|
|
182
119
|
#### MCP Proxy (ENV)
|
|
@@ -346,9 +283,8 @@ macOS is auto-detected via the ARD auth type 30 credential request. When detecte
|
|
|
346
283
|
|
|
347
284
|
[](https://lobehub.com/mcp/aras-workspace-claude-kvm)
|
|
348
285
|
|
|
349
|
-
> [!NOTE]
|
|
350
|
-
> Running on a bare-metal Mac? See the [Mac M1 Preparation Tricks](https://gist.github.com/remrearas/a3f300635b02f2587a134882a51f7114) for VNC hardening, SSH tunneling, and session stability tips.
|
|
351
|
-
|
|
352
286
|
---
|
|
353
287
|
|
|
288
|
+
*"Claude" is a trademark of Anthropic, PBC. This project is not affiliated with or endorsed by Anthropic.*
|
|
289
|
+
|
|
354
290
|
Copyright (c) 2026 Riza Emre ARAS — MIT License
|