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