Save current changes before reorganizing drivers and cleaning workspace

2026-06-17 22:17:59 -04:00
parent 3356e5d4a2
commit 2813c11104
21 changed files with 2904 additions and 132 deletions
@@ -0,0 +1,79 @@
+# Desktop Companion Client for AI Agents
+
+This is a cross-platform (Linux, macOS, Windows) client that allows your computer to be used directly by AI Agents as a physical-like communication and display companion.
+
+It implements the Model Context Protocol (MCP) and exposes the host machine's actual hardware:
+- **Audio Output**: Plays pure tones and WAV files on your actual speakers.
+- **Audio Input**: Records voice messages from your microphone.
+- **Battery Status**: Exposes your laptop's real battery voltage and percentage.
+- **System Telemetry**: Reads host metrics (uptime, CPU loading).
+- **Dedicated Canvas Window**: Renders images and text drawn by the agent.
+- **Video Streaming**: Renders incoming 1-bit monochrome video streams (from sources streaming to TCP port 8081 or UDP port 8082).
+- **UDP Discovery**: Responds to local discovery beacons.
+
+## Requirements
+
+- Python 3.10+
+- **Pillow** (PIL) library (already installed in your environment)
+- **Audio Playback**: Uses native system players (`afplay` on macOS, `aplay`/`paplay`/`pw-play` on Linux, `winsound` on Windows).
+- **Audio Recording**:
+  - **Linux**: Standard `arecord` (pre-installed via `alsa-utils`).
+  - **macOS / Windows**: If `sounddevice` or `pyaudio` Python packages are installed, they will be used. Otherwise, it falls back to `sox`/`rec` if available, or generates a clean simulated wave format if no audio recorder is present.
+
+## Running the Client
+
+Start the client manually with:
+```bash
+python3 desktop_client/client.py
+```
+
+Options:
+- `--port`: HTTP JSON-RPC port (default is `8080`)
+- `--width`: Canvas width (default `480`)
+- `--height`: Canvas height (default `320`)
+- `--headless`: Run headlessly without Pygame GUI window (ideal for remote SSH servers)
+
+### Keyboard Controls (GUI Mode)
+- **`D`**: Switch the screen canvas back to the local **Host Telemetry Dashboard**.
+- **`S`**: Save a screenshot of the companion window.
+
+### Hidden Mode Behavior
+To avoid cluttering your screen, the GUI window starts **hidden** on boot. It runs silently in the background and only pops to the foreground when a message (drawing or video stream) is sent by the AI Agent.
+
+---
+
+## Running as a macOS Service (LaunchAgent)
+
+To run the companion client persistently as a background service that launches automatically on login, use the provided scripts:
+
+1. **Install and Start the Service**:
+   ```bash
+   ./desktop_client/setup_service.sh
+   ```
+2. **Uninstall/Stop the Service**:
+   ```bash
+   ./desktop_client/uninstall_service.sh
+   ```
+
+Logs are captured dynamically at:
+- Standard Out: `desktop_client/stdout.log`
+- Standard Error: `desktop_client/stderr.log`
+
+---
+
+## Configuring Claude Desktop / Agent Host
+
+To add this desktop client as an MCP tool provider, add the following to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "desktop-companion": {
+      "command": "/Users/adolforeyna/.pyenv/versions/3.10.12/bin/python3",
+      "args": [
+        "/Users/adolforeyna/Projects/MicroPython/test1/Screen/desktop_client/client.py"
+      ]
+    }
+  }
+}
+```
@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.adolforeyna.companionclient</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/Users/adolforeyna/.pyenv/versions/3.10.12/bin/python3</string>
+        <string>/Users/adolforeyna/Projects/MicroPython/test1/Screen/desktop_client/client.py</string>
+    </array>
+    <key>WorkingDirectory</key>
+    <string>/Users/adolforeyna/Projects/MicroPython/test1/Screen</string>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>StandardOutPath</key>
+    <string>/Users/adolforeyna/Projects/MicroPython/test1/Screen/desktop_client/stdout.log</string>
+    <key>StandardErrorPath</key>
+    <string>/Users/adolforeyna/Projects/MicroPython/test1/Screen/desktop_client/stderr.log</string>
+</dict>
+</plist>
@@ -0,0 +1,34 @@
+#!/bin/bash
+PLIST_NAME="com.adolforeyna.companionclient.plist"
+LOCAL_PLIST="/Users/adolforeyna/Projects/MicroPython/test1/Screen/desktop_client/${PLIST_NAME}"
+TARGET_DIR="${HOME}/Library/LaunchAgents"
+TARGET_PLIST="${TARGET_DIR}/${PLIST_NAME}"
+
+echo "=== Installing Desktop Companion LaunchAgent ==="
+
+# 1. Create target directory if it doesn't exist
+mkdir -p "${TARGET_DIR}"
+
+# 2. Unload the service if it's already running
+echo "Stopping existing agent if running..."
+launchctl bootout gui/$(id -u) "${TARGET_PLIST}" 2>/dev/null
+launchctl unload "${TARGET_PLIST}" 2>/dev/null
+
+# 3. Copy the plist file
+echo "Copying plist configuration..."
+cp "${LOCAL_PLIST}" "${TARGET_PLIST}"
+chmod 644 "${TARGET_PLIST}"
+
+# 4. Load/start the LaunchAgent
+echo "Loading and starting the service..."
+launchctl bootstrap gui/$(id -u) "${TARGET_PLIST}"
+# Or fallback if bootstrap fails
+if [ $? -ne 0 ]; then
+    launchctl load "${TARGET_PLIST}"
+fi
+
+echo "Service successfully installed and started!"
+echo "Check status using: launchctl list | grep com.adolforeyna.companionclient"
+echo "Logs are available at:"
+echo "  STDOUT: /Users/adolforeyna/Projects/MicroPython/test1/Screen/desktop_client/stdout.log"
+echo "  STDERR: /Users/adolforeyna/Projects/MicroPython/test1/Screen/desktop_client/stderr.log"
@@ -0,0 +1,17 @@
+#!/bin/bash
+PLIST_NAME="com.adolforeyna.companionclient.plist"
+TARGET_PLIST="${HOME}/Library/LaunchAgents/${PLIST_NAME}"
+
+echo "=== Uninstalling Desktop Companion LaunchAgent ==="
+
+if [ -f "${TARGET_PLIST}" ]; then
+    echo "Stopping and unloading the service..."
+    launchctl bootout gui/$(id -u) "${TARGET_PLIST}" 2>/dev/null
+    launchctl unload "${TARGET_PLIST}" 2>/dev/null
+    
+    echo "Removing plist configuration..."
+    rm "${TARGET_PLIST}"
+    echo "Service successfully uninstalled!"
+else
+    echo "Service is not installed."
+fi