hawkeye-ai 0.2.0 → 0.3.0

package/README.md

@@ -1,389 +1,292 @@
-<h1 align="center">Hawkeye</h1>
-
-<p align="center">
-  <strong>The flight recorder for AI agents</strong><br/>
-  <sub>Open-source observability & security for Claude Code · Aider · AutoGPT · CrewAI · Open Interpreter · any LLM-powered agent</sub>
-</p>
-
-<p align="center">
-  <a href="https://www.npmjs.com/package/hawkeye-ai"><img src="https://img.shields.io/npm/v/hawkeye-ai?color=ff5f1f&label=npm" alt="npm version"></a>
-  <a href="https://github.com/MLaminekane/hawkeye/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="license"></a>
-  <a href="https://github.com/MLaminekane/hawkeye"><img src="https://img.shields.io/github/stars/MLaminekane/hawkeye?style=social" alt="GitHub stars"></a>
-</p>
-
-<p align="center">
-  <a href="#installation">Install</a> •
-  <a href="#quick-start">Quick Start</a> •
-  <a href="#features">Features</a> •
-  <a href="#cli-commands">CLI</a> •
-  <a href="#dashboard">Dashboard</a> •
-  <a href="#driftdetect">DriftDetect</a> •
-  <a href="#guardrails">Guardrails</a> •
-  <a href="#security">Security</a> •
-  <a href="#architecture">Architecture</a>
-</p>
-
----
-
-## What is Hawkeye?
-
-Hawkeye is a **flight recorder** for AI agents. It captures every action an agent performs — terminal commands, file operations, LLM calls, API requests — and provides:
-
-- **Session recording & replay** — Full timeline of every agent action with costs and metadata
-- **Time Travel Debugging** — Step-through replay with breakpoints, keyboard shortcuts, interactive SVG timeline, session forking ("replay from here")
-- **Root Cause Analysis** — Automatic `hawkeye analyze` finds primary errors, causal chains, error patterns, and fix suggestions (heuristic + optional LLM)
-- **DriftDetect** — Real-time objective drift detection using heuristic + LLM scoring
-- **Guardrails** — File protection, command blocking, cost limits, token limits, directory scoping, network lock, review gates
-- **Impact Preview** — Pre-execution risk analysis for every agent action (low/medium/high/critical)
-- **Live Firewall** — Real-time action stream with browser push notifications and badge counter
-- **Policy Engine** — Declarative `.hawkeye/policies.yml` for shareable, team-wide security rules
-- **Autonomous Control Layer** — Autocorrect engine that auto-rolls back files, pauses sessions, blocks failing patterns, and injects correction hints to agents via MCP
-- **Memory Diff** — Cross-session agent memory tracking, hallucination detection, cumulative knowledge view
-- **Live Agent Spawning** — Spawn, monitor, and control AI agents directly from the dashboard with role assignment, permission levels, and real-time session linking
-- **Multi-agent Orchestration (Swarm)** — Coordinate multiple AI agents on parallel tasks with isolated worktrees, scope enforcement, dependency ordering, conflict detection, and merge strategies
-- **Visual dashboard** — Mobile-responsive web UI with session explorer, drift charts, firewall, agents control room, memory viewer, and settings management
-- **Remote tasks** — Submit prompts from your phone via dashboard, with image attachments, auto-approve, and persistent agent memory
-- **Interactive TUI** — Terminal-responsive CLI with arrow-key navigation and slash commands
-- **OpenTelemetry export** — Push traces to Grafana Tempo, Jaeger, Datadog, Honeycomb
-- **Universal ingestion API** — Accept events from any source (MCP servers, custom tools)
-- **MCP server** — 38 tools for agent self-awareness, intelligence, and cross-session analysis
-- **Multi-agent support** — Claude Code (hooks), Aider, Open Interpreter, AutoGPT, CrewAI, Codex, or any custom command
-
-## Installation
-
-### npm (recommended)
-
-```bash
-npm install -g hawkeye-ai
+```text
+   ██╗  ██╗
+   ██║  ██║
+   ███████║  Hawkeye
+   ██╔══██║  The flight recorder for AI agents
+   ██║  ██║
+   ╚═╝  ╚═╝
 ```
 
-### npx (no install)
+# Hawkeye CLI
 
-```bash
-npx hawkeye-ai
-```
+`hawkeye-ai` turns any coding agent into something you can actually observe, debug, and trust.
 
-### Homebrew (macOS/Linux)
+If Claude Code, Codex, Cline, or a custom agent goes off-script, Hawkeye shows you:
 
-```bash
-brew install MLaminekane/hawkeye/hawkeye-ai
-```
+- what it did
+- which files it touched
+- what it cost
+- where it started drifting
+- which guardrail blocked it
+- how to replay or inspect the failure
 
-### Vercel Agent Skill
+This package is the fastest way to try Hawkeye locally: install it, wrap one agent run, then open the dashboard and see the whole session.
 
-Install as a skill for any AI coding agent (Claude Code, Cursor, Gemini CLI, GitHub Copilot, and 30+ more):
+## Why try Hawkeye?
 
-```bash
-npx skills add MLaminekane/hawkeye
-```
+Most agent workflows fail in annoying ways:
 
-### From source
+- the agent changed too many files and you do not know when it went wrong
+- the model burned credits without making progress
+- a dangerous command almost ran
+- a failure happened 8 steps after the actual mistake
+- you want to compare a good run with a bad one
 
-```bash
-git clone https://github.com/MLaminekane/hawkeye.git
-cd hawkeye
-pnpm install && pnpm build
-cd packages/cli && npm link
-```
+Hawkeye is built for that exact moment.
 
-## Quick Start
+It gives you:
 
-```bash
-# Initialize in your project
-hawkeye init
-
-# Record an agent session
-hawkeye record -o "Build a REST API" -- claude chat
+- session recording with cost, token, and action tracking
+- drift detection during the run
+- guardrails and policy enforcement
+- root-cause analysis after failures
+- replay, comparison, exports, and dashboard visibility
+- background automation through daemon, tasks, and MCP
 
