A Claude Project setup that turns Claude into a third-wave specialty coffee scout. Give it the address or neighborhood where you're staying, and it returns a curated, map-displayed list of nearby coffee shops sorted by walking distance — with the syrup-forward and gimmick joints filtered out.

Most LLM-based "find me coffee" attempts hallucinate shops or recommend whatever has the most Google reviews. This setup leans on three Claude tools to do better:

• places_search pulls real Google Places data, so the shops actually exist and the addresses are right.
• web_search verifies quality from each shop's own website — checking for named roasters, single-origin offerings, and red flags like Torani syrup bottles in the photos.
• places_map_display_v0 plots the results on a map alongside the text list.

The two knowledge files (favorites.md and anti-favorites.md) act as your personal calibration. As you populate them with shops you've actually visited and why they worked or didn't, Claude's recommendations get sharper trip by trip.

1. Open Claude.ai, click Projects in the sidebar, and create a new project. Name it "Coffee Scout."
2. Open claude-project/instructions.md in this repo. Copy the entire contents and paste them into the project's Custom Instructions field.
3. Open claude-project/knowledge/favorites.template.md and anti-favorites.template.md. Save copies as favorites.md and anti-favorites.md, fill in a few of your own shops (or leave the templates blank to start), and upload them to the project's Knowledge section.
4. Start a conversation in the project. Claude will greet you and ask where to scout.

That's it. The defaults work even with empty knowledge files — they just get more personalized as you fill them in.

The two knowledge files are where this becomes your tool, not a generic one.

• favorites.md — shops you've loved, with one or two lines on why. The "why it works for me" field does the heaviest lifting. Specifics like "the barista knew the farm the Ethiopian came from, espresso was balanced not bitter, no syrup-forward distractions" teach Claude far more than star ratings ever could.
• anti-favorites.md — shops that disappointed you and the specific reason. Most useful when a place looked good on paper but failed in practice — those are the ones Claude is most likely to mistakenly recommend, so the entry sharpens the filter directly.

See examples/favorites.example.md for what a populated file starts to look like.

If you don't want to fork the whole repo, the bare instructions are also published as a GitHub Gist. Paste it into a Claude Project's custom instructions and you'll have a working scout — without the personal calibration, but still better than asking Claude cold.

When you start a scouting conversation, give Claude as much as you can up front:

• Specific address or cross-streets, not just a city — proximity sorting depends on it.
• How long you're staying and whether you have a car.
• Any constraints — e.g., "I'll be on foot," "early mornings only," "need wifi to work for an hour."

After a trip, tell Claude what was actually great vs. what missed. That feedback updates the knowledge files and compounds over time.

PRs welcome for prompt improvements, additions to the respected-roaster list, and refinements to the filtering logic. See CONTRIBUTING.md for what's in scope (and what isn't — your personal favorites file isn't a global contribution).

MIT. See LICENSE.