Hawkeye

🦅 The First Proactive AI Assistant for Desktop

AI that enhances your story. Watch keenly. Act thoughtfully. 10x your productivity.

⌘ + ⇧ + H to observe your screen instantly

🌐 Website · 📖 Documentation · 🐛 Report Bug · 💡 Request Feature

---

🎯 What is Hawkeye?

Traditional AI waits for your commands. Hawkeye watches and helps proactively.

Hawkeye is an AI-powered desktop assistant that observes your work environment—screen, clipboard, files—and proactively offers intelligent suggestions. No prompts needed.

The AI behind Hawkeye is designed to enhance your own story — turning your screen time into meaningful personal growth by automatically mapping your goals, habits, and progress into a living Life Tree.

Feature	Copilot / Cursor / Claude Code	Hawkeye
Mode	Reactive (you ask)	Proactive (it watches)
Scope	Code only	Everything: coding, browsing, writing
Privacy	Cloud-based	Local-first, your data stays local
Control	AI executes	You decide what to execute

✨ Key Features

🔍 Zero-Prompt Intelligence Automatically understands your context No need to explain what you're doing Suggests actions before you ask	🏠 Privacy-First Architecture All perception runs 100% locally Data never leaves your device Works offline with local LLMs
🎯 Smart Task Tracking Identifies your main task goal Generates actionable next steps Learns from your workflow	🔗 Multi-Platform Sync Desktop ↔ Browser seamless sync VS Code extension integration Cross-app workflow automation
🌳 Life Tree — AI Enhances Your Story Automatically maps your activities into life stages, goals, and tasks Proposes micro-experiments to optimize your habits and workflows Graduated experiment phases: task → goal → automation Your AI companion that turns screen time into personal growth

🚀 Quick Start

Download

Platform	Download
	Apple Silicon (.dmg) · Intel (.dmg)
	Installer (.exe)
	Debian/Ubuntu (.deb) · AppImage

⚠️ macOS: "App is damaged" fix

# Remove quarantine attribute
xattr -cr /Applications/Hawkeye.app

Setup in 60 Seconds

# 1. Clone
git clone https://github.com/tensorboy/hawkeye.git && cd hawkeye

# 2. Install
pnpm install

# 3. Run
pnpm dev

Configure AI Provider

Option 1: Google Gemini (Recommended — free tier)

1. Get a free API key at aistudio.google.com/apikey
2. Enter your key in Settings → Gemini API Key
3. Model defaults to gemini-2.0-flash (1M context window)

Option 2: OpenAI-Compatible API

Works with OpenAI, DeepSeek, Groq, Together AI, or any OpenAI-compatible endpoint.

Set your base URL, API key, and model name in Settings.

Option 3: Local LLM with node-llama-cpp (100% Offline)

Download a GGUF model and set the model path in Settings. Supports Metal GPU acceleration on macOS.

Recommended models:

• Qwen 2.5 7B — general purpose (4.7 GB)
• Llama 3.2 3B — lightweight (2.0 GB)
• LLaVA 1.6 7B — vision support (4.5 GB)

Option 4: Ollama (Legacy)

brew install ollama && ollama pull qwen3:8b

Select "Ollama" in Hawkeye settings.

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        HAWKEYE ENGINE                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐         │
│  │  PERCEPTION │───▶│  REASONING  │───▶│  EXECUTION  │         │
│  │   Engine    │    │   Engine    │    │   Engine    │         │
│  └─────────────┘    └─────────────┘    └─────────────┘         │
│        │                  │                  │                  │
│   • Screen OCR      • Claude/Ollama     • Shell Commands       │
│   • Clipboard       • Task Analysis     • File Operations      │
│   • File Watch      • Intent Detect     • App Control          │
│   • Window Track    • Suggestions       • Browser Auto         │
│                                                                 │
├─────────────────────────────────────────────────────────────────┤
│                         INTERFACES                              │
├───────────────┬───────────────┬───────────────┬─────────────────┤
│   🖥️ Desktop   │  🧩 VS Code    │  🌐 Chrome     │    📦 Core      │
│   (Electron)  │  Extension    │  Extension    │    (npm pkg)    │
└───────────────┴───────────────┴───────────────┴─────────────────┘

