Alista

Returns JSON with: caption, taggedUsers, locationName, altText, imageUrls, videoUrl, transcript, etc.

Options:

• --download-images <dir> — Download post images locally for visual analysis
• --extract-frames <dir> — Extract key frames from video (requires ffmpeg); only processes URLs from whitelisted CDN hosts (cdninstagram.com, tiktokcdn.com, etc.)

Manual Save

Save a place by name (verifies with Google Places):

tsx scripts/save-place.ts --name "Place Name" --city "City" --category restaurant --verify

Categories: restaurant, bar, cafe, event

Look Up a Place

Verify a place exists without saving:

tsx scripts/lookup-place.ts --name "Place Name" --city "City"

Search Saved Places

Search your saved places:

tsx scripts/search-places.ts --query "coffee" --type cafe --limit 5

List All Places

List everything you've saved:

tsx scripts/search-places.ts --list

Get Suggestions

Get weekend suggestions based on your saved places:

tsx scripts/nudge.ts --count 3

Conversation Flows

When user shares a social media URL

1. Run fetch-post.ts with the URL to get raw post metadata
2. You reason about the metadata to identify places:
   • Check taggedUsers — in listicle/carousel posts, tagged accounts are often the featured places
   • Check caption — look for place names, addresses, city mentions
   • Check altText — Instagram auto-generates descriptions that often contain place names and neighborhoods
   • Check locationName — the tagged location (but verify it makes sense in context)
   • If text data is insufficient, use --download-images <dir> and analyze the images visually
   • For video posts, use --extract-frames <dir> (needs ffmpeg) or check transcript field
3. Save all verified places and immediately tell the user what was saved. For each place:
   • Run save-place.ts --verify to verify and save in one step
4. Show the user what was saved (name, neighborhood/address, category) so they can review
5. The user can reply to remove any they don't want — only act on removals, not approvals

When user asks to save a place by name

1. Run save-place.ts --name "..." --city "..." --verify
2. If verified: "Saved [Place Name] in [City]!"
3. If not found: "I couldn't verify [Name]. Want me to save it anyway?"

When user asks "what should I try this weekend?"

1. Run nudge.ts --count 3
2. Present suggestions with brief reasons (urgency, freshness, variety)

When user searches ("any good coffee spots?")

1. Run search-places.ts --query "coffee" --type cafe
2. Present results as a numbered list

When user asks to see their list

1. Run search-places.ts --list
2. Present as numbered list grouped by category

Error Handling

• If fetch-post returns no useful data: "I couldn't pull any info from that link. What's the place called?"
• If Google Places can't verify: "I couldn't find [Name] on Google Maps. Want me to save it as-is?"
• If no saved places: "You haven't saved any places yet! Share an Instagram or TikTok link to get started."

Data Storage

All data is stored locally in alista.db (SQLite). No cloud services needed for storage. The database is created automatically on first use.