-# Or launch the interactive TUI
-hawkeye
-```
+If you want the full product overview and repo-level architecture, see the root README. This file stays focused on the CLI package and how to get value from it quickly.
 
-## Features
+## Install
 
-### Session Recording
-
-Wrap any LLM-powered agent with `hawkeye record` to capture everything:
+### npm
 
 ```bash
-hawkeye record -o "Refactor auth module" -- claude chat
-hawkeye record -o "Fix bug #42" --agent cursor -- cursor .
-hawkeye record -o "Deploy to staging" --no-drift -- node deploy.js
+npm install -g hawkeye-ai
 ```
 
-Hawkeye automatically detects the agent (Claude Code, Aider, AutoGPT, CrewAI, Open Interpreter) and intercepts:
-
-| Interceptor    | What it captures                                       |
-| -------------- | ------------------------------------------------------ |
-| **Terminal**   | Commands executed, exit codes, stdout/stderr           |
-| **Filesystem** | File reads, writes, deletes, renames                   |
-| **Network**    | HTTP requests, LLM API calls with token counts & costs |
-
-### Claude Code Hooks
-
-For agents with bundled Node.js runtimes (where `NODE_OPTIONS` injection doesn't work), Hawkeye integrates via **Claude Code hooks**:
+### npx
 
 ```bash
-hawkeye hooks install           # Install PreToolUse + PostToolUse hooks
-hawkeye hooks install --guardrails-only  # Only install guardrail enforcement
-hawkeye hooks status            # Check installation
-hawkeye hooks uninstall         # Remove hooks
-```
-
-Hooks provide:
-
-- **PreToolUse** — Guardrails enforcement (exit code 2 blocks the action)
-- **PostToolUse** — Event recording to SQLite
-- **Stop** — Drift score update (fires after every response, does not end session)
-- Sessions auto-created per `session_id`
-
-### Interactive TUI
-
-Launch the interactive mode by running `hawkeye` with no subcommand:
-
+npx hawkeye-ai
 ```
-   ██╗  ██╗
-   ██║  ██║
-   ███████║  Hawkeye v0.1.0
-   ██╔══██║  The flight recorder for AI agents
-   ██║  ██║  /Users/you/project
-   ╚═╝  ╚═╝
 
-  ● Recording: "Build REST API" (5m 23s)
+### Homebrew
 
-  › /
+```bash
+brew install MLaminekane/hawkeye/hawkeye-ai
 ```
 
-Type `/` to open the command picker with arrow-key navigation and live filtering:
-
-| Command          | Description                                      |
-| ---------------- | ------------------------------------------------ |
-| `/active`        | Show current recording                           |
-| `/analyze`       | Root cause analysis — find why a session failed   |
-| `/approve`       | Approve pending review gate actions               |
-| `/attach`        | Launch agent on active session                    |
-| `/autocorrect`   | Autonomous control — auto-correct agent behavior  |
-| `/clear`         | Clear screen                                      |
-| `/compare`       | Compare sessions side by side                     |
-| `/delete`        | Delete a session                                  |
-| `/end`           | End active sessions                               |
-| `/export`        | Export session as JSON                             |
-| `/firewall`      | Show recent interceptions & impact previews        |
-| `/init`          | Initialize Hawkeye                                |
-| `/inspect`       | Detailed session inspection                       |
-| `/kill`          | Kill hawkeye background processes                 |
-| `/mcp`           | Show MCP server setup instructions                |
-| `/memory`        | Memory diff — agent memory across sessions         |
-| `/new`           | New session (pick agent + objective)               |
-| `/overnight`     | Run overnight mode (guardrails + morning report)   |
-| `/policy`        | Manage security policies (init/check/show)         |
-| `/purge`         | Delete ALL sessions (including old)                |
-| `/quit`          | Exit                                               |
-| `/remote`        | Launch serve + daemon + Cloudflare tunnel          |
-| `/remote stop`   | Stop tunnel + daemon                               |
-| `/replay`        | Replay a session (interactive)                     |
-| `/report`        | Generate morning report                            |
-| `/restart`       | Restart a session                                  |
-| `/revert`        | Revert file changes from a session                 |
-| `/serve`         | Open dashboard on :4242                            |
-| `/sessions`      | List & manage sessions                             |
-| `/settings`      | Configure DriftDetect, Guardrails, API keys        |
-| `/stats`         | Session or global statistics                       |
-| `/swarm`         | Multi-agent orchestration — list/show/init swarms  |
-| `/tasks`         | List & submit remote tasks                         |
-| `/watch`         | Live event stream (tail -f style)                  |
-
-## CLI Commands
-
-### `hawkeye analyze <session-id>`
+### From source
 
 ```bash
-hawkeye analyze <session-id>          # Heuristic root cause analysis
-hawkeye analyze <session-id> --llm    # Enhanced with LLM analysis
-hawkeye analyze <session-id> --json   # Machine-readable output
+git clone https://github.com/MLaminekane/hawkeye.git
+cd hawkeye
+pnpm install
+pnpm build
+cd packages/cli
+npm link
 ```
 
-Automatic root cause analysis: identifies the primary error, builds the causal chain, detects error patterns, analyzes drift trajectory, and generates fix suggestions.
-
-### `hawkeye approve`
-
-Approve pending review gate actions from the CLI.
+## Quick Start
 
-### `hawkeye autocorrect`
+Try it in under a minute:
 
 ```bash
-hawkeye autocorrect enable [--dry-run]  # Enable autonomous correction
-hawkeye autocorrect disable             # Disable autocorrect
-hawkeye autocorrect status              # Show current status and config
-hawkeye autocorrect history             # View past corrections
+hawkeye init
+hawkeye record -o "Review this repo and suggest improvements" -- claude
+hawkeye serve
 ```
 
-Autonomous control layer — Hawkeye doesn't just observe, it autonomously corrects agent behavior when drift, errors, or cost issues are detected. Actions include file rollback, session pause, hint injection to MCP-aware agents, and pattern blocking.
+Then open `http://localhost:4242`.
 
-### `hawkeye compare <id1> <id2>`
+You will immediately get:
+
+- the recorded session timeline
+- files touched
+- drift and cost tracking
+- session stats and replay tools
+
+If you mainly use Claude Code, install hooks once and Hawkeye can capture Claude Code sessions automatically:
 
 ```bash
-hawkeye compare <session1> <session2>
+hawkeye hooks install
 ```
 
