Docs

Eagle Eye reads one JSON feed and redraws every 5 seconds. Install it, run it on the demo feed, then write a feed from your own agents.

Install

One line. It downloads Eagle Eye into ./eagle-eye and serves the demo on http://localhost:8000.

curl -fsSL eagleeye.sh/install | sh

Running it again updates the app files and keeps your config.js. Options, as environment variables:

EAGLE_EYE_DIR=path     where to install            (default: ./eagle-eye)
EAGLE_EYE_PORT=8000    port for the local server   (default: 8000)
EAGLE_EYE_REF=main     branch or tag to install    (default: main)
EAGLE_EYE_NO_SERVE=1   install only, do not start the server

By hand

No build, no dependencies, no account.

git clone https://github.com/utopia-models/eagle-eye && cd eagle-eye
python3 -m http.server 8000      # or: npx serve .
# open http://localhost:8000

Everything you see first comes from demo/data.json, which is made-up sample data. Every campaign, person and step has its own page at /campaigns.html, fed by demo/campaigns.json (also made up). The same demo runs at eagleeye.sh/demo.

Hunts and roosts

Each agent gets a lane on the eye. What it sent out sits on the outer ring; what came back sits on the inner ring.

  • Hunts (ring 0): applications, proposals, cold email, posts. Each hunt shows what was sent and what was answered.
  • Roosts (ring 1): replies, clients, your network. Each roost shows its rows.

It fits whatever screen it is on, with no scroll bar: a phone, a laptop, a 1080p wall, an ultrawide, or half of a desk. At every size hunts and roosts sit side by side on top, and the eye takes the room below them.

Agents feed adapters, adapters write a JSON feed, Eagle Eye draws it

Plug in your agents

Give each agent a lane. Have it append one row per action to a CSV ledger, or write the feed JSON directly.

  1. Write a feed in the feed shape. The reference adapter turns a CSV ledger (one row per application or status change) into a feed.
  2. Point feed in config.js at it, and name your lanes in pipes.
  3. Re-run the adapter on a schedule: cron, a systemd timer, a serverless function. The page picks up changes within 5 seconds, with no reload.
# ledger.csv, one row per action, in time order
ts,lane,org,role,status
2026-11-02 10:00,job_boards,Northwind,Backend engineer,applied
2026-11-05 16:20,job_boards,Northwind,Backend engineer,interview

python3 adapters/csv_feed.py ledger.csv > data.json
python3 adapters/csv_feed.py --self-test

Statuses the adapter counts: found, applied, replied, screen, interview, offer, signed, rejected (a rejection counts as a reply). Any adapter that writes the same JSON works: a CRM export, an ATS API, an inbox count. Source: adapters/csv_feed.py.

Feed format

Eagle Eye polls one JSON document every 5 seconds. Anything that can write this shape can drive the screen: a cron job, a serverless function, a database view.

{
  "updated": "2026-11-15T09:00:00Z",          // when your adapter measured it
  // funnel totals: every key named in config.js `stages` and `key4`
  "applied": 214, "replied": 31, "interviews": 7, "offers": 2,
  "hunts": {                                   // one entry per ring-0 lane, keyed by `hk`
    "job_boards": {
      "sent": 214,                             // what you sent out (outer ring)
      "answered": 31,                          // what came back (inner ring)
      "status": "live",                        // live | partial | empty
      "reason": "...",                         // shown instead of numbers when empty
      "window": "last 30 days", "what": "...", "source": "...",
      "last_action": {"ts": "2026-11-15T08:41:00Z", "event": "applied"}
    }
  },
  "roosts": {                                  // one entry per ring-1 lane, keyed by `rk`
    "clients": {
      "rows": [{"name": "Northwind Labs", "hunt": "referrals",
                "stage": "contract", "contracts": 1, "paid": "$4,800"}],
      "reason": "..."                          // shown when rows is empty
    }
  }
}

Rules the UI keeps, so your adapter should too

  • Never send a zero you did not count. A lane you cannot measure gets "sent": null, "status": "empty" and a reason; the screen shows the reason, dimmed, instead of a fake 0.
  • A failed measurement writes nothing. Keep the last good document rather than replacing it with an empty one.

config.js

Everything in config.js is optional except a feed and at least one lane.

window.EAGLE_EYE = {
  feed: 'demo/data.json',   // any URL that returns the feed JSON
  // ring 0 = a hunt, read from feed.hunts[hk]
  // ring 1 = a roost, read from feed.roosts[rk].rows
  // w = the lane's share of its ring
  pipes: [
    {id:'job-boards', ring:0, hk:'job_boards', name:'Job boards', w:3},
    {id:'cold-email', ring:0, hk:'cold_email', name:'Cold email', w:2},
    {id:'clients',    ring:1, rk:'clients',    name:'Clients',    w:1},
  ],
};

The full file, with funnel stages and per-lane links: config.js on GitHub.

Check the layout

Six sizes in three browsers. It fails on any overlap, anything off screen, or a scroll bar.

npm i && npx playwright install chromium webkit firefox
python3 -m http.server 8000 &
npm run check

Licensed under the MIT License. Questions and fixes: GitHub issues.