tahamajs's picture
download
raw
28.6 kB
<!DOCTYPE html>
<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 &amp; 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 &amp; System Guide
โ”œโ”€โ”€ AGENT.md # Architecture blueprint &amp; math models
โ”œโ”€โ”€ HOOKS.md # CLI &amp; 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 &amp; 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 &amp; Testing Tools
โ”‚ โ”œโ”€โ”€ airmouse_mcp_go/ # Go Native Server source &amp; 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 &amp; docs links
โ”œโ”€โ”€ README.md # Workspace hub README
โ”œโ”€โ”€ memory/
โ”‚ โ”œโ”€โ”€ known_issues.json # Resolved bugs &amp; tuning memory
โ”‚ โ””โ”€โ”€ project_state.json # Dynamic build &amp; server state
โ”œโ”€โ”€ rules/
โ”‚ โ””โ”€โ”€ airmouse-standards.md # Development &amp; 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 &amp; 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>$&gt; 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>$&lt; 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>$&gt; 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>$&gt; 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 &amp; command socket.</td>
</tr>
<tr>
<td><code>WebSocket Port</code></td>
<td><code>9091</code></td>
<td>Networking</td>
<td>Browser &amp; 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 &lt;tool_name&gt; [args...]</code>
- <strong>MCP Stdio Mode</strong>: <code>python airmouse_server_mcp.py</code> (FastMCP stdio JSON-RPC interface)</p>
<h3>Primary Tool Categories &amp; 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 &amp; 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 ($&gt;8.0\text{ rad/s}$), Accel Y scroll ($&gt;8.0\text{ m/s}^2$), Roll tilt right-click ($&gt;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 &amp; 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> &amp; <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 &quot;echo 'Moving mouse: \$dx, \$dy'&quot;
# Add a global preinvoke hook
python airmouse_server_mcp.py hooks add --type preinvoke --command &quot;echo 'Session starting' &gt;&gt; ~/.gemini/logs/hooks.log&quot;
# Add a stop hook for process exit notification
python airmouse_server_mcp.py hooks add --type stop --command &quot;osascript -e 'display notification \&quot;Server stopping\&quot; with title \&quot;AirMouse\&quot;'&quot;
# Test / Remove / Clear
python airmouse_server_mcp.py hooks test --tool move_mouse --type pretool --args '{&quot;dx&quot;: 10, &quot;dy&quot;: 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 &amp; 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 &amp; Q1โ€“Q11 Analysis</h3>
<pre><code class="language-bash">python airmouse_server_mcp.py capture_perfetto_trace duration=&quot;10s&quot;
python airmouse_server_mcp.py run_perfetto_analyzer
python airmouse_server_mcp.py generate_perfetto_report
</code></pre>
<h3>Workflow 4: Full Protocol Validation &amp; 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 &amp; Testing</strong>: https://antigravity.google/docs/browser</li>
<li>๐Ÿ›ก๏ธ <strong>Agent Permissions &amp; Security</strong>: https://antigravity.google/docs/agent-permissions</li>
<li>๐Ÿ“œ <strong>Changelog &amp; Release Notes</strong>: https://antigravity.google/changelog</li>
<li>๐Ÿ†˜ <strong>Troubleshooting &amp; 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.