-Compare two sessions side by side — stats, drift, cost, tokens, and actions.
-
-### `hawkeye daemon`
+If you prefer the terminal-first workflow, open the built-in TUI:
 
 ```bash
-hawkeye daemon [--agent claude] [--interval 30]
+hawkeye
 ```
 
-Run the task daemon — polls `.hawkeye/tasks.json` for pending tasks and executes them. Features:
+## The First 3 Workflows To Try
 
-- **Persistent memory**: writes a task journal (`.hawkeye/task-journal.md`) after each task
-- **Conversation continuity**: uses `claude --continue` within 30-min windows
-- **Context injection**: enriches prompts with git status, recent commits, and task history
-- Works with any agent CLI, not just Claude
+### 1. Record a session
 
-### `hawkeye end`
+Wrap any agent command with `hawkeye record`:
 
 ```bash
-hawkeye end [-s <session-id>] [--all] [--status completed|aborted]
+hawkeye record -o "Fix flaky tests" -- codex
+hawkeye record -o "Review recent changes" -- claude
+hawkeye record -o "Investigate bug 142" -- node ./scripts/agent.js
 ```
 
-### `hawkeye export`
+This is the fastest way to understand Hawkeye. One command gives you:
 
-```bash
-hawkeye export <session-id> [-f json|html] [-o report.html]
-```
+- terminal commands and exit codes
+- file reads and writes
+- LLM calls, token usage, and cost
+- drift updates
+- guardrail violations
 
-### `hawkeye hooks`
+### 2. Open the dashboard
 
 ```bash
-hawkeye hooks install [--local] [--guardrails-only]
-hawkeye hooks uninstall [--local]
-hawkeye hooks status
+hawkeye serve
 ```
 
-### `hawkeye init`
+The dashboard is where Hawkeye clicks for most people:
 
-Initialize Hawkeye in the current directory. Creates `.hawkeye/` directory and config files.
+- sessions list
+- session detail and replay
+- compare view
+- firewall
+- tasks
+- agents control room
 
-### `hawkeye inspect <session-id>`
+It is the easiest way to feel the product value fast.
 
-Detailed session inspection — shows events, cost per file, drift snapshots, and guardrail violations.
+### 3. Inspect a real session
 
-### `hawkeye mcp`
-
-Start the MCP (Model Context Protocol) server over stdio. Agents connect automatically.
+Once you have one recorded run, try:
 
 ```bash
-hawkeye mcp [--db <path>]
+hawkeye sessions
+hawkeye inspect <session-id>
+hawkeye analyze <session-id>
+hawkeye replay <session-id>
 ```
 
-### `hawkeye memory`
+That is usually the moment where Hawkeye stops feeling like “extra logging” and starts feeling like a debugger for agent behavior.
 
-```bash
-hawkeye memory [session]              # Extract memories from a session
-hawkeye memory diff <s1> <s2>         # Compare what agent remembers between sessions
-hawkeye memory cumulative             # Aggregate knowledge across all sessions
-hawkeye memory hallucinations         # Detect contradictions and recurring errors
-```
+## Core Workflows
 
-Cross-session agent memory tracking. Extracts structured knowledge (file patterns, error lessons, tool patterns, decisions) from session events, compares what agents learned/forgot across sessions, and detects hallucinations.
+### Claude Code hooks
 
-### `hawkeye otel-export`
+For Claude Code, Hawkeye integrates through hooks instead of `NODE_OPTIONS` injection:
 
 ```bash
-hawkeye otel-export <session-id> [-o traces.json]
-hawkeye otel-export <session-id> --endpoint https://tempo.example.com/v1/traces
-```
-
-Export as OTLP JSON traces. Compatible with Grafana Tempo, Jaeger, Datadog, Honeycomb.
-
-### `hawkeye overnight`
-
-```bash
-hawkeye overnight [--budget 5] [--agent claude] [--task "prompt"] [--tunnel] [--port 4242] [--report-llm]
+hawkeye hooks install
+hawkeye hooks install --guardrails-only
+hawkeye hooks status
+hawkeye hooks uninstall
 ```
 
-Run overnight mode — composes serve + daemon with strict guardrails for unattended agent runs:
+Hooks enable:
 
-- **Auto-applies guardrails**: cost limit (from `--budget`), file protection for secrets, command blocking, auto-pause on critical drift
-- **Backs up config** before modifying and restores on shutdown
-- **Optional tunnel**: `--tunnel` starts a Cloudflare tunnel for remote monitoring
-- **Optional task**: `--task "..."` queues an initial task for the daemon
-- **Morning report on Ctrl+C**: generates consolidated report of all sessions, fires `overnight_report` webhook
+- synchronous guardrail enforcement before tool use
+- event capture after tool use
+- automatic session creation for Claude Code sessions
 
-| Option          | Description                               | Default  |
-| --------------- | ----------------------------------------- | -------- |
-| `--budget`      | Maximum cost budget in USD                | `5`      |
-| `--agent`       | Agent CLI command                         | `claude` |
-| `--task`        | Submit initial task to daemon queue       |          |
-| `--tunnel`      | Enable Cloudflare tunnel for remote access|          |
-| `--port`        | Dashboard port                            | `4242`   |
-| `--report-llm`  | Run LLM post-mortem per session on shutdown|         |
+### Inspect what happened
 
-### `hawkeye policy`
+Common inspection commands:
 
 ```bash
-hawkeye policy init [--force]      # Generate default policies.yml (or convert existing guardrails)
-hawkeye policy check               # Validate policies.yml
-hawkeye policy show                # Display current policies
-hawkeye policy export [-o file]    # Export guardrails as YAML
-hawkeye policy import <file>       # Import a policies.yml
+hawkeye sessions
+hawkeye stats
+hawkeye inspect <session-id>
+hawkeye analyze <session-id>
+hawkeye compare <id-a> <id-b>
+hawkeye replay <session-id>
 ```
 
-Declarative security policies in `.hawkeye/policies.yml` — shareable across projects and teams. The hook-handler automatically loads and merges policy rules with config.json guardrails.
-
-### `hawkeye record`
+Useful exports:
 
 ```bash
-hawkeye record -o <objective> [options] -- <command...>
+hawkeye export <session-id> -f json
+hawkeye export <session-id> -f html -o report.html
+hawkeye otel-export <session-id> -o traces.json
 ```
 
