| # AirMouse Pro — Master Agent & System Guide (`AGENTS.md`) | |
| **Workspace Path:** `~/Documents/uni/CPS/Files/ComputerAssignments/CA2` | |
| **Project Name:** AirMouse Pro (CPS Computer Assignment 2) | |
| **Purpose:** Comprehensive system architecture, tool reference, workspace configuration, hook engine guide, and workflow specification for AI Agents and Developers. | |
| --- | |
| ## 1. Project Overview | |
| AirMouse Pro is a high-performance Cyber-Physical System (CPS) that transforms an Android smartphone into a wireless 3D air-mouse and spatial controller. The system consists of four primary subsystems: | |
| 1. **Android Client (`code/android/`)**: Pure Kotlin app package (`com.airmouse`) implementing IMU sensor reading, 3-step calibration, Madgwick AHRS sensor fusion ($\beta=0.041$), gesture detection, visual status indicators (green square with yellow click flash), Perfetto trace markers, and TCP newline-delimited JSON streaming. | |
| 2. **Go Desktop Server (`code/pc/airmouse_mcp_go/`)**: High-throughput multi-protocol native server (TCP 9090, WebSocket 9091, UDP Discovery 9092, UDP Stream 9093, REST Admin 8081). Handles OS cursor movement with Kalman predictive blending, power-law acceleration, and 500ms ACK retransmissions. | |
| 3. **Python MCP Server (`airmouse_server_mcp.py`)**: AI-Agent bridge built with `FastMCP` featuring **444 total tools** for building, testing, ADB automation, trace analysis, PyAutoGUI control, and dynamic server administration across CLI and stdio modes. | |
| 4. **Antigravity Workspace (`.agents/`)**: AI workspace configuration hub featuring 22 domain-specific skills, quality rules, system instructions, dynamic state memory, workflows, and environment variables. | |
| --- | |
| ## 2. Directory Layout | |
| ``` | |
| ~/Documents/uni/CPS/Files/ComputerAssignments/CA2/ | |
| ├── AGENTS.md # Master Agent & System Guide | |
| ├── AGENT.md # Architecture blueprint & math models | |
| ├── HOOKS.md # CLI & stdio 5-lifecycle hook system documentation | |
| ├── FINAL_PROJECT_DOCUMENTATION.md # Executive project documentation report | |
| ├── FULL_TEST_SUITE_RESULTS.md # Consolidated unit/integration test matrix | |
| ├── Gozarish_Perfetto_CA2.md # Perfetto trace latency analysis (Q1–Q11) | |
| ├── PROTOCOL_COMPLIANCE.md # Network protocol specification | |
| ├── README.md # Project repository guide | |
| ├── CPS-CA2-00000.zip # Final submission archive | |
| ├── airmouse_server_mcp.py # 444-tool FastMCP Python Server & CLI | |
| ├── create_plugins.py # Plugin registry generator script | |
| ├── code/ | |
| │ ├── android/ # Android Studio Gradle Project (Kotlin) | |
| │ │ ├── app/src/main/java/com/airmouse/ | |
| │ │ │ ├── sensors/ # MadgwickAHRS.kt, CalibrationHelper.kt, MotionDetector.kt | |
| │ │ │ ├── network/ # ConnectionManager.kt (TCP/UDP/ACK) | |
| │ │ │ └── ui/ # OnboardingActivity, CalibrationActivity, HomeFragment | |
| │ │ └── gradlew # Gradle build wrapper | |
| │ └── pc/ # Desktop Backend & Testing Tools | |
| │ ├── airmouse_mcp_go/ # Go Native Server source & main.go | |
| │ ├── airmouse-mcp-go # Compiled CGO-free Go binary | |
| │ ├── test_pc_server.py # Standalone TCP/ACK unit tests | |
| │ ├── test_e2e.py # End-to-end integration test runner | |
| │ └── perfetto_queries.sql # Perfetto trace metrics SQL queries | |
| └── .agents/ # Antigravity Workspace Hub | |
| ├── .env # Environment variables | |
| ├── .env.template # Environment template | |
| ├── config.json # Agent runtime configuration | |
| ├── instructions.md # System instructions & docs links | |
| ├── README.md # Workspace hub README | |
| ├── memory/ | |
| │ ├── known_issues.json # Resolved bugs & tuning memory | |
| │ └── project_state.json # Dynamic build & server state | |
| ├── rules/ | |
| │ └── airmouse-standards.md # Development & quality standards | |
| ├── workflows/ | |
| │ └── deploy.yml # Automation pipeline workflow | |
| └── skills/ # 22 Domain-Specific Skill Modules | |
| ├── airmouse-sensor-fusion/ # SKILL.md | |
| ├── airmouse-network/ # SKILL.md | |
| ├── airmouse-testing/ # SKILL.md | |
| ├── airmouse-perfetto/ # SKILL.md | |
| ├── airmouse-build/ # SKILL.md | |
| ├── airmouse-calibration/ # SKILL.md | |
| ├── airmouse-gesture-detection/# SKILL.md | |
| ├── airmouse-mouse-control/ # SKILL.md | |
| ├── airmouse-ui-automation/ # SKILL.md | |
| ├── airmouse-voice-commands/ # SKILL.md | |
| ├── airmouse-game-profiles/ # SKILL.md | |
| ├── airmouse-go-server-admin/ # SKILL.md | |
| ├── airmouse-project-overview/ # SKILL.md | |
| ├── airmouse-documentation/ # SKILL.md | |
| ├── airmouse-troubleshooting/ # SKILL.md | |
| ├── airmouse-performance-optimization/ # SKILL.md | |
| ├── airmouse-security/ # SKILL.md | |
| ├── airmouse-deployment/ # SKILL.md | |
| ├── airmouse-advanced-sensors/ # SKILL.md | |
| ├── airmouse-protocol-analysis/# SKILL.md | |
| ├── airmouse-customisation/ # SKILL.md | |
| └── airmouse-code-quality/ # SKILL.md | |
| ``` | |
| --- | |
| ## 3. Key Constants & Parameters | |
| | Parameter | Value | Subsystem | Description | | |
| |---|---|---|---| | |
| | `Madgwick Beta` ($\beta$) | `0.041` | Android Client | Fixed Madgwick AHRS filter gain parameter for optimal drift rejection. | | |
| | `Gyro Units` | `rad/s` | Android Client | Raw angular velocity from Android `SensorManager` (no degree conversion). | | |
| | `Gyro Click Threshold` | $> 8.0\text{ rad/s}$ | Gesture Engine | Angular velocity on Y-axis required to trigger a left-click gesture ($300\text{ms}$ cooldown). | | |
| | `Double Click Window` | $< 400\text{ ms}$ | Gesture Engine | Maximum time window between two left clicks to trigger a double-click event. | | |
| | `Accel Scroll Threshold` | $> 8.0\text{ m/s}^2$ | Gesture Engine | Y-axis acceleration threshold for vertical scrolling ($2.0\text{ m/s}^2$ debounce, $100\text{ms}$ cooldown). | | |
| | `Right Click Roll Tilt` | $> 45^\circ$ | Gesture Engine | Roll tilt angle required for right-click activation (held for $\ge 500\text{ms}$). | | |
| | `ACK Timeout` | `500 ms` | Networking | Maximum wait duration before retransmitting unacknowledged packets. | | |
| | `ACK Retries` | `3` | Networking | Maximum retransmission retry limit for `click`, `scroll`, and `control` messages. | | |
| | `TCP Port` | `9090` | Networking | Primary newline-delimited JSON streaming & command socket. | | |
| | `WebSocket Port` | `9091` | Networking | Browser & Web app connection port. | | |
| | `UDP Discovery Port` | `9092` | Networking | Broadcast port for auto-discovering PC servers on LAN. | | |
| | `UDP Stream Port` | `9093` | Networking | High-frequency low-overhead orientation streaming port. | | |
| | `REST Admin Port` | `8081` | Go Server | HTTP REST API port for live stats, device approval, and configuration. | | |
| --- | |
| ## 4. Python MCP Server (`airmouse_server_mcp.py`) | |
| The MCP server provides an AI-Agent bridge exposing **444 total tools** across dual execution modes: | |
| - **CLI Mode**: `python airmouse_server_mcp.py <tool_name> [args...]` | |
| - **MCP Stdio Mode**: `python airmouse_server_mcp.py` (FastMCP stdio JSON-RPC interface) | |
| ### Primary Tool Categories & Representative Tool Examples: | |
| - **Build**: `build_android_debug`, `build_android_release`, `clean_android_build`, `build_go_server`, `clean_go_build` | |
| - **Testing**: `test_android_unit`, `test_go_server`, `test_live_protocols`, `test_full_system`, `run_full_protocol_validation`, `generate_full_test_report` | |
| - **ADB & Device Control**: `list_adb_devices`, `install_apk`, `uninstall_apk`, `launch_android_app`, `clear_app_data`, `dump_logcat`, `screenshot_device`, `pull_traces` | |
| - **Server Management**: `start_server`, `stop_server`, `start_go_server`, `stop_go_server`, `restart_server`, `server_status`, `view_server_logs` | |
| - **Perfetto Trace Analysis**: `analyze_perfetto_trace`, `capture_perfetto_trace`, `get_perfetto_metric`, `run_perfetto_analyzer`, `answer_perfetto_q1` through `answer_perfetto_q11` | |
| - **Documentation**: `generate_master_documentation`, `generate_test_report`, `generate_perfetto_report`, `generate_project_tree`, `generate_changelog`, `generate_demo_script`, `generate_submission_zip` | |
| - **Mouse Control (PyAutoGUI)**: `move_mouse`, `move_mouse_to`, `left_click`, `right_click`, `double_click`, `scroll_up`, `scroll_down`, `drag_mouse`, `type_text`, `press_key`, `hotkey` | |
| - **Calibration Suite**: `calibration_check_status`, `calibration_reset`, `calibration_launch_gyro_step`, `calibration_launch_mag_step`, `calibration_launch_accel_step`, `calibration_validate_gyro_bias`, `calibration_validate_mag_offset`, `calibration_validate_accel_offset`, `calibration_compute_accel_6point` | |
| - **Go Server Admin**: `go_get_stats`, `go_get_devices`, `go_set_sensitivity`, `go_set_smoothing`, `go_set_acceleration`, `go_set_predictive`, `go_set_jitter_compensation`, `go_set_humanizer`, `go_set_gesture_thresholds`, `go_set_gesture_mapping` | |
| - **Gesture Simulation**: `test_gesture_click`, `test_gesture_double_click`, `test_gesture_right_click`, `test_gesture_scroll`, `test_gesture_move`, `gesture_thumbs_up`, `gesture_swipe_left` | |
| - **Utilities**: `search_files`, `read_file`, `list_directory`, `full_ci_pipeline`, `full_deploy`, `health_check`, `system_info`, `backup_project`, `clean_workspace`, `count_lines_of_code` | |
| --- | |
| ## 5. Antigravity Workspace Configuration (`.agents/`) | |
| ### 5.1 The 22 Workspace Skills Index | |
| | # | Skill Identifier | Description | Main Prompt Triggers | | |
| |---|---|---|---| | |
| | 1 | `airmouse-sensor-fusion` | Madgwick AHRS filter math, quaternions, Euler angle conversions, $\beta=0.041$ tuning. | `sensor fusion`, `madgwick`, `quaternion` | | |
| | 2 | `airmouse-network` | TCP (9090), WebSocket (9091), UDP Discovery (9092/9093), 500ms ACK retransmissions. | `network`, `tcp`, `websocket`, `ack` | | |
| | 3 | `airmouse-testing` | Unit, integration, live, and Mockito/Espresso test suites for Android, Go, and Python. | `test`, `unittest`, `robolectric`, `espresso` | | |
| | 4 | `airmouse-perfetto` | Perfetto trace capture, metrics queries, and answers for questions Q1 through Q11. | `perfetto`, `trace`, `q1`, `latency` | | |
| | 5 | `airmouse-build` | Android Gradle compilation, Go server CGO-free build, dependency resolution. | `build`, `compile`, `apk`, `gradle` | | |
| | 6 | `airmouse-calibration` | 3-step calibration (Gyro bias, Mag figure-8, Accel 6-position least-squares). | `calibrate`, `gyro bias`, `mag offset` | | |
| | 7 | `airmouse-gesture-detection` | Gyro Y-axis click ($>8.0\text{ rad/s}$), Accel Y scroll ($>8.0\text{ m/s}^2$), Roll tilt right-click ($>45^\circ$). | `gesture`, `click`, `scroll`, `right-click` | | |
| | 8 | `airmouse-mouse-control` | PyAutoGUI and native server-side cursor movement, click, drag, and hotkey automation. | `mouse`, `move`, `pyautogui`, `cursor` | | |
| | 9 | `airmouse-ui-automation` | ADB screen taps, swipes, input events, developer options, and layout inspection. | `adb`, `tap`, `swipe`, `logcat` | | |
| | 10 | `airmouse-voice-commands` | Speech recognition mapping, text-to-speech simulation, and voice control macros. | `voice`, `speech`, `command` | | |
| | 11 | `airmouse-game-profiles` | Gaming preset profiles (FPS, Racing, RPG) with custom sensitivity curves. | `game`, `profile`, `fps`, `racing` | | |
| | 12 | `airmouse-go-server-admin` | Go server REST Admin API (Port 8081) for live parameters, stats, and device approvals. | `go server`, `admin api`, `stats` | | |
| | 13 | `airmouse-project-overview` | High-level project architecture, folder layout, port assignments, and component maps. | `overview`, `architecture`, `ports` | | |
| | 14 | `airmouse-documentation` | Report generation (`FINAL_PROJECT_DOCUMENTATION.md`), changelogs, and submission ZIP. | `docs`, `report`, `changelog`, `zip` | | |
| | 15 | `airmouse-troubleshooting` | Error log diagnostics, ANR trace extraction, crash analysis, and ADB logcat parsing. | `error`, `crash`, `debug`, `anr` | | |
| | 16 | `airmouse-performance-optimization` | CPU/Memory/Network tuning, sensor sampling rate adjustments, build flags. | `perf`, `optimize`, `cpu`, `memory` | | |
| | 17 | `airmouse-security` | Authentication tokens, protocol validation, app permissions, and security hardening. | `security`, `permission`, `auth` | | |
| | 18 | `airmouse-deployment` | End-to-end build $\rightarrow$ install $\rightarrow$ launch $\rightarrow$ connect deployment pipeline. | `deploy`, `install`, `launch` | | |
| | 19 | `airmouse-advanced-sensors` | IMU sensor coordinate transformations, Allan variance, bias stability, CTS sensor tests. | `imu`, `allan variance`, `cts` | | |
| | 20 | `airmouse-protocol-analysis` | Packet inspection, retransmission timing, network jitter, and latency breakdown. | `protocol`, `packet`, `latency` | | |
| | 21 | `airmouse-customisation` | UI theme customisation, threshold adjustments, gesture re-mapping. | `theme`, `threshold`, `sensitivity` | | |
| | 22 | `airmouse-code-quality` | Linting (`lint_android`, `lint_go`), static code analysis, code formatting. | `lint`, `format`, `static analysis` | | |
| ### 5.2 Quality Rules (`rules/airmouse-standards.md`) | |
| - **Pure Math Implementations**: No external sensor fusion dependencies; pure Kotlin and pure Go math. | |
| - **Strict 3-Step Calibration**: Must enforce Gyro 100-sample, Mag 200-sample, Accel 6-position standards. | |
| - **Perfetto Completeness**: All 11 questions (Q1–Q11) must be answered with trace evidence prior to submission. | |
| - **Race Detection**: Go server tests must execute with `-race` flag enabled. | |
| - **Pre-Commit CI**: Always run `full_ci_pipeline` before committing code. | |
| - **Doc Sync**: Documentation files must be regenerated after code changes. | |
| ### 5.3 System Instructions (`instructions.md`) | |
| - **Tool-First Policy**: Prefer autonomous MCP tool calls over requesting manual user actions. | |
| - **Skill Consultation**: Consult `.agents/skills/` for domain workflows. | |
| - **Bilingual Support**: Default to English, but respond fluently in Persian (Farsi) when addressed in Persian. | |
| - **Destructive Confirmation**: Always confirm before executing clean or force-stop commands. | |
| ### 5.4 Dynamic Memory & Config Files | |
| - **`memory/project_state.json`**: Tracks build status (`android`, `go`), calibration check state, Perfetto status, and active server process. | |
| - **`memory/known_issues.json`**: Long-term memory of resolved bugs (e.g. `rad/s` double conversion fix) and tuning constants. | |
| - **`config.json`**: `{"model": "gemini-3.1-pro", "temperature": 0.15, "max_tokens": 16384, "strict_tool_use": true, "auto_load_skills": true}` | |
| - **`.env` & `.env.template`**: Sets `AIRMOUSE_PROJECT_ROOT`, `ANDROID_HOME`, `JAVA_HOME`, `GO_PATH`. | |
| --- | |
| ## 6. Extended 5-Lifecycle Agent Hook Engine | |
| Hooks are stored in `~/.gemini/config/hooks.json` and executed synchronously by the embedded Python engine in `airmouse_server_mcp.py`. | |
| ### 6.1 The 5 Lifecycle Events | |
| 1. **`pretool`** (PreToolUse): Triggered before an individual tool call executes. | |
| 2. **`posttool`** (PostToolUse): Triggered after an individual tool call completes. | |
| 3. **`preinvoke`** (PreInvocation): Triggered once at the start of an agent invocation request. | |
| 4. **`postinvoke`** (PostInvocation): Triggered once after an invocation request completes. | |
| 5. **`stop`** (Stop): Triggered when the server exits gracefully (`SIGINT`, `SIGTERM`, `atexit`). | |
| ### 6.2 CLI Hook Management Commands | |
| ```bash | |
| # List all configured hooks | |
| python airmouse_server_mcp.py hooks list | |
| # Add a pretool hook for a specific tool | |
| python airmouse_server_mcp.py hooks add --tool move_mouse --type pretool --command "echo 'Moving mouse: \$dx, \$dy'" | |
| # Add a global preinvoke hook | |
| python airmouse_server_mcp.py hooks add --type preinvoke --command "echo 'Session starting' >> ~/.gemini/logs/hooks.log" | |
| # Add a stop hook for process exit notification | |
| python airmouse_server_mcp.py hooks add --type stop --command "osascript -e 'display notification \"Server stopping\" with title \"AirMouse\"'" | |
| # Test / Remove / Clear | |
| python airmouse_server_mcp.py hooks test --tool move_mouse --type pretool --args '{"dx": 10, "dy": 20}' | |
| python airmouse_server_mcp.py hooks remove 1 | |
| python airmouse_server_mcp.py hooks clear | |
| ``` | |
| --- | |
| ## 7. Common Copy-Paste Workflows | |
| ### Workflow 1: Complete Build & CI Pipeline | |
| ```bash | |
| python airmouse_server_mcp.py full_ci_pipeline | |
| ``` | |
| ### Workflow 2: Execute 3-Step Calibration Sequence | |
| ```bash | |
| python airmouse_server_mcp.py calibration_launch_gyro_step | |
| python airmouse_server_mcp.py calibration_launch_mag_step | |
| python airmouse_server_mcp.py calibration_launch_accel_step | |
| python airmouse_server_mcp.py calibration_check_status | |
| ``` | |
| ### Workflow 3: Perfetto Trace Capture & Q1–Q11 Analysis | |
| ```bash | |
| python airmouse_server_mcp.py capture_perfetto_trace duration="10s" | |
| python airmouse_server_mcp.py run_perfetto_analyzer | |
| python airmouse_server_mcp.py generate_perfetto_report | |
| ``` | |
| ### Workflow 4: Full Protocol Validation & Documentation Sync | |
| ```bash | |
| python airmouse_server_mcp.py run_full_protocol_validation | |
| python airmouse_server_mcp.py generate_master_documentation | |
| python airmouse_server_mcp.py generate_test_report | |
| ``` | |
| ### Workflow 5: Generate Clean Final Submission ZIP | |
| ```bash | |
| python airmouse_server_mcp.py generate_submission_zip | |
| ``` | |
| --- | |
| ## 8. Environment Variables | |
| | Variable | Default Value / Path | Description | | |
| |---|---|---| | |
| | `AIRMOUSE_PROJECT_ROOT` | `~/Documents/uni/CPS/Files/ComputerAssignments/CA2` | Absolute path to the AirMouse project root. | | |
| | `ANDROID_HOME` | `/Users/tahamajs/Library/Android/sdk` | Path to Android SDK installation. | | |
| | `JAVA_HOME` | `/Library/Java/JavaVirtualMachines/.../Contents/Home` | Path to JDK installation. | | |
| | `GO_PATH` | `~/go` | Path to Go workspace directory. | | |
| | `HOOK_TYPE` | Injected dynamically (`pretool`, `preinvoke`, etc.) | Current active hook lifecycle event. | | |
| | `TOOL_NAME` | Injected dynamically (`move_mouse`, etc.) | Name of the tool currently executing. | | |
| | `ARGS` | Injected dynamically (JSON string) | Tool input parameters. | | |
| | `RESULT` | Injected dynamically (JSON string) | Tool execution result payload. | | |
| --- | |
| ## 9. Official Google Antigravity Documentation Links | |
| - 🏠 **Main Documentation Home**: https://antigravity.google/docs | |
| - ⚡ **Skills System**: https://antigravity.google/docs/skills | |
| - 📜 **Rules System**: https://antigravity.google/docs/rules | |
| - 🪝 **Hooks System**: https://antigravity.google/docs/hooks | |
| - 🧩 **Plugins Registry**: https://antigravity.google/docs/plugins | |
| - 🏎️ **Sidecars**: https://antigravity.google/docs/sidecars | |
| - 🔌 **Model Context Protocol (MCP)**: https://antigravity.google/docs/mcp | |
| - 🌐 **Browser Automation & Testing**: https://antigravity.google/docs/browser | |
| - 🛡️ **Agent Permissions & Security**: https://antigravity.google/docs/agent-permissions | |
| - 📜 **Changelog & Release Notes**: https://antigravity.google/changelog | |
| - 🆘 **Troubleshooting & Support**: https://antigravity.google/support | |
| --- | |
| ## 10. Quick Reference Card | |
| | Goal / Action | Command / Method | | |
| |---|---| | |
| | **Build Android Debug APK** | `python airmouse_server_mcp.py build_android_debug` | | |
| | **Build Native Go Server** | `python airmouse_server_mcp.py build_go_server` | | |
| | **Run Go Tests with Race Detector** | `python airmouse_server_mcp.py test_go_with_race` | | |
| | **Run Standalone Python TCP Test** | `python airmouse_server_mcp.py pc_run_test_pc_server` | | |
| | **Run E2E Integration Suite** | `python airmouse_server_mcp.py pc_run_e2e_python_test` | | |
| | **List Installed Hooks** | `python airmouse_server_mcp.py hooks list` | | |
| | **Reload Workspace Skills (TUI)** | `/skill reload` | | |
| | **List Active Skills (TUI)** | `/skill list` | | |
| | **Load Specific Skill (TUI)** | `/skill load airmouse-sensor-fusion` | | |
| | **Generate Submission Archive** | `python airmouse_server_mcp.py generate_submission_zip` | | |
| --- | |
| > [!NOTE] | |
| > **Status:** The AirMouse Pro CA2 project is 100% complete, fully tested, documented, and ready for submission! | |
Xet Storage Details
- Size:
- 20.5 kB
- Xet hash:
- a48b374687808595ce7cf61c8802aaee2b93e228602d76115f3d1326d8675ad8
·
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.