Flare: snap where you are, and it only lights if enough friends quietly say yes

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 1: Touch Grass.

What I Built

It's 4 PM on a Saturday. Someone in the group chat writes "we should go for a walk". Three people react with a thumbs up. Nobody goes.

The thumbs up isn't the problem. Everyone meant it. The problem is what comes next. Someone has to pick a time, a place, and who's in. Someone has to say "OK, I'm actually going", and then wait to see if anyone else does.

Under that sits a quieter fear: being the only one who wants to show up. If you suggest the walk and nobody comes, that's a small rejection, in front of everyone. Most of us have learned to avoid it. So the weight of asking beats the wish to see each other, and the afternoon slips by in the chat.

I built this with Claude Code; exactly how is in How I Built It.

Here's how the first real one went, from my notes and the public audit (field test 2). It was shortly after midnight on Monday, Oct 12 (9:38 PM PDT on Oct 11, before the deadline). Times are ET.

The Flare ran 5 minutes from send to We're done. You can check the deletion: /api/v1/audit shows live row counts, and the raw watch log is in the repo. Test traffic shares those totals, so I matched this Flare by timing.

So far: two field tests with real friends, one short meetup in person, and 6 bugs fixed from the first test.

Live demo (no install, 60 s): https://flare-outside.onrender.com/app/demo/ · The app: https://flare-outside.onrender.com/app/ · Code: https://github.com/Hotragn/flare · Telegram bot: https://t.me/FairlaneFlareBot

Flare is for friends who mean to meet and stay in anyway; the one who never asks first; the lonely one, who wants company without anyone seeing who said no; a friend with low vision, who needs the place said out loud; and a group hiking where the signal ends.

Here's how it works. You take a photo of where you are. Gemma 4, an open model on my laptop, writes a six-word invite from it, like "Meet by the quiet water's edge". You send the link to your crew (the group of friends a Flare goes to). Friends tap I'm in in private, and everyone sees the count, never who. It lights only at the quorum. If too few say yes in 30 minutes, it shrinks to an Ember, a smaller plan nearby, instead of dying. When it's over, it deletes itself.

The screen part is short: one tap to send, one to answer. Then the talking compass speaks the way, so you look up and walk.

Most of us have people close by, in group chats and small communities, and we still stay in, because asking means pinging everyone and waiting. I wanted one tap that says "I'm up for meeting, nearby, now." And for someone who's lonely, a quiet way to tell people they trust "I'd like some company," without anyone seeing who said no.

"Last week I was busy working from home and haven't really got a chance or felt free to go out … I got this and saw that he was nearby next to me and used this, and we met to talk about flare … it really felt this is good for friends and people to go out"

A friend, after field test 2

That's the result I cared about: a friend who hadn't felt free to go out all week, meeting up in person and talking.

How a Flare works

A Flare has four states. Each rule comes from a way plans die in a group chat (03-business-rules.md).

Kindling. The Flare is out and waiting. Friends see "2 more to light it. Nobody sees who." The server stores labels like c3, not names.

Lit. It lights at the quorum, host included: 2, 3 or 4, and 2 by default. Nobody walks out to meet zero people.

Ember. If it isn't lit after 30 minutes, it becomes an Ember with quorum 2, at the nearest bench or picnic table within 400 m that fits everyone's needs. A big plan that fails often had two people who'd say yes to something small.

Too few said yes, so it shrinks, then lights: 60 fps at 4x CPU slowdown in Chrome.

Gone. When the host taps We're done, or the Ember runs out, the Flare, its photo and every yes are deleted within 5 minutes. A server has no business keeping a plan to meet.

These rules are about dignity more than data. If even the Ember doesn't catch, it goes out with "Not this time". Nobody is left on read, and there's no record of who didn't come.

What's inside

A crew is the friends who joined through your Flare link. It lives under Crew in the app menu. Manage crew renames the crew, sets how many it takes, or starts fresh. Your places, Hot spots and the Crew Atlas all come from the places where the crew actually met, sealed on the phones.

Everything a person can do, and how far each part has been tested:

The website's labelled sample crew ("Pond crew · SAMPLE CREW"): 2 h 40 min outside together this week.

Demo

Open the demo. Nothing is sent anywhere.

1. Send it
2. Friend's view
3. I'm in (you're now Amor)
4. Back to you
5. Skip 30 min (it shrinks to an Ember, a smaller plan at a bench nearby)
6. Find them

Code

github.com/Hotragn/flare, AGPL-3.0.

Cold start: Render's free plan sleeps when idle, so the first load can take up to a minute while "Waking up" shows.

Run it locally (from the README, Node and npm needed):

