Your smart AI parrot helper/geek — an intelligent desktop companion that watches what you do, learns your patterns, and proactively helps with repetitive tasks.

Like a clever parrot, Ghost observes your behavior silently and pops up with suggestions: "Hey, I noticed you copy-paste customer info every morning — want me to automate that?" It's more than just recording/replaying inputs; it's an active assistant that understands your workflow and offers help before you even ask.

ghost/
├── src/                    # Tauri app frontend (desktop application)
├── public/                 # Marketing website (ghost.muharafiq.com)
├── src-tauri/             # Rust backend
└── .github/workflows/     # CI/CD pipelines

Important: Both src/ and public/ contain identical HTML/CSS/JS files:

• src/ is used by the Tauri desktop app
• public/ is deployed to the marketing website
• Keep both directories synchronized when making UI changes

See DEPLOYMENT.md for detailed deployment instructions.

Ghost is your smart AI parrot — an intelligent assistant that:

• Observes your desktop activity silently, learning your unique patterns
• Learns what workflows you repeat and when you do them
• Assists proactively with "Hey, I noticed you..." style suggestions
• Automates repetitive tasks so you can focus on what matters

It sits on top of macOS Accessibility (and Windows UIA) to understand your clicks, keystrokes, and workflow intent — then turns those actions into reliable automations.

1. Observe — Your parrot silently watches your desktop activity, learning your unique patterns
2. Learn — It builds understanding of your intent and recognizes when you repeat actions
3. Assist — Pops up with proactive suggestions: "Hey, I noticed you ___"

• Frontend (src/) — plain vanilla HTML/CSS/JS, no bundler. The UI for recording and replaying lives here and talks to Rust over Tauri IPC. Also serves as the static marketing site when deployed to Vercel or Netlify, featuring the smart AI parrot demo.
• Backend (src-tauri/) — Rust. The platform-specific integration:
  • macOS — src-tauri/src/platform/macos.rs: CGEventTap for recording, AXUIElement for element lookup, enigo for replay.
  • Windows — src-tauri/src/platform/windows.rs: Win32 hooks for recording, UIA for element lookup, enigo for replay.
  • Engine — src-tauri/src/engine.rs: Platform-agnostic orchestration with atomic cancellation support.

The marketing website is hosted at ghost.muharafiq.com and serves the public/ directory. Download links automatically point to the latest GitHub Release assets.

Build a distributable .app / .dmg (macOS) or .exe / .msi (Windows):

cargo tauri build

• macOS or Windows
• Rust (stable)
• Tauri CLI — cargo install tauri-cli

cargo tauri dev          # run the app (Vite-less; serves src/ directly)

Or work with the backend directly:

cd src-tauri
cargo check              # fast type-check
cargo clippy             # lint
cargo build --release    # build the library

Ghost needs System Settings → Privacy & Security → Accessibility enabled for the app to watch and replay clicks. On first run, click Grant Access in the UI.

Heads up: in cargo tauri dev the dev binary path changes between rebuilds, so macOS may re-prompt or drop the permission. A stable build from cargo tauri build is more reliable for testing real recording.

• core/events.rs — Shared event schema: InputEvent, ElementInfo, KeyAction
• core/traits.rs — Platform-agnostic traits: InputRecorder, ElementLocator, ReplayEngine
• engine.rs — GhostEngine orchestrates backends with thread-safe mpsc channels
• platform/macos.rs — macOS implementation using CGEventTap, AXUIElement, enigo
• platform/windows.rs — Windows implementation using Win32 hooks, UIA, enigo
• commands.rs — Tauri 2 IPC handlers with mpsc→Tauri bridge emitting ghost:event

1. Frontend calls start_recording() via Tauri IPC
2. Engine spawns native recorder (CGEventTap/Win32 hook) on background thread
3. Native events flow through mpsc channel → bridge thread → app.emit("ghost:event", payload)
4. Frontend receives events via listen("ghost:event", callback)
5. Replay uses enigo with AtomicBool cancellation for instant stop

All Phase 4 features are now in production on master:

• Platform-agnostic engine foundation (Phase 0)
• Full macOS backend: CGEventTap, AXUIElement, enigo replay with speed control
• Full Windows backend: Win32 hooks, UIA, enigo replay with speed control
• Thread-safe mpsc bridge with atomic cancellation
• Marketing site with Vercel/Netlify deployment
• Interactive recording controls in frontend
• Workflow save/load functionality
• Playback speed control (0.1x - 2.0x+)
• Pause/resume replay functionality
• AI-powered workflow analysis and optimization
• Workflow naming suggestions using pattern detection
• Reliability replay with configurable retry and backoff strategies
• Cloud sync capabilities with authentication
• Workspace management for team collaboration
• Enterprise audit logging for compliance
• Accessibility permission handling (check/request)
• Real-time event timeline visualization
• Smart AI Parrot UI - Interactive parrot avatar with typing animation, clickable to see proactive suggestions
• Marketing site - Shows both macOS and Windows support with app mockup
• Phase 4A: Visual Regression - Visual checkpoints during replay with SSIM comparison, baseline capture, mismatch handling
• Phase 4B: Smart Observer Mode - Watches/learns patterns, proactive suggestions, pattern detection
• Phase 4C: Data-Driven Testing - CSV/JSON/Environment data sources, template resolution
• Phase 4D: Geek Mode Insights - Technical performance metrics, event timing analysis for power users
• Phase 5: Execution & Analytics - Execution history tracking, workflow analytics
• Capture what was clicked (AX element role/title) with full attribute extraction
• Keyboard modifier tracking and character mapping
• Scroll event phase handling
• Cross-platform desktop deployment
• Phase 6.1: Observability wiring - Opt-in usage telemetry and performance monitoring, gated by privacy/performance config flags (get_telemetry_stats, export_telemetry, get_performance_summary)

Telemetry and performance monitoring are opt-in and disabled by default. They activate only when privacy.telemetry_enabled / performance.profiling_enabled are set in config, and collect nothing otherwise.