📦 Project Structure

hawkeye/
├── packages/
│   ├── core/                 # 🧠 Core engine (local processing)
│   │   ├── perception/       #    Screen, clipboard, file monitoring
│   │   ├── ai/               #    AI providers (Claude, Ollama, etc.)
│   │   ├── execution/        #    Action execution system
│   │   └── storage/          #    Local database (SQLite)
│   │
│   ├── desktop/              # 🖥️  Electron desktop app
│   ├── vscode-extension/     # 🧩 VS Code extension
│   └── chrome-extension/     # 🌐 Chrome browser extension
│
├── docs/                     # 📖 Documentation
└── website/                  # 🌐 Marketing site

🔒 Privacy & Security

Aspect	How We Protect You
Screenshots	✅ Analyzed locally, never uploaded
Clipboard	✅ Processed on-device only
Files	✅ Monitored locally, paths never sent
AI Calls	✅ Only minimal context text sent (or use local LLM)
Dangerous Ops	✅ Always requires your confirmation

📁 All data stored in ~/.hawkeye/ — you own your data.

📖 Usage Examples

As a Library

import { HawkeyeEngine } from '@hawkeye/core';

const engine = new HawkeyeEngine({
  provider: 'ollama',
  model: 'qwen3:8b'
});

// Get AI-powered suggestions based on current context
const suggestions = await engine.observe();

// Execute a suggestion with user confirmation
await engine.execute(suggestions[0].id);

File Watcher

import { FileWatcher } from '@hawkeye/core';

const watcher = new FileWatcher({
  paths: ['~/Downloads', '~/Documents'],
  events: ['create', 'move']
});

watcher.on('change', (event) => {
  console.log(`${event.type}: ${event.path}`);
});

🛡️ Advanced Features

Exponential Backoff Retry

AI provider calls use exponential backoff with jitter to handle transient failures gracefully, preventing thundering herd effects.

SQLite FTS5 Full-Text Search

Context history (window titles, clipboard, OCR text) is indexed with SQLite FTS5 for instant fuzzy search across all recorded observations.

Adaptive Refresh Rate

The observation interval adjusts dynamically based on user activity — fast polling when active, slow polling when idle — saving CPU and battery.

Priority Task Queue

A priority-based task queue with deduplication ensures that AI requests and plan executions are processed efficiently without duplicate work.

MCP Server Tools

Hawkeye exposes 15+ tools via MCP (Model Context Protocol) for screen perception, window management, file organization, and automation.

Safety Guardrails

An agent monitor enforces cost limits, blocks dangerous operations (e.g. rm -rf /), requires confirmation for risky actions, and supports a sandbox mode.

Menu Bar Panel

A macOS-style popover panel accessible from the system tray provides quick actions, recent activity feed, and real-time module status indicators.

Provider Unified Protocol

All AI providers declare their capabilities (chat, vision, streaming, function calling), enabling intelligent routing and health monitoring across providers.

🗺️ Roadmap

• Core perception engine
• Desktop app (Electron)
• VS Code extension
• Chrome extension
• Local LLM support (Ollama, node-llama-cpp)
• Multi-provider AI (Gemini, OpenAI-compatible, LlamaCpp)
• Provider unified protocol with capability routing
• Streaming and health check support
• SQLite FTS5 full-text search
• Exponential backoff retry strategy
• Adaptive refresh rate
• Priority task queue
• MCP Server with 15+ tools
• Safety guardrails and agent monitoring
• Menu bar panel (macOS-style popover)
• Life Tree — AI maps your life journey and enhances your story
• Desktop ↔ Extension real-time sync
• Plugin system
• Custom workflow builder
• Mobile companion app

🤝 Contributing

Contributions are what make the open source community amazing! Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

⭐ Star History

📄 License

Distributed under the MIT License. See LICENSE for more information.

☕ Support

If you find Hawkeye useful, consider buying me a coffee!

---

🌐 Website · 📖 Docs · 🐦 Twitter · 💬 Discord

_{Built with ❤️ by the Hawkeye Team}

If Hawkeye helps you, please consider giving it a ⭐