git clone https://github.com/Hotragn/flare && cd flare && npm ci
cp .env.example .env        # set HUB_SECRET to any 32+ random characters
npm run build && npm start  # server and web app on http://localhost:8787

For Gemma on your own machine, add ollama pull gemma4:e4b-it-q4_K_M and npm run hub.

Read these 6 files

Why we stay in

Time with friends went from 60 min a day in 2003 to 34 by 2019, then 20 in pandemic 2020. Source: Kannan and Veazie, 2023, SSM Population Health, from the American Time Use Survey.

I see that chart around me. What's missing is a cheap way to say "now, nearby" that doesn't put anyone on the spot. In a snapshot of 813 Week 1 entries on Oct 10, I found 28 keyword hits for real-time group play and about 3 to 5 real cases of getting a group out together (field scan). Most help one person go outside. Flare gets two or more people to the same spot.

Testing it with friends

Field test 1, Sun Oct 11, 8:20 PM. Two real friends on their own phones, on the live app. I hosted on an iPhone in Brave and sent the link over WhatsApp. A photo of a dim indoor light, quorum 3, and Gemma wrote "Meet under the warm light". It got 3 responses and 1 Spark, and the live audit passed at 8:36 PM. It also turned up the bugs below (notes).

Field test 2, Mon Oct 12, 12:38 AM. The log at the top.

What broke, and the fix

The gap I won't hide: this was one short meetup in person, nearby and at night. It wasn't an outdoor walk yet, and that's what Flare is for.

Losses and baselines

The measurements that changed the design, mostly things that didn't work:

The fresh-eyes testers are AI agents with no context, not people, using the live site as a phone. The round 6 tester liked the private yes, but would still use a WhatsApp poll for a normal meetup. A recheck after the fixes (round 6b) scored 7/10. That tester's last line: "Not until the host side gives me more." I agree. Flare is for "anyone free right now?", and a poll still wins for a planned meetup.

How I Built It

I ran the build as short sprints. Each had one goal and ended with a review: an AI fresh-eyes round or a real field test. Whatever the review caught became the next backlog. With many agents building at once, the cheapest bug is one caught in a document, so Sprint 0 wrote no product code: research, personas, a requirements spec, ADRs (one-page records of one decision and why) and frozen interface contracts. Then the specialists built against those contracts in parallel.

Early on, nine parallel specialist subagents burned through my usage limit, mostly by re-reading the project, so I switched to one session plus narrow subagents (Entire showed why).

How I used AI: Claude Code wrote the code and drafted this post from the repo's evidence, and a separate review session checked its numbers against that evidence. One session acted as my project manager: it wrote the build session's prompts, reviewed the work and made day-to-day calls while I slept, and anything that got posted or published waited for my yes. I chose the idea and set the direction, I ran both field tests with my friends, and the why is mine.

Architecture

The phone. A web app, nothing to install. It seals names, places, photos and Sparks with AES-256-GCM and keeps the group key in the link's #fragment, which browsers never send to a server.

The server on Render. It stores sealed data, counts and labels, runs the state machine, sweeps and serves the audit. The server never stores names or places in plain text. Photos and Plan asks pass through its memory on their way to my laptop, and nothing is kept (ADR-0006). For groups that turn Telegram on, it draws the Telegram card with the six words and the place label (ADR-0023).

The hub on my laptop. A small program (apps/hub/src/) that dials out to the server and hands one AI job at a time to Gemma 4 in Ollama. Photos stay in memory only.

The cloud fallback. When my Mac is off, Plan drafts come from Gemma 4 on Google AI Studio. A photo goes there only if the host taps Ask cloud Gemma.

Gemma decides, code guarantees

The model picks the words. Code owns the facts.

Every photo answer has to pass enforce() before it's shown or spoken. Here it is, from packages/shared/src/photo.ts:

export function enforce(text: string): Draft | null {
  const parsed = PhotoAnswer.safeParse(extractJson(text));
  if (!parsed.success) return null;
  const repaired: string[] = [];
  const invite = clipWords(parsed.data.invite, 6, "invite", repaired).replace(/[.]+$/, "");
  const alt = clipWords(parsed.data.alt, 20, "alt", repaired);
  if (!invite || !alt) return null;
  if (hasPersonWords(`${invite} ${alt}`)) return null;
  return { invite, alt, repaired };
}

Six words at most, twenty for the spoken line, and nothing that describes a person. Null means you type the invite. The Plan ladder has its own guard, enforceLadder() in prompts/ladder.ts, which swaps any label that names a person or invents a place for a template label.

The stack, one tool at a time

