flights-overhead

SKILL.md

---
name: "flights-overhead"
description: "See what flights are above you right now. Identify contrails, planes overhead, and nearby air traffic using OpenSky Network (free, no key)."
---

# Flights Overhead Skill

See what flights are currently above you. Identify contrails, planes overhead, and nearby air traffic using OpenSky Network (free, no API key needed).

## When to Use

- "What flights are above me right now?"
- "What plane is that?"
- "What's that contrail?"
- "What flights are near me?"
- "What's flying overhead?"
- Any query about identifying aircraft in the sky

## Requirements

- **OpenSky Network** — free, no API key, no account needed
- **Python 3** (standard library only)
- **User's location** — lat/lng (from device location or ask the user)
- Script: `scripts/flights_overhead.py`

## Privacy & Data Disclosure

- **OpenSky Network**: Your approximate location (lat/lng bounding box) is sent as query parameters to OpenSky's public API to retrieve nearby aircraft. No account or personal data is transmitted beyond coordinates.
- **Location source**: The agent should confirm or ask for the user's location rather than silently using stored addresses. An approximate location (city-level) is usually sufficient for overhead flight queries.
- No data is stored externally.

## Script Usage

```bash
# Show flights within 50 km (default)
python3 scripts/flights_overhead.py --lat 47.68 --lng -122.21

# Smaller radius, JSON output
python3 scripts/flights_overhead.py --lat 47.68 --lng -122.21 --radius 30 --json

# Limit results
python3 scripts/flights_overhead.py --lat 47.68 --lng -122.21 --limit 5 --json
```

### Parameters

| Flag | Required | Default | Description |
|------|----------|---------|-------------|
| `--lat` | Yes | — | Observer latitude |
| `--lng` | Yes | — | Observer longitude |
| `--radius` | No | 50 | Search radius in km |
| `--limit` | No | 20 | Max flights to return |
| `--json` | No | — | Output as JSON |

### Output (JSON)

```json
{
  "count": 8,
  "flights": [
    {
      "callsign": "ASA640",
      "airline": "Alaska Airlines",
      "flight_number": "AS640",
      "lat": 47.65,
      "lng": -122.30,
      "altitude_ft": 4875,
      "altitude_m": 1486,
      "speed_kmh": 464.9,
      "heading": 355,
      "vertical_rate_ms": -5.2,
      "distance_km": 8.2,
      "origin_country": "United States"
    }
  ]
}
```

### Key Fields

| Field | Description |
|-------|-------------|
| `callsign` | ICAO callsign (e.g. ASA640) |
| `airline` | Resolved airline name (if recognized) |
| `flight_number` | IATA flight number (e.g. AS640) |
| `altitude_ft` | Altitude in feet |
| `speed_kmh` | Ground speed |
| `heading` | Direction of travel (degrees, 0=north) |
| `distance_km` | Distance from observer |
| `vertical_rate_ms` | Climb/descent rate (negative = descending) |

## Procedure

### Step 1: Determine User Location

Options (in priority order):
1. **Device location** (preferred for mobile users) — use `nodes` → `location_get`. Requires user to have granted location permission on their paired device. Best option when the user may be away from home.
2. **Home address** from USER.md — convert to lat/lng. Use as fallback when device location is unavailable or user is known to be at home.
3. **Ask the user** — if neither is available.

**Note:** Device location requires explicit user permission on the paired mobile device. If not granted, the call will fail — fall back to option 2 or 3. For mobile users who are frequently away from home, device location gives accurate results. For stationary/home use, the address from USER.md is sufficient.

### Step 2: Query Flights

```bash
python3 scripts/flights_overhead.py --lat <lat> --lng <lng> --radius 30 --json
```

Use radius 5 km for "what's over me" / "what's that plane" (actually audible/visible).
Use radius 30 km for "what's that contrail" (high altitude, visible far away).
Use radius 20 km for "what flights are near me" or general area queries.

### Step 3: Look Up Routes

For identified commercial flights, look up origin/destination:

```bash
# Web search for flight route
web_search "<airline> <flight_number> flight route origin destination today"
```

FlightAware (`flightaware.com/live/flight/<ICAO_CALLSIGN>`) and FlightStats typically show the route. Extract origin → destination from the search snippet.

Skip route lookup for:
- Private/GA aircraft (registration numbers like N262BS)
- If the user just wants a quick count, not details

### Step 4: Present Results

**For "what's that contrail?" or "what plane is that?":**
- Filter to high-altitude flights (>25,000 ft for contrails)
- Show closest match with airline, flight number, altitude, heading
- Mention where it's likely going based on heading

**For "what flights are above me?":**
- Show all flights sorted by distance
- Group by airline if many results
- Mention total count

**For identifying a specific plane:**
- Ask for any details (direction it's heading, approximate altitude, size)
- Filter results to match

### Step 4: Enrich (Optional)

If user wants more info about a specific flight:
- Use `flight_tracker.py` to get route (origin/destination) if callsign is known
- Mention approximate aircraft type from origin_country + airline

## Example Responses

**"What flights are above me?"**
> Right now within 30 km of Kirkland, I can see 8 flights:
> - AS640 (Alaska Airlines) at 4,875 ft, 8 km away, heading north
> - DL2980 (Delta) at 3,850 ft, 9 km away, heading south
> - WN1713 (Southwest) at 7,000 ft, 7 km away, heading north
> ...
> Mostly arrivals/departures from SEA-TAC.

**"What's that contrail heading east?"**
> That's likely UA2271 (United Airlines) at 35,000 ft, heading 208° (southwest). It's about 13 km from you.

## Data Source

- **OpenSky Network** — community-run ADS-B network, free, no key needed
- Rate limit: 1 request per 10 seconds (anonymous)
- Coverage: Excellent over US/Europe, good globally except remote oceans
- Delay: ~5-15 seconds behind real-time

## Supported Airlines

The script recognizes 40+ airlines by ICAO callsign prefix and resolves them to human-readable names and IATA flight numbers. Unrecognized callsigns display as-is (often private/cargo aircraft with registration numbers like N262BS).

## Notes

- Contrails typically form above 25,000 ft in cold air — filter by altitude for contrail queries
- Aircraft on the ground are automatically excluded
- Results sorted by distance from observer (closest first)
- Heading 0°/360° = north, 90° = east, 180° = south, 270° = west
- Private/GA aircraft show registration numbers (e.g. N262BS) without airline info