HUB
Sign inSign up

psyb0t/planesnitch

By psyb0t

β€’Updated 10 days ago

Snitches on every interesting aircraft that dares fly near your locations: military jets, governm...

Image
0

10K+

psyb0t/planesnitch repository overview

Source⁠ | Project page⁠

β πŸ›©οΈ planesnitch

CI version license Docker Pulls

Snitches on every interesting aircraft that dares fly near your locations: military jets, government spooks, emergency squawks, sketchy low-flyers, or whatever the fuck you tell it to watch for. Monitor multiple locations at once: your house, your office, grandma's house, Area 51, whatever. Rats them out straight to your Telegram or webhook like a paranoid neighbor with radar.

No SDR required. No antenna. No hardware. Just an internet connection and a config file. Works anywhere on the fuckin planet, for as many places as you want.

⁠Contents

β πŸš€ Quick start

Grab the example config and put in your location and Telegram bot:

curl -sL \
  https://raw.githubusercontent.com/psyb0t/docker-planesnitch/main/config.yaml.example \
  -o config.yaml

The example also watches military, government and police aircraft from plane-alert-db⁠. Grab those lists:

mkdir -p csv
BASE=https://raw.githubusercontent.com/sdr-enthusiasts/plane-alert-db/main
for list in mil gov pol civ pia; do
  curl -sLo "csv/plane-alert-$list.csv" "$BASE/plane-alert-$list.csv"
done
curl -sLo csv/plane-alert-db.csv "$BASE/plane-alert-db.csv"

Let it rip:

docker run -d --name planesnitch \
  --restart unless-stopped \
  -v ./config.yaml:/app/config.yaml:ro \
  -v ./csv:/csv:ro \
  -v ./images:/images \
  psyb0t/planesnitch
2026-03-07 22:25:39 [planesnitch] INFO planesnitch starting
2026-03-07 22:25:39 [planesnitch] INFO health endpoint listening on :8080
2026-03-07 22:25:40 [planesnitch] INFO watchlist military: 8709 aircraft loaded
2026-03-07 22:25:40 [planesnitch] INFO fetched 14 aircraft
2026-03-07 22:25:40 [planesnitch] INFO ALERT [Military Spotter] [Home] ae07e1 TEDDY64

The getting started guide⁠ walks through the Telegram bot setup and your first test alert.

β βš™οΈ How you configure it

One YAML file. Define where to watch, where the data comes from, what to snitch on, when to lose your shit, and where to scream about it:

locations:
  home:
    name: "Home"
    lat: 38.8719
    lon: -77.0563
    radius: 150km

sources:
  - type: adsb_fi
  - type: airplanes_live

watchlists:
  emergencies:
    type: squawk
    values: ["7500", "7600", "7700"]
  military:
    type: icao_csv
    source: plane-alert-mil.csv

alerts:
  - name: "Military Spotter"
    watchlists: [emergencies, military]
    cooldown: 5m
    notify: [tg_main]

notifications:
  tg_main:
    type: telegram
    bot_token: "123456:ABC-DEF"
    chat_id: "-100123456789"

Six watchlist types: all, squawk, icao, icao_type, icao_csv and proximity (the "what just buzzed my house" altitude filter). Alerts go to Telegram, with an aircraft-type photo, or to webhooks as JSON. Edit the file while it runs; the next poll picks it up. Every key is in the configuration reference⁠.

β πŸ”” What the alerts look like

πŸ”” Military Spotter
✈️ TEDDY64
πŸ›©οΈ BOEING C-17A Globemaster III | 94-0067 | 1994
πŸ’Ό USAF
🏷️ USAF β€” US Military
πŸ“ 37.9306, -78.7019 | 12,350 ft
πŸ“ 99 nm from Home
πŸ’¨ 413 kts
πŸ“‘ squawk 1613
πŸ—ΊοΈ https://globe.adsb.fi/?icao=ae07e1

Click the link, watch the bastard in real time on globe.adsb.fi⁠. The webhook payload is documented in notifications⁠.

β πŸ“š Documentation

The whole manual lives at psyb0t.github.io/docker-planesnitch⁠.

PageWhat's in it
Getting started⁠Config, Telegram bot, CSVs, first alert
Configuration⁠Every key, unit and default, plus env variables
Watchlists⁠The six types and the plane-alert-db lists
Notifications⁠Telegram format, photos, the webhook payload
How it works⁠Polling, sources, rate limits, dedup, cooldowns, health endpoint
Deployment⁠Docker, Compose, volumes, image tags, upgrades
Security⁠What leaves your machine and how to lock it down
Troubleshooting⁠Every error message and what to do about it

β πŸ€– Agent integrations

The skill⁠ works in any agent that reads .agents/skills/ (such as peen⁠), and installs natively in Claude Code, Codex and OpenClaw:

claude plugin marketplace add psyb0t/agents
claude plugin install planesnitch@psyb0t

Codex and OpenClaw commands are on the agent integrations page⁠.

β πŸ› οΈ Development

make test   # pytest in Docker
make lint   # ruff + mypy in Docker
make help   # everything else

Not 47 microservices. It watches planes and sends messages. That's it. Layout and the release pipeline are in development⁠.

β β˜• Sponsor

Buy Me a Coffee

β πŸ“ License

WTFPL⁠. Do What The Fuck You Want To. See CHANGELOG.md⁠ for release notes.

Tag summary

Content type

Image

Digest

sha256:447d817ef…

Size

49.5 MB

Last updated

10 days ago

docker pull psyb0t/planesnitch