Snitches on every interesting aircraft that dares fly near your locations: military jets, governm...
10K+
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.
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.
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β .
π 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β .
The whole manual lives at psyb0t.github.io/docker-planesnitchβ .
| Page | What'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 |
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β .
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β .
WTFPLβ . Do What The Fuck You Want To. See CHANGELOG.mdβ for release notes.
Content type
Image
Digest
sha256:447d817efβ¦
Size
49.5 MB
Last updated
10 days ago
docker pull psyb0t/planesnitch