-| Option            | Description                             |
-| ----------------- | --------------------------------------- |
-| `-o, --objective` | Session objective **(required)**        |
-| `-a, --agent`     | Agent name (auto-detected from command) |
-| `-m, --model`     | Model name                              |
-| `--no-drift`      | Disable DriftDetect                     |
-| `--no-guardrails` | Disable guardrails                      |
-
-### `hawkeye replay <session-id>`
+### Run the dashboard and automation
 
 ```bash
-hawkeye replay <session-id> [--speed 2] [--no-delay]
+hawkeye serve
+hawkeye daemon
+hawkeye overnight --budget 5 --task "review the repo"
 ```
 
-Replay a session action-by-action with timing.
+This is the setup to use if you want:
 
-### `hawkeye report`
+- remote task submission
+- persistent task execution
+- unattended guarded runs
+- dashboard visibility while agents work
 
-```bash
-hawkeye report [--since <iso>] [--json] [--llm] [--webhook]
-```
+### Connect agents through MCP
 
-Generate a morning report of recent sessions. Aggregates stats, drift, errors, and cost per session.
-
-| Option      | Description                                                    | Default                              |
-| ----------- | -------------------------------------------------------------- | ------------------------------------ |
-| `--since`   | Report on sessions since this ISO timestamp                    | `overnight.json` startedAt or 8h ago |
-| `--json`    | Output as JSON                                                 |                                      |
-| `--llm`     | Include LLM-powered post-mortem per session                    |                                      |
-| `--webhook` | Fire `overnight_report` webhook with the report                |                                      |
+```bash
+hawkeye mcp
+```
+
+The MCP server exposes Hawkeye tools for session introspection, drift checks, memory analysis, and corrective workflows.
+
+## Command Guide
+
+### Main commands
+
+| Command | Purpose |
+| --- | --- |
+| `hawkeye init` | Initialize `.hawkeye/` in the current project |
+| `hawkeye record` | Record an agent session |
+| `hawkeye hooks` | Install or manage Claude Code hooks |
+| `hawkeye serve` | Start the dashboard |
+| `hawkeye daemon` | Run the task daemon |
+| `hawkeye mcp` | Start the MCP server |
+| `hawkeye sessions` | List recorded sessions |
+| `hawkeye inspect` | Show detailed session data |
+| `hawkeye analyze` | Run root-cause analysis |
+| `hawkeye compare` | Compare two or more sessions |
+| `hawkeye replay` | Replay a session timeline |
+| `hawkeye report` | Generate a recent session report |
+| `hawkeye export` | Export a session report |
+| `hawkeye policy` | Manage `.hawkeye/policies.yml` |
+| `hawkeye autocorrect` | Configure autonomous correction |
+| `hawkeye memory` | Compare or aggregate agent memory |
+| `hawkeye ci` | Post a session report to GitHub PRs |
+| `hawkeye overnight` | Run guarded unattended workflows |
+| `hawkeye swarm` | Run multi-agent orchestration |
+| `hawkeye restart` | Restart a session with inherited context |
+| `hawkeye revert` | Revert file changes from a session |
+| `hawkeye approve` | Approve pending review-gate actions |
+| `hawkeye end` | End active recording sessions |
+| `hawkeye stats` | Show stats for one session or globally |
+
+### Interactive mode
+
+Running `hawkeye` with no subcommand opens the terminal UI.
+
+That mode is great if you want Hawkeye to feel more like a daily control surface than a long list of commands. It is the fastest way to:
+
+- start a new session
+- browse sessions
+- launch the dashboard
+- inspect stats
+- manage settings and policies
+
+## Key Commands
 
-### `hawkeye restart`
+### `hawkeye record`
 
 ```bash
-hawkeye restart [session-id] [-o <objective>] [-a <agent>] [-m <model>]
+hawkeye record -o <objective> [options] -- <command...>
 ```
 
-Restart a session — inherits objective, agent, and model from the original if not overridden. Interactive picker when no ID is given.
+Common options:
 
-### `hawkeye revert`
+| Option | Meaning |
+| --- | --- |
+| `-o, --objective` | Required session objective |
+| `-a, --agent` | Override agent name |
+| `-m, --model` | Override model name |
+| `--no-drift` | Disable DriftDetect |
+| `--no-guardrails` | Disable guardrails |
 
-```bash
-hawkeye revert <session-id> <file-path>
-```
+Good use cases:
 
-Revert a file to its pre-session state using git.
+- wrap a single risky run
+- compare two agent strategies on the same task
+- capture a bug reproduction or failed refactor
+- audit what an agent actually did
 
 ### `hawkeye serve`
 
@@ -391,496 +294,133 @@ Revert a file to its pre-session state using git.
 hawkeye serve [-p 4242]
 ```
 
-Launch the web dashboard on `http://localhost:4242`. Auto-reloads after `pnpm build` — watches `dist/` and restarts the server when compiled files change.
+Starts the dashboard locally, usually at `http://localhost:4242`.
 
-### `hawkeye sessions`
+Use this when you want visual monitoring, replay, compare, firewall, tasks, or agent orchestration.
+
+### `hawkeye daemon`
 
 ```bash
-hawkeye sessions [-n 10] [-s recording|completed|aborted]
+hawkeye daemon [--agent claude] [--interval 30]
 ```
 
-### `hawkeye stats <session-id>`
+Runs the background task worker that processes queued dashboard tasks and maintains task memory.
 
-Display statistics for a session (accepts ID prefix).
+Use this if you want Hawkeye to keep working even when the dashboard tab is closed.
 
-### `hawkeye swarm`
+### `hawkeye mcp`
 
 ```bash
-hawkeye swarm <config.json>           # Run multi-agent orchestration from config
-hawkeye swarm init                    # Generate a template swarm config
-hawkeye swarm list                    # List past swarm runs
+hawkeye mcp [--db <path>]
 ```
 
