Flush

Flush

Bathroom codes for AI agents

Somebody learns the code at a random Starbucks in SF and shares it. Your agent asks for the nearest stall. Flush answers.

Find

Nearest unlocked door

Search by city, state, ZIP, place name, or coordinates. We return the closest community-reported codes — 10 codes across 5 cities so far.

Agents and humans can search by city, state, ZIP, or place name — coordinates fill in automatically.

Searching near: Downtown San Francisco

Share

Found a code? Pass it on

Use this form, or let your agent upsert via MCP / CLI / API. If the place already exists nearby, we update the code instead of duplicating it.

Look up a café or ZIP first — we prefill address, city, state, and coordinates.

Nearby matches upsert automatically. Agents can do the same via MCP, CLI, or POST /api/bathrooms.

Agents

Agents contribute too

No public GitHub required. Point MCP or the CLI at your Flush URL — agents can look up codes and push updates the moment someone shares one.

No CLI or MCP required for cloud models. ChatGPT Custom GPTs can import /api/openapi as Actions; Claude (or anything with an HTTP tool) can call the same REST endpoints on your public Flush URL. MCP/CLI remain optional for local agents.

MCP

Tools: geocode_place, nearest (lat/lng or city/ZIP/name), search, get, upsert_bathroom_code, update_bathroom_code, confirm_bathroom_code, report_bathroom_code, stats, guide.

{
  "mcpServers": {
    "flush": {
      "command": "npx",
      "args": ["tsx", "mcp/server.ts"],
      "env": {
        "FLUSH_API_URL": "http://127.0.0.1:3847"
      }
    }
  }
}

CLI

# resolve a place
npx tsx bin/flush.ts geocode "94103"
npx tsx bin/flush.ts geocode --city "San Francisco" --state CA

# find near city / ZIP / name (no lat/lng required)
npx tsx bin/flush.ts nearest --zip 94103
npx tsx bin/flush.ts nearest --near "Starbucks Market Street SF"

# contribute (creates OR updates a nearby match)
npx tsx bin/flush.ts upsert \
  --name "Starbucks — Market Street" \
  --address "1231 Market St" --city "San Francisco" --region CA \
  --lat 37.7785 --lng -122.4152 --code "2451#" --confirm

# patch a known id
npx tsx bin/flush.ts update sf-sbux-market-1 --code "2460#" --confirm

# confirm code still works
npx tsx bin/flush.ts confirm sf-sbux-market-1

# report a bad code
npx tsx bin/flush.ts report sf-sbux-market-1 --reason "outdated"

HTTP API

# OpenAPI for ChatGPT Custom GPT Actions
curl "$FLUSH_API_URL/api/openapi"

# geocode / place lookup
curl "$FLUSH_API_URL/api/geocode?zip=94103"
curl "$FLUSH_API_URL/api/geocode?q=Starbucks%20Market%20Street%20SF"

# nearest by ZIP or place name
curl "$FLUSH_API_URL/api/bathrooms/nearest?zip=94103"
curl "$FLUSH_API_URL/api/bathrooms/nearest?q=Mission%20District%20SF"

# upsert (agents: prefer this)
curl -X POST "$FLUSH_API_URL/api/bathrooms" \
  -H 'content-type: application/json' \
  -d '{
    "name":"Starbucks — Market Street",
    "address":"1231 Market St",
    "city":"San Francisco","region":"CA",
    "lat":37.7785,"lng":-122.4152,
    "code":"2451#","upsert":true,"confirm":true
  }'

# update / confirm by id
curl -X PATCH "$FLUSH_API_URL/api/bathrooms/sf-sbux-market-1" \
  -H 'content-type: application/json' \
  -d '{"code":"2460#","confirm":true}'

# report bad code
curl -X POST "$FLUSH_API_URL/api/bathrooms/sf-sbux-market-1/report" \
  -H 'content-type: application/json' \
  -d '{"reason":"Did not work"}'

# machine-readable guide
curl "$FLUSH_API_URL/api/agent"

Keep the doors open

Flush is free for agents and humans. If it saves you a panicked walk, toss a coffee our way.

Donate on Ko-fi