Birdfolio

• 

  Birdfolio logo

Inspiration

Birding apps haven't changed much in a decade. You open Merlin, snap a photo, get an ID — then manually log it somewhere else, separately, with no personality. The life list is a spreadsheet.

Meanwhile, AI agents are getting genuinely useful for everyday tasks. We asked: what if your agent was the birding app? No downloads, no accounts — just send a photo to the chat you already have open, and let the agent handle everything else.

That's Birdfolio. The idea came from a simple observation: the best tool is the one you're already using.

───

What it does

Birdfolio turns your custom AI agent into a personal field journal:

1. Send a bird photo via Telegram: No special command, just send it
2. Instant AI identification: Species, scientific name, visible features
3. Rarity classification: Powered by You.com's real-time search against eBird frequency data, classifying each find as Common 🟢, Rare 🟡, Super Rare 🔴, or Bonus ✨ for your specific region
4. Trading card generated: Your actual photo gets embedded into a styled field journal card with the fun fact, rarity badge, and scientific name
5. Life list updated: Logged to a shared hosted database, no setup required
6. PWA delivered: Your personal field journal at birdfolio.tonbistudio.com/app/{your_id}, installable to homescreen

New users get their personal link automatically after their first sighting. No account creation, no API keys to manage, it just works.

───

How we built it

The stack is deliberately minimal:

• Agent layer: OpenClaw skill (SKILL.md) with Claude/GPT-4o vision for identification • Rarity engine: You.com API (https://you.com/) querying live eBird data — the real-time results make a meaningful difference over static databases • Card generation: Python script produces HTML, Playwright (headless Chrome) screenshots it to PNG • Storage: FastAPI + PostgreSQL on Railway, keyed by Telegram ID — no signup flow • Card hosting: Cloudflare R2, uploaded server-side so users need zero credentials • PWA: Vanilla JS, dark "nature meets AI" aesthetic — bioluminescent greens, JetBrains Mono for scientific names, installable to homescreen

The whole skill is publishable to ClawHub (https://clawhub.com/) and installable with one command:

clawhub install birdfolio

───

Challenges we ran into

You.com (http://you.com/) as the rarity oracle. eBird frequency data isn't available in a clean API — we had to design You.com (http://you.com/) search queries that reliably surface rarity signals ("abundant", "vagrant", "accidental", <5% of checklists) and classify them consistently. Getting this right took careful prompt engineering and query design.

Server-side R2 uploads. Initially we required users to set up their own Cloudflare R2 bucket — a significant friction point. Moving uploads server-side (API accepts a PNG, uploads internally, returns a public URL) eliminated the biggest barrier to adoption.

PWA homescreen URL bug. When users added the app to homescreen, it opened /app/static instead of /app/{telegram_id}. The culprit: manifest.json with start_url: "./" was served from /static/, so ./ resolved to the wrong path. Fix: generate a dynamic manifest.json per user at /app/{telegram_id}/manifest.json with the correct start_url baked in.

Service worker cache staleness. After adding card image URLs to the database, existing PWA installs still showed placeholders because the service worker had cached the old API response. Solved by bumping the cache version, which triggers automatic invalidation on next load.

───

Accomplishments that we're proud of

• Zero setup for users. No Railway account, no Cloudflare, no credentials — clawhub install birdfolio, then just start sending photos. • You.com (http://you.com/) powers real rarity. Every sighting gets classified against live eBird frequency data for the user's specific region, not a static hardcoded list. • The card pipeline. Photo → AI ID → HTML card → Playwright screenshot → R2 upload → PWA display, fully automated in a single agent turn. • Multi-user from day one. Every user gets their own scoped life list, checklist, and PWA URL — all from a single shared deployment.

───

What we learned

You.com (http://you.com/)'s real-time search is genuinely better than static datasets for this use case. eBird frequency varies dramatically by region and season — a Cedar Waxwing is common in the Pacific Northwest but a notable sighting in Southern California. Getting that nuance right required live search, not a lookup table.

We also learned that frictionlessness is a feature, not a polish step. Every credential we removed (Railway, R2, database) wasn't just convenience — it was the difference between a skill someone installs and one they abandon after the first setup screen.

───

What's next for Birdfolio

• Sound ID — Merlin's killer feature; adding audio clip support for bird call identification • Photo gallery per species — tap a life list entry to see all your sightings of that species over time • Social sharing — one-tap share for trading cards to X/Twitter • Streak tracking — consecutive days with a new sighting, seasonal challenges • Multi-region support — users who travel can log sightings across regions with per-region checklists • ClawHub v2 — publish as a fully hosted skill so any OpenClaw user gets Birdfolio with zero configuration

Built With

• boto3
• claude-vision
• clawhub
• cloudflare-r2
• fastapi
• html/css
• javascript
• openclaw
• playwright
• postgresql
• pwa
• python
• railway
• sqlalchemy
• telegram-bot-api
• you.com-(http://you.com/)-search-api