-Coordinate multiple AI agents on parallel tasks. Each agent gets an isolated git worktree with enforced scope boundaries. Features dependency ordering (topological sort), file conflict detection, sequential/octopus merge strategies, and live terminal progress.
+Starts the Hawkeye MCP server over stdio.
 
-Add to `.mcp.json` at project root for Claude Code:
+Use this when you want agents to query Hawkeye directly for session stats, drift, memory, or historical context.
+
+Example `.mcp.json`:
 
 ```json
 {
   "mcpServers": {
     "hawkeye": {
-      "command": "node",
-      "args": ["path/to/hawkeye/packages/cli/dist/index.js", "mcp"]
+      "command": "hawkeye",
+      "args": ["mcp"]
     }
   }
 }
 ```
 
-**38 tools** for agent self-awareness, intelligence, and control:
-
-| Category | Tools |
-|----------|-------|
-| **Observability** (9) | `list_sessions`, `get_session`, `get_session_events`, `get_session_drift`, `get_session_stats`, `get_global_stats`, `compare_sessions`, `get_violations`, `get_cost_by_file` |
-| **Self-awareness** (8) | `check_drift`, `get_objective`, `check_cost`, `check_guardrail`, `check_progress`, `log_event`, `list_changes`, `get_config` |
-| **Intelligence** (8) | `get_session_timeline`, `get_error_summary`, `suggest_correction`, `analyze_root_cause`, `post_mortem`, `memory_diff`, `check_memory`, `auto_correct` |
-| **Actions** (5) | `end_session`, `pause_session`, `resume_session`, `set_objective`, `get_correction` |
-| **Cross-session** (2) | `search_events`, `revert_file` |
-| **Swarm** (3) | `list_swarms`, `get_swarm`, `get_swarm_agent` |
-
-## Dashboard
-
-The web dashboard (`hawkeye serve`) is fully **mobile responsive** and provides:
-
-### Sessions Page
-
-- List all sessions with status filtering (recording / completed / aborted)
-- Search by objective or agent name
-- Auto-refresh every 5 seconds, module-level cache (no flash on page change)
-- Shows costs, drift scores, action counts
-
-### Session Detail Page
-
-- **Time Travel Debugger** — Interactive SVG timeline with step-through, breakpoints, keyboard shortcuts, and session forking
-- **Drift score chart** — Line chart with warning/critical reference zones
-- **Event timeline** — Filterable, searchable list with type badges (CMD, FILE, LLM, GUARD, etc.)
-- **Expandable details** — Full event payload for each action, auto-expands during step-through
-- **Live mode** — Auto-refreshes every 3 seconds for active sessions
-- **Export** — Download session as JSON
-
-### Tasks Page (Remote)
-
-- Submit prompts remotely from your phone
-- **Image attachments** — Upload photos to include with prompts
-- **Auto-approve toggle** — Automatically approve all guardrail-blocked actions
-- **Approve/Deny buttons** — Manually review dangerous actions
-- **Agent memory** — View/clear the persistent task journal
-- Status tracking: pending, running, completed, failed
-
-### Agents Control Room
-
-- **Spawn agents** directly from the dashboard — choose agent CLI (claude, aider, codex), assign role (lead/worker/reviewer), set permissions (full access/supervised/default), add personality
-- **Live monitoring** — Real-time output streaming, session linking with drift/cost/action stats, follow-up messages
-- **Permission levels** — Full access (skip confirmation prompts), supervised (Hawkeye guardrails enforce limits), default (agent runtime defaults)
-- **Persistent agents** — Agents survive server restarts via file-backed persistence (`.hawkeye/agents.json`)
-- **Session integration** — Each spawned agent is automatically linked to its Hawkeye session for full observability
-
-### Compare Page
-
-- Select two sessions to compare side by side
-- Stats comparison (actions, cost, tokens, drift)
-
-### Memory Page
-
-- **Cumulative Memory** — Aggregate knowledge across all sessions (file patterns, error lessons, tool patterns, decisions)
-- **Memory Diff** — Compare what an agent remembered between two sessions (learned, forgotten, retained, evolved, contradicted)
-- **Hallucination Detection** — Cross-session analysis for recurring errors and contradicted facts
-
-### Swarm Page
-
-- List and detail view of multi-agent orchestration runs
-- Agent cards with scope display, files changed, merge status
-- Conflict visualization between agents
-- Real-time WebSocket updates during execution
-
-### Firewall Page
-
-- **Live action stream** — Every agent action in real-time with risk classification
-- **Filters** — All / Risky Only / Blocked / Writes / Commands
-- **Browser notifications** — Push alerts when actions are blocked or critical
-- **Navbar badge** — Red counter for high/critical actions
-
-### Settings Page
-
-- Configure DriftDetect (provider, model, thresholds, check frequency)
-- Manage guardrail rules (enable/disable, toggle warn/block)
-- **Policy Engine** — Initialize, edit, and manage `.hawkeye/policies.yml` with full CRUD for rules
-- Provider model selection with live lookup
-
-### REST API
-
-| Endpoint                          | Method | Description                      |
-| --------------------------------- | ------ | -------------------------------- |
-| `/api/sessions`                   | GET    | List sessions                    |
-| `/api/sessions/:id`               | GET    | Session details                  |
-| `/api/sessions/:id/events`        | GET    | Session events                   |
-| `/api/sessions/:id/drift`         | GET    | Drift snapshots                  |
-| `/api/sessions/:id/cost-by-file`  | GET    | Cost breakdown by file           |
-| `/api/sessions/:id/end`           | POST   | End a session                    |
-| `/api/sessions/:id/pause`         | POST   | Pause a session                  |
-| `/api/sessions/:id/resume`        | POST   | Resume a paused session          |
-| `/api/sessions/:id/fork`          | POST   | Fork session up to event N       |
-| `/api/sessions/:id/analyze`       | GET    | Root cause analysis              |
-| `/api/compare?ids=id1,id2`        | GET    | Compare sessions side by side    |
-| `/api/stats`                      | GET    | Global statistics                |
-| `/api/settings`                   | GET    | Get configuration                |
-| `/api/settings`                   | POST   | Save configuration (Zod-validated) |
-| `/api/providers`                  | GET    | Available LLM providers & models |
-| `/api/ingest`                     | POST   | Universal event ingestion (Zod-validated) |
-| `/api/revert`                     | POST   | Revert a file change             |
-| `/api/tasks`                      | GET    | List remote tasks                |
-| `/api/tasks`                      | POST   | Create a task (with attachments) |
-| `/api/tasks/:id/cancel`           | POST   | Cancel a pending task            |
-| `/api/tasks/journal`              | GET    | Read agent memory journal        |
-| `/api/tasks/journal/clear`        | POST   | Clear agent memory               |
-| `/api/tasks/attachments/:file`    | GET    | Serve task image attachments     |
-| `/api/pending-reviews`            | GET    | List pending review gate items   |
-| `/api/review-approve`             | POST   | Approve a review gate item       |
-| `/api/review-deny`                | POST   | Deny a review gate item          |
-| `/api/policies`                   | GET    | Get current policies.yml         |
-| `/api/policies`                   | POST   | Save policies (server-validated) |
-| `/api/impact`                     | GET    | Last impact preview              |
-| `/api/interceptions`              | GET    | Recent blocks + pending reviews  |
-| `/api/sessions/:id/memory`        | GET    | Session memory items             |
-| `/api/sessions/:id/corrections`   | GET    | Session autocorrect history      |
-| `/api/memory/diff?a=X&b=Y`       | GET    | Memory diff between sessions     |
-| `/api/memory/cumulative`          | GET    | Cumulative memory across sessions|
-| `/api/memory/hallucinations`      | GET    | Cross-session hallucination check|
-| `/api/corrections`                | GET    | All corrections across sessions  |
-| `/api/active-correction`          | GET    | Current active correction hint   |
-| `/api/autocorrect`                | POST   | Trigger/configure autocorrect    |
-| `/api/agents`                     | GET    | List live agents                 |
-| `/api/agents/spawn`               | POST   | Spawn a new agent                |
-| `/api/agents/:id`                 | GET    | Get agent details                |
-| `/api/agents/:id/stop`            | POST   | Stop a running agent             |
-| `/api/agents/:id/remove`          | POST   | Remove an agent                  |
-| `/api/agents/:id/message`         | POST   | Send follow-up message to agent  |
-| `/api/agents/:id/events`          | GET    | Get agent's session events       |
-| `/api/swarms`                     | GET    | List swarm runs                  |
-| `/api/swarms/:id`                 | GET    | Swarm details                    |
-| `/api/swarms/:id/agents`          | GET    | Swarm agent details              |
-| `/api/swarms/:id/conflicts`       | GET    | Swarm file conflicts             |
-
-## DriftDetect
-
-DriftDetect monitors agent behavior in real-time and assigns a **drift score** (0–100):
-
-| Score  | Status      | Meaning                           |
-| ------ | ----------- | --------------------------------- |
-| 70–100 | ✅ OK       | Agent is on track                 |
-| 40–69  | ⚠️ Warning  | Possible deviation from objective |
-| 0–39   | 🔴 Critical | Significant drift detected        |
-
-### Scoring Engines
-
-**Heuristic scorer** (always active, zero-cost):
-
-- Penalizes dangerous commands (`rm -rf`, `DROP TABLE`, `curl | bash`)
-- Flags suspicious paths (`/etc`, `~/.ssh`, `/root`)
-- Detects sensitive file extensions (`.pem`, `.key`, `.env`)
-- Monitors error rates
-
-**LLM scorer** (optional, configurable):
-
-- Evaluates actions against the stated objective using an LLM
-- Supports 6 providers:
-
-| Provider  | Models                                                                                               |
-| --------- | ---------------------------------------------------------------------------------------------------- |
-| Ollama    | llama4, llama3.2, mistral, codellama, deepseek-coder, phi3                                           |
-| Anthropic | claude-sonnet-4-6, claude-opus-4-6, claude-haiku-4-5, claude-sonnet-4-5, claude-opus-4-5             |
-| OpenAI    | gpt-4o, gpt-4o-mini, gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, gpt-5, gpt-5-mini, o3, o3-mini, o4-mini    |
-| DeepSeek  | deepseek-chat, deepseek-reasoner                                                                     |
-| Mistral   | mistral-large-latest, mistral-medium-latest, mistral-small-latest, codestral-latest, devstral-latest |
-| Google    | gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite, gemini-2.0-flash                            |
-
-## Guardrails
-
-Guardrails are evaluated **synchronously before** events are persisted. Violations can `warn` (log only) or `block` (prevent the action).
-
-| Rule Type         | Description                            | Config                                |
-| ----------------- | -------------------------------------- | ------------------------------------- |
-| `file_protect`    | Protect files/dirs from modification   | `paths: string[]` (glob patterns)     |
-| `command_block`   | Block dangerous commands               | `patterns: string[]` (regex patterns) |
-| `cost_limit`      | Limit spending per session/hour        | `maxUsdPerSession`, `maxUsdPerHour`   |
-| `token_limit`     | Limit token consumption                | `maxTokensPerSession`                 |
-| `directory_scope` | Restrict agent to specific directories | `allowedDirs`, `blockedDirs`          |
-| `network_lock`    | Allow/block specific API hostnames     | `allowedHosts`, `blockedHosts`        |
-| `review_gate`     | Require human approval for commands    | `patterns: string[]` (regex patterns) |
-| `impact_threshold`| Block actions above a risk level       | `blockAbove`, `warnAbove` (low/medium/high/critical) |
-
-### Time Travel Debugging
-
-The dashboard session replay is a full debugger for AI agent sessions:
-
-- **Step-through controls** — Step forward/back one event at a time, play/pause with speed controls (1x–10x)
-- **Breakpoints** — Click events on the interactive SVG timeline or press `B` to toggle breakpoints; playback pauses automatically at breakpoints
-- **Interactive timeline** — Color-coded dots by event type, drift score overlay, right-click context menu
-- **Session forking** — "Fork from here" creates a new session from any point in time, copying all events, drift snapshots, and guardrail violations up to that point
-- **Keyboard shortcuts** — `←`/`→` step through, `Space` play/pause, `B` toggle breakpoint
-- **Auto-expand** — Current event details expand automatically during step-through
-
-### Root Cause Analysis
-
-After a session fails, run `hawkeye analyze <session>` (or click "Analyze" in the dashboard) to get:
-
-- **Primary error** — The main failure event with context
-- **Causal chain** — Backwards trace: which file edits and LLM decisions led to the error
-- **Error patterns** — Repeated failures grouped and counted (e.g., "tsc failed 5x")
-- **Drift analysis** — Score trend, inflection point, and what triggered the drift
-- **Suggestions** — Actionable fix recommendations based on detected patterns
-- **LLM enhancement** — Add `--llm` for deeper natural language analysis
+### `hawkeye policy`
 