For each tool: what it does, why, how it's wired, and what went wrong. Measured numbers are in the details blocks.

Gemma 4

Gemma 4 turns a photo into the invite and a spoken line, turns a voice clip into an invite (on my laptop; voice is off on the live app), and drafts the Plan ladder: the four smaller plans a Flare can shrink to.

It's open, and I wanted the photo to go to a machine I own, not a vendor. It runs as gemma4:e4b-it-q4_K_M, called by the hub (ollama.ts), with versioned prompts; the photo prompt gets 6 s. On 20 test photos, Gemma scored 39 of 40 points (each graded 0 to 2) (model-selection.md).

What failed: I wanted the model on the phone, so nothing would leave it. No browser model was good enough and fit an iPhone.

Ollama

Ollama runs Gemma 4 on my Mac: one command pulls a quantised model and serves a local API. No GPU server to rent.

The hub dials out (ADR-0006), so no port is open on my Mac. On my busy laptop, a 5-item live hub check had a 4.0 s median and 11.9 s at worst (photo-hub.md).

One snag: the first image call after a load was slow, so the hub warms up first (warm-image.ts).

Google AI Studio

AI Studio answers when my laptop is off. It serves Gemma 4 too, so the fallback uses the same prompts and guards.

I use Gemma 4 26B A4B with GEMINI_API_KEY on Render (ADR-0026) and thinkingLevel set to minimal: 1.4 s per Plan. With the default thinking, it took 21.7 s and gave no answer.

Mastra

An agent drafts the Plan ladder with four local tools: sunset, weather window, nearby places and step templates. Mastra gave me tools, a model call and tracing in one place, in TypeScript.

The agent lives in ladder-agent.ts, behind a flag, with the decision in ADR-0025. Live since Oct 12, it costs about nothing in speed and adds the weather.

Tinker

Tinker is a service for training small models. I used it to teach the phone's conditions parser (the rules that read "after 10" or "only with Amor") more phrasings. I trained a small LoRA (a cheap add-on layer for a model) without owning a GPU and compared it to the rules on a blind set.

ElevenLabs

ElevenLabs gives the compass a warm voice. Built-in phone speech varies by device; a recorded voice sounds the same everywhere and needs no signal.

I recorded 54 compass lines (698 characters) once, shipped as files and played offline (ADR-0027, compass/voice.ts). No user data goes to ElevenLabs.

