Documentation & Quickstart

1. What HawkeRun Does

HawkeRun is a durable supervisor daemon that manages AI and CLI agent execution loops on your local machine. Instead of running agents in a simple loop and hoping they don't crash or stall, HawkeRun uses a **leased task queue** (backed by SQLite in WAL mode) to enforce safety policies:

• Heartbeats & Watchdog: Kills and requeues any agent that freezes or goes silent for too long.
• Privacy-First: Keeps all source code, logs, and project contexts 100% local. It only calls home to verify subscription plans.
• Manager Approvals: Gathers approvals for sensitive actions (like deploying code) and relays them to your dashboard or your phone.

2. Installation

Download the build for your operating system from the account dashboard. HawkeRun runs on Windows, macOS, and Linux, and every build puts the hawke command line tool on your PATH.

3. Activate License

Copy your license key from your HawkeRun dashboard. Activate it in your terminal to unlock plan-specific limits (like additional concurrent workers and advanced adapters):

hawke license activate <your-license-key>

You can check the status of your local license cache at any time:

hawke license status

4. Add First Project & Configure

Run the interactive first-run wizard. It detects your AI tools (Claude Code, Codex, Ollama, etc.) and sets up neutral YAML configurations:

hawke init

During setup, the wizard will ask you to specify:

• Which directories to monitor.
• Which AI model workers are allowed to execute tasks.
• Your email address for decision notifications.

5. Start the Supervisor Service

To run the supervisor daemon seamlessly in the background (surviving user logouts and reboots), register it as a background service. hawke service install picks the right mechanism for your OS automatically: Task Scheduler on Windows, launchd on macOS, and systemd on Linux.

hawke service install hawke service start

Check the service status and dashboard:

hawke service status hawke dashboard

6. Trigger a Demo Task

To test the queue execution, drop an agent-task codeblock inside the target project's AGENTS.md file:

```agent-task
id: T-demo-1
title: Run build check
worker: shell
command: npm
args: ["run", "build"]
priority: 5
max_attempts: 3
```

The supervisor will instantly detect the new block, lock the task, start execution, and report progress back into the local dashboard timeline.