+```bash
+hawkeye policy init
+hawkeye policy check
+hawkeye policy show
+hawkeye policy export
+hawkeye policy import <file>
 ```
-$ hawkeye analyze abc123
 
- ─── Root Cause Analysis ─── session abc12345
+Use this when you want declarative, shareable guardrail rules in `.hawkeye/policies.yml`.
 
-  FAILURE   confidence: high
+## Who this is for
 
-  SUMMARY
-  Session failed due to repeated TypeScript compilation errors
+Hawkeye is a strong fit if you:
 
-  PRIMARY ERROR (event #47)
-  tsc --noEmit → exit 1
-  at 14:23:05 — command
+- run AI coding agents on real repos
+- care about cost visibility
+- want safer automation
+- need post-mortems when runs go wrong
+- want a shared observability layer across multiple agent runtimes
 
-  CAUSAL CHAIN
-  #12 ◇ LLM    anthropic/claude-3.5-sonnet
-  #15 ● FILE   Modified src/middleware.ts
-  #23 ○ CMD    tsc --noEmit → exit 1
+It is especially useful once you move beyond toy prompts and start trusting agents with actual code, CI, secrets, or long-running tasks.
 
-  SUGGESTIONS
-  1. TypeScript compilation failed 5 times — fix type errors
-  2. Agent made multiple unsuccessful attempts
-```
+### `hawkeye overnight`
 
-### Impact Preview
-
-Every agent action is analyzed **before execution** via the Impact Preview engine:
-
-- Computes risk level (low/medium/high/critical) based on command patterns, file sensitivity, git status
-- Shows affected files, lines, and git tracking status in the terminal
-- Blocks critical-risk actions automatically (configurable via `impact_threshold` policy rule)
-- Dashboard Firewall page shows all actions in real-time with browser push notifications
-
-### Policy Engine
-
-Declarative policies in `.hawkeye/policies.yml` are shareable, version-controllable, and team-wide:
-
-```yaml
-version: "1"
-name: my-project
-rules:
-  - name: protect-secrets
-    type: file_protect
-    enabled: true
-    action: block
-    config:
-      paths: [".env", "*.pem", "*.key"]
-  - name: block-high-impact
-    type: impact_threshold
-    enabled: true
-    action: block
-    config:
-      blockAbove: critical
-      warnAbove: high
+```bash
+hawkeye overnight [--budget 5] [--agent claude] [--task "prompt"] [--tunnel]
 ```
 
-Manage via `hawkeye policy` CLI, dashboard Settings page, or direct YAML edit.
-
-### Autonomous Control Layer (Autocorrect)
-
-Hawkeye doesn't just observe — it autonomously corrects agent behavior:
-
-- **Triggers**: critical drift (< 30), declining drift trend, repeated error patterns (configurable, default 3x), cost exceeding budget threshold (85%)
-- **Actions**: file rollback (`git checkout -- <file>`), session pause, hint injection to MCP-aware agents, dynamic pattern blocking, webhook notifications
-- **Agent integration**: MCP-aware agents (Claude Code, Cursor) receive correction hints via `get_correction` tool with direct `agentInstructions`
-- **Dry-run mode**: test corrections without executing them
-
-### Memory Diff
-
-Cross-session agent memory tracking and hallucination detection:
-
-- **7-phase extraction**: file knowledge, error lessons, corrections, tool patterns, decisions, dependency facts, API knowledge
-- **Diff analysis**: learned (new), forgotten (lost), retained, evolved (updated), contradicted (conflicting)
-- **Hallucination detection**: recurring errors across sessions, contradicted facts
-- **Cumulative memory**: aggregated knowledge across all sessions with deduplication
+Useful for unattended runs with:
 
-### Multi-agent Orchestration (Swarm)
-
-Coordinate multiple AI agents on parallel tasks:
-
-- **Isolated worktrees**: each agent gets its own git worktree — no conflicts during execution
-- **Scope enforcement**: include/exclude glob patterns, enforced at prompt-level and validated post-execution
-- **Dependency ordering**: topological sort (Kahn's algorithm) for task dependencies
-- **Conflict detection**: file overlap detection between agents with severity scoring
-- **Merge strategies**: sequential (least-conflict-first) or octopus
-- **Config-driven**: JSON config files with agent personas, tasks, scopes, and timeouts
-
-### Live Agent Spawning
-
-Spawn and control AI agents directly from the dashboard:
-
-- **Role-based creation**: assign roles (lead/worker/reviewer) and custom personality
-- **Permission levels**: full access (`--dangerously-skip-permissions`), supervised (Hawkeye guardrails), or default
-- **Session linking**: automatic detection and linking to Hawkeye sessions for full observability
-- **Live stats**: real-time drift score, cost, action count, and session info via WebSocket
-- **Follow-up messages**: send additional prompts to running agents via stdin
-- **Persistence**: agents survive server restarts via `.hawkeye/agents.json`
-
-Example configuration (via `/settings` in TUI or dashboard):
-
-```json
-{
-  "guardrails": [
-    {
-      "name": "Protect secrets",
-      "type": "file_protect",
-      "enabled": true,
-      "action": "block",
-      "config": { "paths": ["**/.env", "**/*.key", "**/*.pem"] }
-    },
-    {
-      "name": "No destructive commands",
-      "type": "command_block",
-      "enabled": true,
-      "action": "block",
-      "config": { "patterns": ["rm\\s+-rf\\s+/", "DROP\\s+TABLE", "curl.*\\|.*bash"] }
-    },
-    {
-      "name": "Budget limit",
-      "type": "cost_limit",
-      "enabled": true,
-      "action": "warn",
-      "config": { "maxUsdPerSession": 5.0, "maxUsdPerHour": 2.0 }
-    }
-  ]
-}
-```
+- budget enforcement
+- stricter guardrails
+- optional remote monitoring
+- morning report generation on shutdown
 
 ## Configuration
 
-Configuration is stored at `.hawkeye/config.json`:
+Project config lives in:
 
-```json
-{
-  "drift": {
-    "enabled": true,
-    "checkEvery": 5,
-    "provider": "ollama",
-    "model": "llama3.2",
-    "warningThreshold": 60,
-    "criticalThreshold": 30,
-    "contextWindow": 10
-  },
-  "guardrails": [],
-  "apiKeys": {
-    "anthropic": "sk-ant-...",
-    "openai": "sk-..."
-  }
-}
+```text
+.hawkeye/config.json
 ```
 
-Manage settings via:
-
-- **TUI**: `/settings` command with interactive sub-menus
-- **Dashboard**: Settings page at `http://localhost:4242/settings`
-- **Direct edit**: `.hawkeye/config.json`
+Typical sections:
 
-## Security
+- `drift`
+- `guardrails`
+- `apiKeys`
+- provider-specific settings such as LM Studio URL
 
-Hawkeye is designed to run locally. The dashboard server binds to `localhost` and includes multiple security layers:
+You can manage config through:
 
-| Protection | Description |
-|---|---|
-| **CORS** | Only `localhost` / `127.0.0.1` origins accepted |
-| **WebSocket origin check** | Upgrade requests from cross-origin pages are rejected |
-| **POST body limit** | 5 MB max — oversized requests are destroyed (prevents DoS) |
-| **Path traversal** | Static file serving and attachment endpoints verify resolved paths stay within their root |
-| **No command injection** | All git operations use `execFile()` with argument arrays, never shell strings |
-| **Config file permissions** | `.hawkeye/config.json` and `policies.yml` written with `0o600` (owner-only) to protect API keys |
-| **Policy validation** | `POST /api/policies` validates schema before writing — rejects invalid rules |
-| **Impact analysis** | Pre-execution risk scoring blocks critical actions before they run |
-| **Concurrent write safety** | Hook handler uses exclusive lockfile for `hook-sessions.json` writes |
+- the TUI
+- the dashboard Settings page
+- direct file edits
 
-### API Keys
+## What this package includes
 
-API keys for LLM providers (Anthropic, OpenAI, etc.) are stored in `.hawkeye/config.json`. The file is created with restricted permissions (`0o600`), but you should also add `.hawkeye/` to your global `.gitignore` to avoid accidental commits.
+This package ships:
 
-## Architecture
+- the `hawkeye` executable
+- the bundled dashboard assets used by `hawkeye serve`
+- the CLI command set and interactive TUI
 
-TypeScript monorepo using **pnpm workspaces** + **Turborepo**:
-
-```
-packages/
-├── core/        Node.js SDK — recorder, interceptors, storage, DriftDetect, guardrails
-├── cli/         CLI (Commander.js + chalk) — commands, interactive TUI
-└── dashboard/   React 19 + Vite + Tailwind CSS + Recharts — web UI
-```
-
-### Data Flow
-
-```
-Agent ──► Interceptors ──► Recorder ──► Guardrails (sync) ──► SQLite
-                                            │
-                                            └──► DriftDetect (async)
-```
-
-### Network Interception
-
-For child processes, Hawkeye injects a preload ESM script via `NODE_OPTIONS="--import ..."` that monkey-patches `http/https.request` and `globalThis.fetch`. It detects LLM API calls by hostname and path, parses SSE streaming responses, and sends captured events back to the parent via Node.js IPC.
-
-### Storage
-
-SQLite via `better-sqlite3` with WAL mode. Nine tables:
-
-| Table                  | Purpose                                                       |
-| ---------------------- | ------------------------------------------------------------- |
-| `sessions`             | Session metadata (objective, agent, status, timestamps)       |
-| `events`               | Captured events (type, data, timestamps, token counts, costs) |
-| `drift_snapshots`      | Drift score history per session                               |
-| `guardrail_violations` | Guardrail violation log                                       |
-| `memory_items`         | Cross-session agent memory (knowledge, patterns, lessons)     |
-| `corrections`          | Autocorrect actions (rollbacks, pauses, hints, blocks)        |
-| `swarms`               | Swarm orchestration run metadata                              |
-| `swarm_agents`         | Per-agent state within swarm runs                             |
-| `swarm_conflicts`      | File conflicts detected between swarm agents                  |
+This is the package to install if you want to actually use Hawkeye, not just browse the repo.
 
 ## Development
 
+From the repo root:
+
 ```bash
-pnpm install                           # Install all dependencies
-pnpm build                             # Production build (all packages)
-pnpm dev                               # Dev mode (Turborepo watch)
-pnpm test                              # Run all tests (Vitest)
-pnpm --filter @hawkeye/core test       # Run only core tests
-pnpm --filter @hawkeye/cli build       # Build only CLI
+pnpm install
+pnpm build
+pnpm test
+pnpm --filter hawkeye-ai build
+pnpm --filter hawkeye-ai test
 ```
 
-### Requirements
-
-- Node.js ≥ 20
-- pnpm 9.x
-
-### Tech Stack
-
-| Package              | Stack                                  |
-| -------------------- | -------------------------------------- |
-| `@hawkeye/core`      | TypeScript, better-sqlite3, Vitest     |
-| `@hawkeye/cli`       | TypeScript, Commander.js, chalk v5     |
-| `@hawkeye/dashboard` | React 19, Vite, Tailwind CSS, Recharts |
-
-### Code Conventions
+Requirements:
 
-- TypeScript strict mode, ES2022 target, ESM modules
-- File names in kebab-case
-- Named exports only (no default exports except React components)
-- `Result<T, E>` pattern for error handling (no throwing in core)
-- Prettier: semi, singleQuote, trailingComma: all, printWidth: 100
+- Node.js 20+
+- pnpm 9+
 
-## Acknowledgments
+## Notes
 
-Special thanks to **Lamine** for their contributions and support.
+- `packages/cli/README.md` is the package README for `hawkeye-ai`.
+- The root README should stay product-level.
+- This file should stay CLI-focused and avoid duplicating the entire repository handbook.
 
 ## License