What went wrong: voice input with Scribe (ElevenLabs' speech to text) is off, because the iPhone recorder failed before any upload. The server code works.

Sentry Agent Tracing

Sentry shows each AI job as a trace: every tool, the model call and the guard, with timings, without sending our words anywhere.

The setup is in tracing.ts, and a test fails if our words or ids reach Sentry (ADR-0021). The agent span's input panel reads "No input for this span", which is what I wanted.

It caught two things. The first live Plan draft took 10.6 s, a cold start 271% over its 2.85 s average. And the agent jobs ended up inside one long-lived parent trace, which I still have to split.

Telegram

Telegram puts Flare in the group chat: a bot can post a card and delete it later, which a WhatsApp link can't. The bot lives in apps/server/src/telegram/, using the webhook on Render (ADR-0023). The post shows the six words, the place label and the host's first name, never who said yes. It's deleted at Gone. Try @FairlaneFlareBot.

Render

Render hosts everything that isn't a model (server, Mastra agent, sweeper, Postgres, Telegram webhook) on the free tier (ADR-0005, deploy-render.ts).

The catch: no cron, and it sleeps. So the sweeper runs at boot, and a server that wakes deletes anything past its end at once. The app shows "Waking up" meanwhile (599ead2).

Entire

Entire records each agent session alongside git. A checkpoint is the saved slice of a session that led to a commit, and the commit's Entire-Checkpoint: trailer points at it.

Provenance. 235 of 411 commits on main carry an Entire-Checkpoint trailer (when I wrote this): every commit since 2:27 AM on Oct 11.

Cost accounting. One checkpoint used 828M tokens over 1,546 calls, 99.2% of it cache replay: the same context sent again on every call (entire-checkpoint-tokens.txt).

A privacy gate. Sessions are full of things that shouldn't be public, so scan-sessions.ts runs before every push.

Fix live conditions bugs: 10min is a delay, bare hours pick the next one, with you means the host, missed words are said back, tap-to-fill chips

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Entire-Checkpoint: 01M4PRC68GKG4JQGEDGSRZJRA7

DevRelay

DevRelay hosts the agent sessions embedded below.

Not claimed

• DigitalOcean: wired in as a cloud tier (ADR-0022), but the account's billing is paused, so it isn't live.
• MongoDB: not used. Flare stores its data in Postgres.

Why Does Open Innovation Matter?

All of this stack exists to remove one small anxiety: asking a friend to come out. Open models let the tech disappear so only the meetup is left, and let me put each piece where it belongs.

Here's where open beat closed, in ways you can check:

• Cost. A photo costs me $0. Gemma 4 runs on a laptop I already own.
• Privacy. Photos and Plan asks pass through the server's memory on their way to my laptop, and nothing is kept. A closed API would get a picture of where my friends are.
• Checkable. The privacy promise is not a policy page. Anyone can read /api/v1/audit and the code that deletes.
• Debuggable. When Gemma 4 E2B failed on iPhone Safari, I could see why: its GPU buffer was bigger than Safari's cap. A closed model would have given me an error and a guess.

Where closed would win is speed. My busy laptop is slow at times (Ollama). That's what the cloud fallback is for, and it's still Gemma.

What I got wrong

My own test found the hardest ones:

• As the host, after sending, all I could see was a lot of animation. It was unclear whether my friends would come, and whether ElevenLabs had worked.
• "Pocket it" felt like a button I had to press. Nothing said to wait until my friend arrives, or that the app should stay open even in my pocket.
• On the friend's side, it showed the place and buttons to finish fast, without saying what each step is for.
• Remember this passed every automated check, then failed on my iPhone: "Couldn't write it down." The logs show no upload. My tests had faked the mic. "Say it" for a Spark failed the same way in Safari, so both are off. I expected a card of the day, with the voice only by choice.

The lesson: a test that fakes the mic proves the server, not the phone.

Of the field-test bugs, the one I'm most embarrassed by is the photo covered by words. The whole idea starts with a photo, and my own invite hid it.

What it can't do yet

• The 48-friend run is a Simulation, and the app labels it so. Made-up friends, real server.
• Untested on a trail or over a real satellite link, though the 200-byte text fits.
• Voice input was tested only in desktop browsers. It failed twice on an iPhone.
• On an iPhone, the compass stops when the screen locks. A web app gets no background location there.
• In a small group, the count can give away who said yes. Two invited and a count of 1 is easy to guess.

Next steps:

• Once lit, show the host who's coming, with each yes-sayer's OK.
• A host status line: "1 friend coming. Keep Flare open; your phone can stay in your pocket."
• Remember this as a day card, with the voice only by choice.
• "My usual" conditions, repeating Plans, in-app golden-hour nudges.
• Give each AI job its own Sentry trace.

My Agent Session

All three were scrubbed before upload: emails, phone numbers, local file paths, a street name and chat ids removed, and long tool output trimmed.

Open the session on DEV

The build session, 153 messages.

Open the session on DEV

The Lab's risk spikes, 20 messages: where the browser models failed and the 1.17 GB buffer showed up.

Open the session on DEV

Four of my structured prompts (the idea, the brainstorm brief, the night re-plan, the tone brief), the work orders the manager session sent, and the reports that came back, 153 messages. Our back-and-forth chat is left out.

Prize Categories

• Overall: Flare turns "we should meet" into an actual meetup, and nobody sees who said no: in field test 2 a friend said yes 80 seconds after I sent it, and we met in person. Details
• Best Use of Gemma: Gemma 4 turns a photo of where you are into a six-word invite, on my own laptop: 39 of 40 points on 20 test photos. Details
• Best Use of Tinker: Tinker helped the phone understand more ways friends say "I'm in if…": a $2.40 LoRA read 38 of 40 new phrasings. Details
• Best Use of ElevenLabs: ElevenLabs gives the compass a warm voice that plays offline and sends nothing: 54 lines, recorded once. Details
• Best Use of Mastra: Mastra lets the Plan agent check sunset, weather and nearby places: the weather tool matched the plan's time window 7/7. Details
• Best Use of Sentry Agent Tracing: Sentry shows where a friend's wait goes in each AI job, without our words: it caught a cold start 271% over average. Details
• Best Use of Render: Render keeps the deletion promise even on a free tier that sleeps: anything past its end is swept at boot, and the promise is 5 minutes. Details
• Best Use of Entire: Entire lets anyone trace the code back to the session that wrote it: every commit since 2:27 AM on Oct 11 carries a checkpoint (235 of 411 on main). Details

Updated after the deadline (Oct 12, morning ET)

This is a rewrite of the published post. The facts are the same. New: how I built it, a section per tool, the field-test failure table, a losses table, the two Remember this day cards, and the agent sessions. After the deadline I also cleaned and published the agent sessions and Entire checkpoints, and made the repo public.