DEV Community: Arya Koste

Clarity: Understanding, Out Loud

Arya Koste — Mon, 13 Jul 2026 04:33:01 +0000

This is a submission for Weekend Challenge: Passion Edition

Inspiration

Passion doesn't only live on a pitch or in a stadium chant. Sometimes it's quieter than that — it's the stubborn, protective love that makes you want to shield someone from feeling stupid or scared.

Everyone has a person like this in their life: a grandparent who freezes when a dense hospital bill shows up in the mailbox. A parent whose English is a second language and who reads "final notice" and assumes the worst. A friend with a reading disability, low vision, or dyslexia who has to ask someone else to make sense of their own mail for them. Official mail is written by institutions, for institutions — dense, jargon-heavy, and never for the person actually holding the envelope, hands shaking a little, afraid to open it alone.

The real problem was never that these people can't hear — it's that they can't understand. So Clarity isn't a text-to-speech gadget. It's a comprehension tool first: it reads a confusing document the way a patient, well-informed friend would — breaking it down, translating the jargon, telling you what actually matters — and only then does it speak, because understanding something and having no way to absorb it is its own kind of cruelty.

Clarity is built out of that same fire people usually save for rivalries and fandoms, just pointed somewhere quieter: nobody I love should ever feel powerless in front of a piece of paper they can't make sense of.

What it does

You hand Clarity a document — a photo of a paper letter, a PDF, or just pasted text — and it:

Understands it and breaks it down, not just transcribes it. A calm, structured explanation: what this document actually is, the parts that matter, exactly what you need to do and by when, and anything to watch out for (fees, penalties, easy-to-miss deadlines) — turning a wall of legal or medical jargon into something a person can actually act on.
Adapts to how you understand best — "explain it like I'm 10," plain everyday language, or full precision that preserves legal/technical detail for someone who wants it straight.
Speaks the explanation out loud, with each word highlighting in perfect sync as it's read — genuinely useful for low vision, dyslexia, or anyone who processes speech better than dense paragraphs.
Speaks it in 9+ languages — the same English medical bill, understood and read back in Spanish, Hindi, Arabic, and more.
Takes follow-up questions by voice — tap the mic and ask "how much do I actually owe, and by when?" — answered directly from the document, and read back to you too.
Turns real deadlines into calendar reminders — one tap adds "pay by April 22" straight to your calendar as a .ics file, but only when the document actually states a real date (it won't guess at vague phrasing like "within 30 days").

It runs as a single, no-build Node/Express server with a vanilla HTML/JS frontend — your document is processed entirely on your own machine. The only thing that ever leaves it is a few sentences of already-plain-language explanation text, sent to ElevenLabs to become audio.

See it in action

I ran Clarity against three completely different kinds of confusing paperwork, live, with a real AI model doing the understanding and real ElevenLabs audio doing the speaking — no canned demo text:

Document	What Clarity understood and explained
🏥 Hospital bill ($1,284.67 balance)	Deductible + coinsurance breakdown, the exact due date, late-fee and credit-impact warnings, a glossary entry for "coinsurance"
🧾 IRS CP2000 tax notice	The $2,161.05 total owed, the April 22 payment deadline (with a working "Add to calendar" button), the 30-day response window, glossary entries for "Form 1099-NEC" and "CP2000"
⚖️ Jury duty summons (explained "like I'm 10")	Eligibility rules, the May 1 confirmation deadline, pay rate, and a plain-English glossary for "probation" and "felony conviction"

And the signature moment — the explanation read aloud with word-by-word highlighting, driven by ElevenLabs' actual audio timing, not a guess:

Code

Aryakoste / Clarity

Clarity 🔊

A voice companion that reads and explains confusing letters, bills, and medical notices — in plain language, out loud.

Millions of people freeze when official mail arrives: dense legal wording, medical jargon, "final notice" red ink. That burden falls hardest on elderly people, people with low vision or dyslexia, and non-native speakers. Clarity takes a photo or PDF of that letter and gives back a calm, spoken explanation: what it is, the parts that matter, exactly what you need to do, and what to watch out for — read aloud with the words highlighting as it speaks. You can then ask follow-up questions with your voice.

Built to run entirely on your own machine — your documents never go to a third party (except the few sentences of explanation sent for text-to-speech).

What it does

📄 Reads any document — upload a PDF, snap a photo of paper…

View on GitHub

How I built it

Node.js/Express server, single file, no build step. Holds the ElevenLabs key server-side — the browser never sees it.
Text extraction: pdfjs-dist for PDFs, tesseract.js for OCR on photographed letters.
The understanding layer: a swappable LLM — local Ollama (llama3.2, $0 cost, runs entirely on-device), or hosted OpenAI/Anthropic — that turns raw, jargon-heavy document text into a structured plain-language breakdown: summary, key points, actions with deadlines, warnings, and glossary.
The voice: ElevenLabs' text-to-speech API, specifically the with-timestamps endpoint, which returns character-level timing alongside the audio. The frontend maps that real alignment data onto individual word spans, so the highlight isn't a fake proportional estimate — it's actually locked to the audio.
Voice input: the browser's built-in Speech Recognition API for asking follow-up questions hands-free — no extra key required.
Calendar export: client-side .ics generation, only offered when a real, parseable date exists — no guessing at vague deadlines.

Challenges I ran into

Real word-level sync is harder than it looks. My first pass at highlighting used a length-weighted time estimate per sentence — good enough to demo, but not actually synced to the audio. Rebuilding it on ElevenLabs' character-level alignment data meant reworking the transcript into per-word spans and mapping character offsets back to real timestamps, with a graceful fallback to the old estimate if alignment ever comes back empty.
A live 402 from ElevenLabs. Mid-testing, the app's original default voice started returning payment_required — turns out ElevenLabs recently restricted "library" voices to paid plans via the API. I caught it, pulled the account's actual available voice list, and swapped in a working free-tier voice ("Sarah") so the app isn't silently broken for the next person who clones it.
Trustworthy dates, not guessed ones. For the calendar export, I deliberately only parse deadlines that resolve to an unambiguous date — "April 22, 2026" gets a calendar button, "within 30 days" doesn't. For a tool handling bills and legal notices, a wrong guess about understanding is worse than no shortcut at all.

Accomplishments I am proud of

Getting the whole pipeline — OCR/PDF extraction → real AI comprehension and plain-language rewriting → real ElevenLabs voice with true word-level sync → calendar export — working end-to-end, verified live against three genuinely different real-world document types, with zero console errors and a recorded video + audio to prove it.

What I learned

That "passion project" doesn't have to mean something loud. Some of the most stubborn devotion shows up as making sure a scary, confusing envelope never gets the last word — and that understanding, not volume, is the thing that actually needs delivering first.

What's next

A caregiver "share this explanation" mode, so an adult child can see exactly what their parent's letter said and meant.
A lightweight "does this look like a scam?" pass, given how much of this mail is designed to look official whether it is or not.
True multilingual voice models (eleven_multilingual_v2) for richer non-English read-alouds.

Built with

Node.js · Express · pdfjs-dist · tesseract.js · ElevenLabs (Text-to-Speech + timestamps API) · Ollama (llama3.2) · Web Speech API · vanilla HTML/CSS/JS

Prize category: Best use of ElevenLabs

Clarity's core job is comprehension — the real AI-driven breakdown of a confusing document into plain language is what makes any of this useful. But comprehension that stays trapped on a screen doesn't reach everyone it needs to: the whole point is to hand that understanding to people who read poorly, see poorly, or read a different language — and that handoff happens entirely through ElevenLabs. Specifically, I use:

The with-timestamps TTS endpoint, not just plain audio — its character-level alignment data is what drives real, accurate word-by-word highlighting, rather than a fake time estimate, so the explanation is followable in real time, not just audible.
Multiple output languages through the same voice pipeline, so the same plain-language explanation can be read back in Spanish, Hindi, Arabic, and more.
Voice configuration as a first-class setting (voice ID, model ID) — and I hit and fixed a real free-tier API policy change along the way, which says something about how deep the integration actually goes.

I Put My Dying Side Projects on Life Support — an ICU With Real EKGs, a Snowflake Lab, and an On-Chain Defibrillator

Arya Koste — Mon, 13 Jul 2026 03:21:23 +0000

This is a submission for Weekend Challenge: Passion Edition

What I Built

I have lots public repositories. some of them are dead.

Not deleted — dead. There's a difference. Deleted would mean I made a decision. Dead means one day I committed "fix readme typo" and never came back, and the repo has been lying there ever since, full of half-finished dreams and a TODO.md I'm afraid to open.

Everyone builds graveyards for these projects. Post-mortems. Eulogies. I didn't want a graveyard — because my projects aren't dead to me. They're comatose. So I built the other room in the hospital.

LIFE SUPPORT is an intensive care unit for your side projects.

You admit your GitHub username to the ward. Every repo becomes a patient on a live, animated EKG monitor — commit cadence is the heart rate, and projects you've abandoned show the one thing no developer is emotionally prepared to see:

A flatline. With the sound.

Then the lab runs your entire commit history through Snowflake and prints your chart, including the number I was genuinely afraid to learn about myself:

My passion half-life: [23] days.
The median time it takes my enthusiasm for a new project to decay by 50%. Fitted as an exponential decay curve over my actual weekly commit counts. My love has a measurable half-life, and it is shorter than a gym membership.

The chart also includes:

BPM — beats per month. One commit, one heartbeat.
The 2 AM index — [26]% of my commits happen between midnight and 5 AM. That is not a schedule. That is love.
Ward census — [3] alive, [6] flatlined, [1] critical.
Longest flatline — [crypto-tracker], silent for [2.2 years], built at the exact top of the market.

And then — the part I'm proudest of — the app doesn't let you just feel bad. Every flatlined patient has a red button:

⚡ DEFIBRILLATE

Pressing it opens a revival pledge on Solana: a memo transaction, signed with your own wallet, containing a vow to ship at least one commit to that repo within 7 days. It's permanent, timestamped, and publicly auditable.

Here's why a blockchain, sincerely, and not as a sticker: you can delete a todo list. You can dismiss a calendar reminder. You cannot quietly un-promise something you signed on-chain. It's a commitment device. After the deadline, LIFE SUPPORT checks GitHub and renders one of three verdicts: PLEDGE HONORED, PLEDGE PENDING, or — the chain remembers this one too — PLEDGE BROKEN.

I signed a pledge for [ai-recipe-bot], flatlined [267] days. The clock is ticking as you read this. Feel free to check whether I honored it.

Demo

Two things to try:

Toggle SOUND ON in the header, then hover a healthy monitor. Then hover a flatlined one. I'm sorry in advance.
Look at the "when the passion burns" histogram. The red bars are your nights.

Full walkthrough:

Repo

Aryakoste / LifeSupport

🫀 LIFE SUPPORT

An intensive care unit for your dying side projects.

Every repo you abandoned is still in there. LIFE SUPPORT admits your GitHub account to the ward, puts every side project on a live EKG monitor, runs your entire commit history through a Snowflake-powered lab, and prints the one number you are afraid of: your passion half-life — how many days it takes your love for a new project to decay by half.

Then it hands you a defibrillator: an on-chain revival pledge on Solana. A permanent, timestamped, publicly auditable vow to ship one commit within 7 days. You can delete a todo list. You cannot quietly un-promise.

The ward at a glance

Vital	What it means
Passion half-life	Exponential decay fit over your weekly commit counts: `ln(commits+1) ~ a + b·week`, half-life = `-ln(2)/b`. Computed per repo, reported as the median.
BPM	Beats per month.

…

View on GitHub

Started and finished inside the challenge window, as the rules demand — which felt poetic, because building a project about abandoning projects in 48 hours means racing your own half-life. According to my chart I had at least [23] days of love available. I only needed two.

How I Built It

Stack: Next.js 14 (TypeScript) · Snowflake · Solana (devnet, Memo program) · GitHub REST API · hand-rolled canvas EKGs · WebAudio · zero UI libraries.

The lab runs on Snowflake — actual SQL, not a sticker (Best Use of Snowflake)

Every commit is ingested into a Snowflake table, and the entire diagnosis is one SQL statement. The parts I enjoyed way too much:

1. The passion half-life is a linear regression in SQL. Log-linearize exponential decay, then let REGR_SLOPE do the fitting:

-- ln(commits + 1) ~ a + b * week   →   half-life = -ln(2)/b
SELECT REPO, REGR_SLOPE(LN(N + 1), WK) AS B
FROM weeks_dense GROUP BY REPO
-- later: IFF(B < 0, -LN(2) / B * 7, NULL) AS HALF_LIFE_DAYS

2. Silent weeks must count. A decay fit over only the weeks you did commit is flattery. I densify the calendar with a GENERATOR so every silent week shows up as a zero — the silence is the data:

SELECT b.REPO, g.WK, COALESCE(w.N, 0) AS N
FROM bounds b
JOIN LATERAL (SELECT SEQ4() AS WK FROM TABLE(GENERATOR(ROWCOUNT => 10000))) g
  ON g.WK <= FLOOR(DATEDIFF(day, b.FIRST_C, b.LAST_C) / 7)
LEFT JOIN weekly w ON w.REPO = b.REPO AND w.WK = g.WK

3. Commit streaks are gaps-and-islands. The old window-function party trick: day number minus row number is constant within a consecutive run:

DATEDIFF(day, '1970-01-01', D)
  - ROW_NUMBER() OVER (PARTITION BY REPO ORDER BY D) AS GRP

There's also a local TypeScript engine implementing the identical math, so the demo works with zero setup — both engines agree on a toy dataset to the decimal (13.5 days, textbook new-project decay). Same math, two labs.

The defibrillator runs on Solana (Best Use of Solana)

The pledge is a Memo-program transaction signed by the user's Phantom wallet:

{
  "protocol": "LIFE-SUPPORT/v1",
  "kind": "REVIVAL_PLEDGE",
  "patient": "ai-recipe-bot",
  "surgeon": "[you]",
  "vow": "I will ship at least one commit before the deadline.",
  "deadline": "+7 days"
}

I deliberately did not write a custom program for this — a memo is exactly enough, and choosing the smallest on-chain footprint that delivers the property you actually need (immutable public accountability) felt more honest than deploying a contract for the résumé value. Verification happens off-chain against the GitHub API. No wallet installed? You get a clearly-labeled practice pledge so the flow is never gated.

The EKGs are honest

The monitors are a hand-written <canvas> renderer that draws the way real patient monitors draw — a moving write head with an erase bar, sweeping at ~25mm/s, P-QRS-T complexes and all. The waveform shape is decorative physiology; the rate, the status, and every number on the chart are real, derived from real commit history. Flatlines are perfectly flat. Critical patients beat weak and slow. It respects prefers-reduced-motion and the beeps are WebAudio, off by default, because I like whimsy but I'm not a monster.

What I learned about myself

My commit history knew things about me that I didn't. My peak commit hour is [02:00]. My passion decays by half every [23] days — but dotfiles, unglamorous, six years old, never decayed at all. Apparently what survives isn't the exciting projects. It's the ones stitched into how I live.

Also: hovering over your own flatlined repo while the tone plays is a genuinely strange emotional experience, and I built the thing.

One repo gets my first revival pledge. The chain is watching now. So are you.

Prize Categories

Best Use of Snowflake
Snowflake is the hospital lab — every diagnosis on the chart is computed as SQL inside the warehouse, not in application code.
The app ingests your full GitHub commit history into a Snowflake table, then runs the entire patient diagnosis as one SQL statement.

Best Use of Solana

Solana is the defibrillator — not a badge, but a commitment device.

Every flatlined repo gets a ⚡ DEFIBRILLATE button. Pressing it signs a Memo-program transaction on devnet with your Phantom wallet:

{
  "protocol": "LIFE-SUPPORT/v1",
  "kind": "REVIVAL_PLEDGE",
  "patient": "ai-recipe-bot",
  "surgeon": "[you]",
  "vow": "I will ship at least one commit before the deadline.",
  "deadline": "+7 days"
}

Why a blockchain, sincerely: you can delete a todo list. You can dismiss a calendar reminder. You cannot quietly un-promise something you signed on-chain. The properties I actually needed — immutability, timestamping, public auditability — are precisely the properties Solana provides. A private database would let me lie to myself, which is the exact failure mode the app exists to fix.

Run yours — I'd honestly love to see your half-life in the comments. ([Repo half-lives under 15 days get automatic sympathy.])*

I built an AI commentator that screams about your sourdough like it's the World Cup final

Arya Koste — Mon, 13 Jul 2026 02:43:54 +0000

This is a submission for Weekend Challenge: Passion Edition

What I Built

Last week my grandpa beat me at chess. Again. He slid his rook across the board, said absolutely nothing, and went to make tea. And I thought: this man just hit me with a tactic he's been setting up for eleven moves, and the only sound in the room was a kettle.

Meanwhile, on TV, a man kicked a ball two meters into an open net and a commentator screamed for thirty consecutive seconds, lost his voice, found it again, and thanked his mother.

That gap felt unfair. So I closed it.

GOLAZO is an AI hype commentator for your life. You describe a moment — any moment — and it gets called like the winning goal of a World Cup final:

Pick your booth: The Legend (measured British gravitas that erupts at exactly the right beat), La Radio (Latin American radio at full throttle — the GOOOOOL is contractually mandatory), or The Poet (golden-age radio lyricism that treats your laundry like the moon landing).
Pick one of nine languages.
Crank the intensity dial. It goes to 10. It should probably not go to 10. It goes to 10.

Then Gemini writes the commentary, it streams onto the screen word-by-word next to a blinking REC dot like a live feed, and ElevenLabs stands up in the booth and roars it out loud.

Here's what it did with my grandpa:

"...Grandpa — seventy-eight years young, cardigan flapping like a cape — slides the rook home! He's done it again! The pawns are weeping, the knights bow their heads, and somewhere a kettle whistles in triumph! CHECKMAAAAAAATE! Legends never retire, my friends — they just play the long game!"

He listened to it twice. He did not smile. He is The Legend.

There's a sincere idea hiding under the joke, though. Passion in football is the commentator — the voice is what turns a ball crossing a line into something people cry about. But that voice only exists for ninety televised minutes. Kids' leagues don't get one. Grassroots matches don't get one. Visually impaired fans watching anything below the top flight usually don't get one. GOLAZO is a tiny, silly step toward a world where every moment gets a voice in the booth — including the small ones. Especially the small ones.

Demo

Here's the booth going live — describe the moment, pick La Radio, dial it to 10, and watch the commentary stream in:

Try it yourself: tap the preset chip "Grandpa beat me at chess again", choose La Radio, intensity 10, and press Hear it. I take no responsibility for what your speakers do next.

Code

👉 Repo: https://github.com/Aryakoste/Golazo

The entire application is one index.html file. No framework. No build step. No backend. No node_modules folder achieving sentience. You could email this app to someone. Please don't, but you could.

How I Built It

The design is a broadcast, not an app. Chalk white, pitch green, ticker yellow, hard black keylines on everything, and Anton at a full italic skew because passion does not stand up straight. There's a scrolling ticker at the top and a blinking REC dot on the output, and the commentary doesn't just appear — it types itself out at broadcast pace, because passion delivered instantly is a paragraph, but passion delivered word-by-word is an event. (Ticker, blink, and typewriter all switch off under prefers-reduced-motion. Hype should be opt-in.)

Google AI (Gemini 2.0 Flash) writes every line via the generateContent REST API, called straight from the browser with the user's own free key (stored only in localStorage — the only servers your data ever touches are Google's and ElevenLabs' own). The whole project lives or dies in one prompt. Each booth has a personality brief — La Radio's literally includes "the climactic word MUST be an extended GOOOOOL-style cry adapted to the moment" — plus the language, the intensity scale, a strict 60–110 word budget, and the single rule I care most about:

Never mock the smallness of the moment. Its smallness is what makes it great.

Without that line, an LLM defaults to gentle irony — it commentates your sourdough with a smirk. With it, the output is sincere, and sincerity is the entire product. Your bread deserves a believer, not a comedian.

ElevenLabs (eleven_multilingual_v2) is the voice, and this took actual tuning. Default voice settings sound like someone reading a weather report. I dropped stability to 0.35 and pushed style to 0.7, and suddenly the delivery got loose, fast, and genuinely excited — less "newsreader," more "man standing on his chair." The multilingual model means a Spanish La Radio call actually sounds like Spanish radio. And if a visitor has no ElevenLabs key, the Web Speech API steps in as the backup announcer, so the demo works for absolutely everyone.

Your last eight commentaries are saved locally as Match Highlights, because some victories deserve a replay.

The hardest bug of the weekend, for the record, was not the AI. It was CSS. It is always CSS.

Prize Categories

Best Use of Google AI — Gemini writes every commentary from a style-briefed, intensity-scaled, sincerity-enforced prompt, in nine languages.
Best Use of ElevenLabs — expressive multilingual TTS, deliberately de-tuned from "newsreader" to "commentator who has completely lost his composure."

Now if you'll excuse me, I have a rematch to lose. Intensity 10 is standing by.

QUERY: the HTTP method we've been faking for 16 years

Arya Koste — Fri, 03 Jul 2026 08:22:17 +0000

HTTP just got its first brand-new method since 2010. Meet QUERY, a GET with a body, or a POST that's finally honest about being read-only.

Every backend dev has hit this moment. You've got a search endpoint. The filters are getting spicy: nested facets, an array of tags, a sort order, a date range. You reach for GET, because searching is reading and reading is a GET, obviously.

Then your query object grows up, your URL crosses two thousand characters, some proxy three hops away quietly truncates it, and you spend an afternoon learning which piece of middleware hates you today.

So you give up and switch to POST. It works. But now you're lying. POST tells every cache, CDN, and proxy on the wire, "careful, this might change something," when all you did was ask a question. No caching for you.

We've been stuck choosing between a verb that can't carry luggage and a verb that sets off the alarm at every checkpoint. For sixteen years there was no third option.

Now there is.

Meet QUERY

In June 2026 the IETF published RFC 10008, standardizing a new HTTP method called QUERY. It's the first genuinely new standard HTTP method since PATCH landed back in 2010, which in web-standards time is roughly an ice age.

The pitch is almost annoyingly simple. QUERY takes the request body from POST and the good manners from GET:

It carries a body, so your gnarly filter object goes where it belongs.
It's safe: the server promises not to change state.
It's idempotent: fire it twice, get the same result, no harm done.
And because of those two promises, it's cacheable.

That last point is the quiet superpower. A cache can look at a QUERY, see that it's safe and idempotent, and reuse the response, something it could never responsibly do with a POST.

What it actually looks like

Nothing exotic. It's a request line you already know how to read, just with a new verb at the front and a body hanging off the bottom:

QUERY /products HTTP/1.1
Host: api.shop.example
Content-Type: application/json
Accept: application/json

{
  "filter": { "category": "boots", "inStock": true },
  "sort": "-price",
  "limit": 20
}

The Content-Type isn't decoration. It tells the server what language your query is written in. JSON here, but nothing stops a resource from speaking JSONPath, a SQL-ish dialect, or some format your team invented on a whiteboard. The URL identifies what you're querying; the body says how.

Notice the response header:

HTTP/1.1 200 OK
Accept-Query: application/json
Cache-Control: max-age=60, private

Accept-Query is the other new thing the RFC introduces. It lets a resource advertise which query formats it understands, the same way Accept-Post works for POST. Self-documenting endpoints, for free.

Wait, haven't we seen this before?

Kind of! If QUERY feels familiar, that's because its great-grandparent is the old WebDAV SEARCH method. The idea of "a read that carries a body" has been circling the standards world for two decades. It just never made it into the HTTP core vocabulary, not until the working group dusted it off, sanded down the rough edges, and gave it a name that says exactly what it does.

And honestly, we've all been simulating QUERY for years. Elasticsearch let you send a body with GET /_search (technically undefined behavior that half the tooling refuses to send) and also offered POST /_search for when that broke. That awkward dance, where you pick your poison and give up either the body or the caching, is precisely the gap QUERY fills.

The one gotcha: caching keys

Here's the detail that'll bite the unwary. When a cache stores a normal GET, the cache key is basically the URL. Two identical URLs, same cached response.

But two QUERY requests to the same URL can have completely different bodies. That's the whole point. So a compliant cache must fold the request body into the cache key. If your cache or CDN doesn't understand QUERY yet, it might key on the URL alone and cheerfully hand user B the results of user A's query. Fun bug. Do not ship it.

The RFC is explicit about this, but your infrastructure has to actually implement it. Which brings us to the part where I gently pump the brakes.

Should you rush this into production?

No. Love the enthusiasm, but no.

QUERY is a proposed standard, published in mid-2026. That means the spec is solid, but the ecosystem is still catching up:

Browsers don't send QUERY from fetch() everywhere yet, and HTML <form> still only knows GET and POST.
Plenty of proxies, WAFs, and API gateways drop or reject methods they don't recognize.
Cache implementations that key QUERY correctly are the exception, not the rule today.

Support like this spreads in years, not weeks. PATCH was standardized in 2010 and still trips over the occasional stubborn gateway.

So treat QUERY the way you'd treat any shiny new protocol feature: understand it, design your API vocabulary with it in mind, maybe reach for it behind your own controlled infrastructure where you own the whole path. But keep that POST /search endpoint around for a while yet.

The takeaway

QUERY isn't flashy. It doesn't unlock anything you literally couldn't do before. What it does is end a sixteen-year-old compromise. It lets you say, right there in the protocol, "I'm asking a question, not changing anything, and here's my complicated question in the body." And for the first time, the caches and proxies on the wire can actually understand you.

It's a small verb with a big job: making read-only requests honest again.

Now if you'll excuse me, I have a few POST /search endpoints to feel guilty about.

Have you started experimenting with QUERY yet, or are you waiting for the ecosystem to catch up? Let me know in the comments.

Filtered Vector Search: Where Every Benchmark Quietly Lies to You

Arya Koste — Thu, 02 Jul 2026 17:52:09 +0000

Let me show you a magic trick every vector database benchmark performs.

Step one: run a query with no filter. Just "find me the nearest neighbors to this vector." Step two: report the gorgeous QPS numbers and the 95% recall. Step three: take a bow while everyone claps.

Here is the query you actually run in production:

nearest neighbors to <embedding>
WHERE tenant_id = 'acme'
  AND status = 'active'
  AND created_at > '2026-01-01'

And here is where the applause stops. Latency triples. Recall quietly falls off a cliff. You ask for ten results and get three, and nobody notices until a user files a ticket that just says "search feels broken." No stack trace. No error. Just vibes, and the vibes are bad.

This is filtered vector search, and it is the single most under-discussed part of the whole retrieval stack. People will argue for three hours about pgvector versus Pinecone and then hand-wave the one thing that actually decides whether their search works: what happens when you bolt a WHERE clause onto an approximate nearest neighbor search.

So let's talk about it. Not which database to buy. The actual mechanics of why filtering a vector search is weirdly, unintuitively hard, the three ways to do it, why two of them fail in exactly opposite situations, and the newer trick that makes a filter actually speed your search up. Stick around for that last part, it's genuinely delightful.

Why your SQL instincts are lying to you

Quick gut check. In a normal database, does adding WHERE status = 'active' make a query faster or slower?

Faster, obviously. You've got an index on status, you look up the matching rows, you scan less stuff. Filtering is a discount. This instinct has served you well for your entire career.

Throw it in the bin. It does not apply here, and understanding why is the whole game.

Vector search over millions of embeddings is only fast because of a structure like HNSW (Hierarchical Navigable Small World). Picture a graph where every vector is a dot, and each dot is wired to its nearest neighbors. A search drops in at an entry point and walks the graph greedily, hopping dot to dot toward your query vector, touching a tiny sliver of the total data. That walk is the magic. It's what turns "compare against all 10 million vectors" into "visit maybe 1,200 of them."

Now add a filter. Suddenly a bunch of dots are off-limits because they don't match tenant_id = 'acme'. But here's the thing: the graph's wiring was built assuming every dot is fair game. Rip out the forbidden dots and you punch holes in the connectivity the walk depends on. The route the search needed might run straight through nodes that no longer exist.

Look at the right side. The path the search wanted to take got cut because the filter deleted the stepping stones. The search is now standing on one side of a river that used to have a bridge. That's the core tension of this entire topic: the index that makes vector search fast assumes nobody's filtering, and every filter is a small betrayal of that assumption.

There are three ways to cope. They are not equally good, and the two obvious ones fail in beautifully opposite ways.

The three strategies, at a glance

Keep this picture in your head as we go. Post-filtering breaks on the right side of the selectivity range, pre-filtering breaks on the left, and only the third one covers the middle where your real queries live. Now the details.

Strategy 1: Post-filtering (the "search now, apologize later" approach)

The obvious move. Run the normal vector search, get your candidates, then chuck the ones that don't match.

# Post-filtering
candidates = ann_search(query_vector, k=100)   # filter? what filter?
results = [c for c in candidates if c.status == "active"][:10]

Simple. No special index magic required. And it's totally fine as long as your filter is loose, meaning most of the dataset passes it. If 80% of your rows are active, your top 100 candidates will contain plenty of active ones. Everybody's happy.

Now watch it detonate. Suppose only 1% of your points match. You pull 100 candidates from the unfiltered search, and on average... one of them is active. You asked for ten results. You got one. The actual ten closest active vectors? Never in the running. They were sitting further out in the graph, politely waiting behind a wall of inactive points that hogged your top 100.

"Just fetch more," you say, sweat forming. "Grab the top 1,000." Sure, sometimes that rescues you. You're also now doing 10x the search work, your latency is climbing, and against a really nasty filter you're still just gambling with extra steps. Over-fetching isn't a fix, it's a bribe you pay the problem to leave you alone, and the bribe scales with exactly how selective your filter is.

Post-filtering dies when filters are restrictive. The more you filter, the more it flails.

Strategy 2: Pre-filtering (the "opposite mistake")

Fine, do the reverse. Find everything matching the filter first, then search only inside that subset.

# Pre-filtering
allowed_ids = metadata_index.lookup(status="active")   # inverted index, etc.
results = ann_search(query_vector, k=10, restrict_to=allowed_ids)

For a restrictive filter this sounds perfect, and for small subsets it genuinely is chef's kiss. If the filter narrows you down to a few thousand vectors, just brute-force the search over those and get exact, high-recall results, fast. This is exactly why good engines have a "if the subset is tiny, skip the fancy graph and just scan it" fallback. Correct call.

But scale that allowed set up and the whole thing flips on you. Remember the graph runs on connectivity. When you restrict the walk to a subset, you're yanking all the non-matching dots out mid-search. On a big dataset where the filter still matches, say, a few hundred thousand scattered points, you fragment the graph exactly like our first diagram: the greedy walk keeps trying to route through excluded nodes, hits dead ends, and either returns garbage or collapses into something slow. The logarithmic magic is gone. You're back to expensive.

So pre-filtering is the exact mirror image of post-filtering. Post handles loose filters and dies on tight ones. Pre handles tiny result sets and dies on large ones. Which leaves a lovely canyon in the middle, a moderately selective filter over a large collection, where both approaches whimper. Guess where basically every real production query lives? The canyon. Everyone lives in the canyon.

Pre-filtering dies when the filtered subset is large and scattered.

Strategy 3: Filter-aware search (the one that actually works)

The grown-up answer is to stop treating the filter as a thing that happens before or after the search, and fold it into the walk itself. The graph traversal still happens, but now the filter rides along and steers: when the search picks which neighbor to hop to next, it's already accounting for the filter instead of ignoring it (post) or being blindly walled off by it (pre).

Two flavors worth knowing, because they map onto real toggles you'll flip in production.

Filter-aware edges, built ahead of time. One approach adds extra edges to the graph based on the fields you'll filter on. For a field like category, the index quietly builds connected subgraphs per value, so when you later filter category = 'laptop', there's already a fully-connected laptop-only graph to walk. Search quality holds up even under tight filters, with basically no runtime tax, because the work happened at build time. The catch is combinations: the index can pre-wire category and brand separately, but it can't pre-wire every category AND brand AND price combo, the math explodes. So one strict filter is smooth, but stack two or three high-selectivity filters and you can still fragment the graph, just fashionably later than you would have.

Adaptive traversal, decided at query time. A newer family (the one you'll hear named in 2026 is ACORN) skips the "know your filters in advance" requirement. The trick: during the walk, if a node's direct neighbors are all filtered out, don't quit, peek at the neighbors of those neighbors. A two-hop jump. This lets the search vault over filtered-out regions and stay connected even for filter combos it never trained for. The honest cost is that exploring more nodes takes more time per query, so you switch this on for the genuinely gnarly cases (complex, unpredictable, low-selectivity filters), not for every lookup. In practice it shows up as a per-query flag, precisely because it's a scalpel, not a bulldozer.

This is the only strategy that covers the canyon. And it comes with a payoff that feels like cheating.

The good part: a filter that makes search faster

With the naive strategies, filtering is pure tax. More work, more latency, more sighing. With real filter-aware search, the opposite can happen: when the filter genuinely shrinks the pool the search has to consider, and the engine prunes that work during the walk instead of after, adding a filter can lower your latency below the unfiltered query.

Look at that green line going down. Reported behavior on integrated engines follows this shape: an unfiltered query sits at some baseline, a 50%-selective filter pulls latency down, and a 1%-selective filter pulls it down further, because the search is simply doing less. That downward slope is the tell of a real filter-aware implementation. It's also a fantastic diagnostic when you're kicking the tires on an engine:

Run your workload filtered, then unfiltered. Watch which way latency moves. If filtering your data makes it faster, the engine is filtering inside the algorithm, that's the good stuff. If filtering reliably makes it slower, it's quietly doing pre- or post-filtering behind your back, and you should plan accordingly.

The gotchas nobody puts in the quickstart

Understanding the strategies is half the battle. The other half is the boring operational stuff that silently wrecks filtered search and never appears in a "hello world" tutorial. Here's where the bodies are buried.

Index your filter fields, and do it BEFORE building the vector index. This one bites everyone once. Filter-aware edges can only be built if the engine knows which fields you'll filter on at build time. Add a metadata index after the vector graph is already built and the filter-aware edges don't magically appear, you have to rebuild the vector index to get them. Rebuilding a graph on a big collection is not a coffee break, it's a "come back after lunch" operation. Order of operations: define your filterable fields, index them, then ingest and build. Future you will send a thank-you card.

Cardinality changes everything, and the engine may swap strategies mid-flight. Good engines estimate how many points a filter will match and pick a strategy per query off that estimate: brute-force the tiny subsets, use the filterable graph for the big ones. Great when it works, but it means your latency profile can shift depending on the specific values a user sends. A filter matching 50 rows and one matching 500,000 rows may run completely different code paths under the hood. So benchmark across the whole range of selectivities you expect, not just one tidy representative query that makes your graphs look nice.

Watch for correlated filters, the silent killer. The genuinely brutal case is when your filter is negatively correlated with vector distance, when the things that match your filter happen to sit far from the query in embedding space. Filter-aware traversal quietly assumes matching points are scattered reasonably near the query. When they're systematically not, even the clever two-hop tricks degrade. If your filtered searches are mysteriously bad and it's not a cardinality thing, ask whether your filter and your embeddings are pulling in opposite directions.

Over-fetching hides bugs. If you "solved" filtered search by cranking your candidate count to the moon, congratulations, you've buried the problem, not fixed it, and you're paying the latency tax on every single query forever. Every so often, check whether you still need that over-fetch or whether proper filter-aware indexing would let you quietly delete it.

A cheat sheet for which strategy you actually want

You usually won't hand-code these, the engine picks, but knowing which one you want tells you what to configure and what to test.

Loose filter (matches most of the data): post-filtering is fine. Go outside, touch grass, don't overthink it.
Tiny subset (a few thousand points): you want the brute-force fallback. Make sure your engine's threshold for triggering it is tuned so it actually fires.
Moderately selective filter over a large collection (the canyon, aka real life): filter-aware indexing, with your filter fields indexed up front. This is the setup most production RAG needs and the one people most reliably botch.
Multiple strict filters, or filters you can't predict: this is where query-time adaptive traversal (the two-hop family) earns its keep. Switch it on for these queries specifically. Don't pay its cost on everything.

The one-line takeaway

The database war everyone loves to fight matters less than the layer underneath it. Two engines with near-identical unfiltered benchmarks can behave like completely different products the second you add a WHERE clause, and your production queries basically always have a WHERE clause. So when you're evaluating anything for real retrieval work, filter it the way your app actually will, and measure both latency and recall against the true filtered nearest neighbors.

Because here's the thing to tattoo somewhere visible:

Unfiltered benchmarks measure a query you will never actually run.

Fine print on the numbers and named techniques: filtered ANN is an active research area as of 2026, and the specific behaviors here (two-hop traversal, per-value subgraphs, cardinality-based planning) are implemented differently across engines and still evolving. Treat this as the conceptual map, then verify the exact behavior against your engine's current docs and, more importantly, against your own data. The selectivity numbers are illustrative of the pattern, not universal constants.

I gave a brand-new AI the memory of all my old chats, here's the free tool I built to do it.

Arya Koste — Wed, 01 Jul 2026 04:40:06 +0000

My AI conversations were scattered across three apps that couldn't remember each other. So I built a private, local-first vault that pulls them together and lets me hand my whole history to any new model. Come break it and tell me what's missing.

Picture this. You spend an hour with ChatGPT untangling a gnarly bug. It's beautiful. You feel understood.

Two weeks later you need that exact solution again. You open ChatGPT and... which of your 300 conversations was it? Was it even ChatGPT? Maybe it was Claude. Or that one Gemini chat you'll never find because it's titled "Untitled."

And here's the part that finally broke me: even when you do find it, the new model you're chatting with today has no idea any of it ever happened. Every AI lives in its own little walled garden with the long-term memory of a goldfish. Switch tools and you start from zero.

So I did the reasonable, well-adjusted thing and built an app about it.

Meet ChatVault

ChatVault is a private home for your AI chat history. You export your conversations from ChatGPT, Claude, or Gemini (they all offer this), drop the file in, and suddenly everything lives in one place you can actually search.

That alone scratched my itch. But then I added the feature I can't shut up about.

The fun part: give any AI your memories

There's a button called Export as memory.

You pick a bunch of conversations or a whole collection and ChatVault bundles them into a single tidy file with a little instruction note at the top: "Treat the following as background knowledge about me and my projects." Paste that into a fresh ChatGPT, Claude, or Gemini chat, and the new model starts the conversation already knowing your context.

It's like handing the new hire a binder of everything the last one learned, instead of making them figure out who you are from scratch every single morning.

It even trims the fat if you want, strips code blocks, condenses long-winded replies, and shows you a live token estimate so your "memory" actually fits in the model's context window. And because it pulls in the private notes you jot on each chat, the AI gets your curated takeaways, not just a raw transcript wall.

What else is in the box

One search bar across every conversation from every tool, with matches highlighted
Collections to group chats by project (so "Memory export" can target just the right ones)
Find in chat for jumping around inside a long conversation
Bookmarked messages - star the good replies, find them later in one view
A snippet library that auto-collects every code block you've ever gotten
Insights - your most-used words, busiest days, and habits, computed on your machine
Password-protected backups with real encryption, because it's your history
Dark mode, keyboard shortcuts, works offline ## The catch (there isn't one, and that's the point)

Here's the thing I'm weirdly proud of: nothing leaves your device. No account. No server. No analytics. No "we value your privacy" popup that means the opposite. Your conversations sit in your own browser and never phone home, ChatVault makes zero network requests, and you can watch the Network tab to prove it.

That's not just a nice-to-have. It's why it can stay free. There's no server bill to pass on to you, because there's no server. Turns out the cheapest backend is no backend.

Okay, now the ask

I built this on nights and weekends, which means it works great on my machine and I would love to know how spectacularly it breaks on yours. Especially:

Did the import work with your export? (Gemini's format is the wild one.)
Is the Export as memory file actually useful when you paste it into a new AI?
What's missing that would make this part of your daily flow? Try it here: https://chat-vault-drab.vercel.app/

Kick the tires, be brutal, tell me everything. And I'm genuinely curious in the comments: what's the one AI conversation you wish you could pull back up right now and which model would you hand your memory file to first?

Choosing a Vector Database in 2026: pgvector vs. Pinecone vs. Qdrant vs. Weaviate vs. Milvus

Arya Koste — Wed, 24 Jun 2026 17:56:49 +0000

Every RAG tutorial pulls the same move. It walks you through embeddings, chunking, retrieval, and then right at the moment of truth it says "now pick a vector database" and just... moves on. Like that's a coffee-order decision. Like you're choosing a font.

It's not. The database you pick decides how fast your queries come back, how much you bleed in infrastructure costs, and how miserable your life gets the day traffic triples. And here's the thing that took me a while to figure out while researching this: the database you start with is often not the one you ship. Teams migrate, sometimes more than once. Some of those moves are clean wins; some are weeks of pain and a postmortem doc.

So let's try to skip the regret. I spent a long time digging through benchmarks, production write-ups, and the trade-offs people only discover after the fact, and this is the guide I wish I'd had when I started: what each of these five (pgvector, Pinecone, Qdrant, Weaviate, and Milvus) is actually good at, where each quietly falls apart, and how to pick without drowning in a feature matrix.

I'll spoil the ending, because it's the most useful thing here: pick based on the infrastructure you already run, not the benchmark you just read. If you're already on Postgres, the answer is probably pgvector and you can almost stop reading. If you never want to touch infrastructure again, it's Pinecone. Everything past that is fine-tuning.

The cheat sheet, for the impatient

If this is you	Use	The one-liner
Already on Postgres, under ~50M vectors	pgvector	One database, zero new problems
Want it to just work, will pay for that	Pinecone	Hand them a key, walk away
Self-hosting and obsessed with speed	Qdrant	The Rust one. It's fast.
Hybrid search is the whole point	Weaviate	Did keyword + vector before it was cool
Heading toward a billion vectors	Milvus	Built for the scale that breaks everything else

Now the actual reasoning.

First, stop staring at the benchmarks

I get the pull. The benchmarks are right there, with their satisfying little bar charts, and one database is 3ms faster than another and that feels like a decision. It mostly isn't. At the scale almost everyone actually operates, every database on this list is fast enough that your users will never feel the difference. The latency war is largely fought over workloads you don't have yet.

What actually decides this, in roughly this order, is four boring questions:

What do you already run? If Postgres is already humming along in your stack (and if you're a full-stack dev, it probably is), bolting on a second database means a sync layer, separate backups, and a whole new thing that can page you at 3am. That gravity is real, and it usually wins.

Do you want to run infrastructure at all? Some people find ops satisfying. Some people would rather light money on fire than configure another cluster. Both are valid. Be honest about which one you are.

How big does this actually get? Under 10 million vectors, genuinely anything works. Between 10 million and a billion, the field thins out fast. Past a billion, you've got maybe two real options.

Do you need hybrid search? This one sneaks up on people. Pure semantic search is great until a user types an exact product ID or a version number and your "vibes-based" retrieval shrugs. More on this later, but file it away.

Answer those four honestly and the database basically picks itself. Here's each one against that lens.

pgvector: the answer that's almost boring enough to be right

pgvector isn't a database. It's a Postgres extension. You teach the database you already have how to do vector search, and that's the whole trick. No new service. No sync layer. No 2am pages from a system you provisioned in a hurry and never fully understood.

Why it's so often the right call. Your vectors sit right next to your actual data, so you can query both in a single transaction, your existing backups already cover them, and filtering is just a SQL WHERE clause: joins, subqueries, the works. The old "Postgres is too slow for vectors" complaint is genuinely outdated; it comes from the bad-old-days IVFFlat era. Once HNSW indexing landed, pgvector started matching dedicated databases at a million vectors, and with the pgvectorscale extension it holds its own well past that, with competitive throughput at 99% recall on tens of millions of vectors. For a huge share of RAG projects this is the right answer, and its only real crime is being unexciting.

Where it starts to hurt. Push past a couple million vectors on one box and index builds start taking twenty-plus minutes, and Postgres's VACUUM process starts elbowing your queries for resources. There's also a subtler trap: pgvector filters after it searches, so a picky filter on a big collection means scanning a pile of candidates to hand you back a handful. Somewhere around 50-100 million vectors you'll be reaching for read replicas, partitioning, or the exit.

Use it if: you're on Postgres, under ~50M vectors, and you don't need to win a latency contest. Most teams are exactly this and don't realize it.

Pinecone: pay money, make the problem disappear

Pinecone basically invented the managed-vector-database category and still sets the bar for it. You get an API key, you make an index, you throw vectors at it, you query them back. There's nothing to size, nothing to tune, nothing to keep alive. That's not a feature list. That's the entire pitch, and it's a genuinely good one.

Why people love it. "I need a vector database and I refuse to think about it any further" is a completely legitimate position, and Pinecone is built precisely for that person. It scales to billions of vectors, it does hybrid search, it's got the enterprise compliance checkboxes. You offload the whole operational headache to someone whose entire job is keeping it up.

The catch (and there's a real one). It's closed-source and there's no self-hosting, full stop. Your data lives in their cloud, and if their pricing shifts or they have a bad day, you have no plan B. The serverless tier swaps latency for convenience and pins your recall at around 90% with no knob to turn. Pinecone just doesn't let you touch the HNSW internals. Writes are eventually consistent, so freshly-added vectors take a beat to show up. Filtering is weaker than SQL (no joins, no subqueries), so anything fancy spills back into your application code. And the bill grows with you, sometimes faster than you'd like.

Use it if: not running infrastructure matters more to you than tuning control, and you've made peace with lock-in as the price of never thinking about this again.

Qdrant: the fast one, and it knows it

Qdrant is open-source, written in Rust, and built from day one to do vector search and basically nothing else. That focus shows.

Why it's appealing. It's the speed leader of the open-source pack, with the lowest p50 latency of the bunch, and the gap actually widens under heavy query load where it matters most. But the real party trick is filtered search: Qdrant runs your filters inside the search traversal instead of bolting them on afterward, so the exact "find me similar shoes, but only the red ones in stock" query that makes pgvector sweat stays snappy here. Add binary quantization that can shrink memory dramatically, plus newer cloud features like GPU-accelerated indexing and multi-AZ failover, and you've got a lot of database for the money. The free tier is the most generous on this list, too.

The honest downside. The ecosystem is younger. You'll find fewer Stack Overflow threads at midnight, fewer random blog posts that happen to solve your exact problem. Though LangChain and LlamaIndex both support it just fine, so you're not in the wilderness. And some teams have reported friction under really heavy concurrent writes, so if you're write-hammering it, test that specifically before you commit.

Use it if: you'll happily run your own infrastructure, you want the best performance per dollar, and fast filtered search is central to what you're building.

Weaviate: the one that wants to be your whole pipeline

Weaviate is open-source too, but it's playing a different game. It doesn't just want to store your vectors, it wants to be the backbone of your entire AI pipeline.

Why it stands out. Two reasons. First, hybrid search, which Weaviate shipped back in late 2022, ages before most of the field caught on. Its implementation is genuinely mature (proper keyword scoring fused with vector results), so if blending semantic and exact-match retrieval is core to your product, this is the most grown-up native option out there. Second, it'll do your embeddings for you: send raw text, and Weaviate vectorizes it on the way in using OpenAI, Cohere, Hugging Face, whatever. Fewer moving parts in your pipeline, which is a real quality-of-life win.

Where it gets heavy. Those built-in vectorizers aren't free. They call the same embedding APIs you'd call yourself, so you're paying that latency and cost, just somewhere less visible. The GraphQL API is a genuine learning curve if your brain is wired for SQL or plain REST. And the Java runtime is hungry when you self-host; operational complexity climbs as you pile on modules and multi-tenancy.

Use it if: native hybrid search is a hard requirement, or you genuinely want the database to handle vectorization so your pipeline has fewer parts to break.

Milvus: bring this one out when things get enormous

Milvus is the most-starred open-source option on GitHub, backed by Zilliz (whose managed Zilliz Cloud is the souped-up enterprise version). It exists for one reason: scale that makes everything else fall over.

Why it earns its place. Nothing else here touches its distributed architecture when you're genuinely big. Heading past a billion vectors? Need GPU-accelerated indexing? This is the tool built for that exact day. At the 100M+ range it's a serious candidate, full stop.

Why you shouldn't reach for it casually. It's a lot of machine. The operational complexity outpaces Qdrant's for normal use cases. Budget real engineering time for the Kubernetes wrangling, and expect your team to climb a learning curve. There's also a known performance gotcha around output fields that can bite in RAG pipelines. If you're under a few tens of millions of vectors, Milvus is almost certainly more database than your problem deserves.

Use it if: you're truly heading into 100M-1B+ territory or need distributed GPU indexing, and you've got the ops capacity to run it.

A quick word on the ones I skipped

ChromaDB earns an honorable mention. It runs right inside your Python process with zero config and is a joy for prototyping. It just doesn't bring the production tooling (high availability, snapshots, real monitoring) the big five do, so think of it as where you start, not where you stay. Faiss (a library, not a database), LanceDB (multi-modal first), Vespa, and the cloud-native managed options like Vertex Vector round out the wider field, but the five above are the ones people actually argue about in production Slack channels.

The hybrid-search thing I keep promising to explain

Here it is, because it quietly decides more choices than people expect. Pure vector search is wonderful right up until someone searches for an exact SKU, a person's name, or "v2.3.1", and suddenly your beautiful semantic embeddings return something thematically adjacent but useless. Real systems need both: the fuzzy semantic match and the exact keyword hit, in the same query.

Weaviate and Qdrant ship this natively. Pinecone bolted it on. pgvector makes you assemble it yourself by hand. If you're building agent memory or RAG over genuinely varied content, treat hybrid search as non-negotiable and let it tilt your decision. It's not a nice-to-have anymore; it's table stakes wearing a trench coat pretending to be a differentiator.

So, what do you actually pick?

If you take one thing from all of this:

You're on Postgres and under ~50M vectors? Use pgvector and go build something. Stop researching.

You never want to see a config file? Pinecone, and make peace with the lock-in.

Self-hosting and you care about speed or filtering? Qdrant.

Hybrid search is the heart of the product? Weaviate.

Staring down hundreds of millions of vectors? Milvus.

And the meta-lesson under all of it: the benchmarks are tie-breakers, not deciders. The database you prototype with probably isn't the one you'll ship, so optimize for the one that's easiest to reason about today and least painful to leave tomorrow. For most teams, honestly, that's pgvector right up until something specific drags them off it. And "something specific" tends to arrive a lot later than the breathless blog posts would have you believe.

One fair warning on the numbers in here: the benchmark figures floating around the industry come from wildly different test setups: different vector dimensions, different hardware, different recall targets, and quite often run by the vendor whose database happens to win. Treat all of it as directionally true rather than gospel, and test against your own data at your own scale before you bet the product on it.

Building a 3D Game in the Browser Humbled Me. Here's Everything That Fought Back.

Arya Koste — Sun, 21 Jun 2026 19:32:38 +0000

This is a submission for the June Solstice Game Jam

Coordinate systems. Rotated bounding boxes. A sine wave cycling 637 times per second. A tribute to Alan Turing hidden in binary light. This is how Solstice Village came to be.

The Idea

June 21. The longest day. Light and darkness at their most dramatic inflection point.

I wanted something that felt like the solstice — not a platformer about suns, not a timer counting daylight seconds. I wanted the quiet tension of a village where every window has gone dark on the longest night, and the warmth that spreads as you, one courier with a lantern, carry light back home to home.

Solstice Village is a 3D exploration game built in Three.js. You play as Sol, walking a circular village, talking to keepers, gathering light at the central brazier, and lighting eight dark homes until the sky shifts from midnight indigo to morning gold.

Play it here: https://aryakoste.github.io/solsticeGame/

What You're Actually Playing

The village is a ring. At the centre: a brazier that flickers. Around it at radius 17 units: eight homes, each dark. Between them at radius 11.5: lamp posts. Beyond the homes: 32 swaying trees, fireflies, a deer, a cat, an owl blinking on a post, and — if you find it — a secret grove with glowing mushrooms and a standing stone.

The main game loop is: Talk → Gather → Deliver → Watch the sky change. Each house lit raises dawnAmount by 1/8. That single float drives everything — sky colour, sun position, fog, ambient light, moon fade. The world literally brightens as you play.

But there is a second ending. If you collect all six spirit wisps scattered around the village without lighting a single home, the game takes a different turn entirely. The village stays dark. The grove awakens. The stone hums. A different piece of narration plays. It rewards the player who ignores the instructions and wanders instead — which felt right for a solstice game, where the night itself has value.

Why 3D on the Web Is a Different Beast Entirely

Most developers who've shipped 2D browser games look at a 3D game and think: it's just one more axis, how much harder can it be?

The answer is: in almost every possible way.

In 2D, your world is flat. Movement is x += vx. Collision is rectangle overlap. Camera is a viewport offset. You render sprites front-to-back and call it done. The computer does what your intuition expects.

In 3D, almost nothing does what your intuition expects.

Everything lives in multiple coordinate spaces at once. Your player exists in world space. The camera that watches them exists in view space. Objects like houses have their own local space, rotated relative to the world. When you need to know if the player is colliding with a rotated house, you can't just compare coordinates — you have to transform the player into the house's local space, do the math there, then rotate the result back. Get any step wrong and the player clips through walls or gets ejected into the sky.

Rotations stop being numbers and become order-dependent operations. In 2D, rotating by 30° then 45° gives the same result as rotating by 45° then 30°. In 3D, the order matters. Rotation around X then Y is not the same as Y then X. This is not a quirk — it's fundamental to how 3D rotations work (they aren't commutative). Every character, every NPC, every camera angle in a 3D game is a product of carefully ordered rotations, and one wrong assumption cascades into every object in the scene pointing the wrong direction.

The camera is its own 3D object, not a window. In 2D you scroll a viewport. In 3D, your camera has a position, an orientation, a field of view, a near clip plane, a far clip plane. A third-person camera orbiting a player requires converting spherical coordinates (yaw angle, pitch angle, distance) into Cartesian (x, y, z). That formula is six trigonometry calls per frame, and if any sign is wrong the camera clips underground, or drifts into the player's head, or spins the wrong direction when you drag the mouse.

Lighting is a full second discipline. In 2D you colour pixels. In 3D, light sources emit in all directions, cast shadows that require their own depth-buffer render pass, bounce off surfaces according to material properties (roughness, metalness, normal maps), and interact with ambient light, hemisphere light, and fog — all simultaneously. Getting a scene to feel right at night, then feel like dawn, requires understanding all of those systems well enough to tune them together.

Time is not a given. In 2D games you often get away with position += speed per frame. In 3D you quickly learn that frame rate varies — a phone runs at 30fps, a desktop at 120fps — and if you animate against raw time without delta-time scaling, your game runs fast on powerful hardware and slow on weak hardware. And even delta-time isn't enough: the specific unit of time matters. Miss a milliseconds-to-seconds conversion anywhere and your animation blows up in ways that look completely inexplicable until you work out the arithmetic.

These aren't beginner mistakes you outgrow. They are the permanent operational cost of building in three dimensions. Every feature you add has to be thought through in all three axes, across multiple coordinate spaces, accounting for arbitrary rotation and variable time. And you discover most of them by shipping a bug.

Here's what Solstice Village taught me.

The Technical Part (Where the 3D Tax Got Collected)

Challenge 1: The NPC That Stared at Walls

Every NPC was placed around the village ring facing away from the plaza — backs to the player, faces to their own house wall. Maddening.

The culprit: Three.js r128's Object3D.lookAt(). This is exactly the kind of 3D convention trap that costs hours. lookAt on any object makes the local −Z axis face the target — the camera convention carried over from OpenGL, where cameras look down -Z by default. When you call grp.lookAt(0,0,0), Three.js rotates the object so its back (-Z) faces the origin. Since the character's face is built at local +Z, every NPC literally showed me their back.

The fix required abandoning lookAt entirely and thinking in terms of the angle I actually needed:

// WRONG — makes local -Z face origin (NPC backs to player)
grp.lookAt(0, 0, 0);

// RIGHT — makes local +Z (the face) point toward origin
grp.rotation.y = Math.atan2(-out.x, -out.z);

Math.atan2(dy, dx) gives the angle of a 2D vector. When you negate both components — (-out.x, -out.z) — you get the angle pointing toward the origin from the NPC's position. Since Three.js character faces have eyes at local +Z, this finally made everyone look at the plaza. The same formula drives NPC head-tracking when you walk close:

// Track player — local +Z toward player
const dx = playerPos.x - n.pos.x;
const dz = playerPos.z - n.pos.z;
n.group.rotation.y = Math.atan2(dx, dz);

Two negations, two formulas, same underlying geometry — just applied in opposite directions. The symmetry is elegant once you find it. Finding it is the hard part.

Challenge 2: The Sine Wave That Cycled 637 Times Per Second

The cat was vibrating. The wisps were strobing. Every frame, the cat's Y position was essentially random — not glitching in some obvious broken way, just wrong, jittering too fast to see what it was trying to do.

The animation code looked fine:

g.position.y = Math.abs(Math.sin(now * 4 + r.phase)) * 0.06;

This is where 3D's time problem came to collect. now came from performance.now() — which returns milliseconds. At 60 fps, now increments by ~16.7 per frame. Math.sin(now * 4) means Math.sin(16.7 × 4) = Math.sin(66.8 radians) per frame. One full sine cycle is 2π ≈ 6.28 radians. So per frame, the animation was completing:

66.8 ÷ 6.28 ≈ 10.6 full cycles per frame

At 60 fps, that's 637 cycles per second. The position was sampling a different, effectively random point on the sine curve every single frame. The cat wasn't jittering — it was animating perfectly at ultrasonic speed. You just can't see 637 Hz with human eyes.

Fix: convert milliseconds to seconds before using as a time parameter:

// Cat bob — multiply by 0.004 = (0.001 to convert ms→s) × (4 Hz frequency)
g.position.y = Math.abs(Math.sin(now * 0.004 + r.phase)) * 0.06;

// Wisp float — explicit ms→s conversion
const t = now * 0.001 + w.phase;
w.orb.position.y = w.oy + Math.sin(t * 1.4) * 0.28;

The firefly animation, written earlier, had correctly used now * 0.001. The roamers and wisps were missing it. One factor of 1000. The difference between a cat that bobs at 4 Hz and a cat that vibrates into another dimension.

Challenge 3: The Camera Orbit

Third-person camera in 3D needs two angles: yaw (horizontal rotation around the player) and pitch (vertical tilt). Converting those spherical coordinates to a Cartesian camera position is one of those formulas you derive, get wrong, stare at, re-derive:

const CAM_DIST = 7.5;
const camYaw = Math.PI; // starts behind player, facing −Z toward plaza

const cx = player.x - Math.sin(camYaw) * Math.cos(camPitch) * CAM_DIST;
const cz = player.z - Math.cos(camYaw) * Math.cos(camPitch) * CAM_DIST;
const cy = player.y + 1.4 + Math.sin(camPitch) * CAM_DIST;
camera.position.set(cx, cy, cz);
camera.lookAt(player.position.x, player.position.y + 1.4, player.position.z);

The Math.cos(camPitch) factor collapses the horizontal offset as pitch increases — when you're looking straight down, the camera is directly above. The Math.sin(camPitch) * CAM_DIST lifts the camera vertically as you tilt up. Both terms together trace a sphere of radius CAM_DIST centred on the player.

Then the movement system has to use that same yaw to map WASD onto world directions, so pressing W always means "forward relative to where the camera is looking":

const wx = Math.sin(camYaw) * fwd + Math.cos(camYaw) * strafe;
const wz = Math.cos(camYaw) * fwd - Math.sin(camYaw) * strafe;
player.rotation.y = Math.atan2(wx, wz);

In 2D this is trivial. In 3D, getting the minus signs right between camera orbit and player movement — so that pressing D strafes right relative to the camera, not world-right — takes real attention.

Challenge 4: Collision Detection Across Rotated Space

Two types of colliders in the world: circular (trees, lamp posts, well, NPCs) and oriented box (rotated houses). Circular collision is manageable:

function _resolveCircle(c) {
  const dx = player.x - c.x, dz = player.z - c.z;
  const dist = Math.sqrt(dx*dx + dz*dz);
  const minDist = playerRadius + c.r;
  if (dist < minDist && dist > 0) {
    player.x += (dx/dist) * (minDist - dist);
    player.z += (dz/dist) * (minDist - dist);
  }
}

Box colliders for houses are the full 3D problem. Each house is rotated to face the plaza — so the box's axes aren't aligned with the world. You can't just compare world-space coordinates. You have to:

Transform the player into the house's local coordinate space
Find the closest point on the axis-aligned box in local space
Compute the penetration depth
Transform the push vector back to world space

function _resolveBox(c) {
  const cos = Math.cos(-c.rotY), sin = Math.sin(-c.rotY);
  const dx = player.x - c.cx, dz = player.z - c.cz;
  // step 1: rotate into box local space
  const lx = cos*dx - sin*dz, lz = sin*dx + cos*dz;
  // step 2: nearest point on box surface
  const px = Math.max(-c.hw, Math.min(c.hw, lx));
  const pz = Math.max(-c.hd, Math.min(c.hd, lz));
  const ox = lx - px, oz = lz - pz;
  const d = Math.sqrt(ox*ox + oz*oz);
  if (d < playerRadius && d > 0) {
    const nx = ox/d, nz = oz/d;
    const push = playerRadius - d;
    // step 3: rotate push back to world space
    player.x += (cos*nx + sin*nz) * push;
    player.z += (-sin*nx + cos*nz) * push;
  }
}

Fourteen lines. Two full rotation transforms. This took longer to get right than any other system in the game — and it's the kind of thing you genuinely cannot debug by guessing. You have to understand the coordinate space transform or you'll never know which of the four signs is wrong.

Challenge 5: Dawn as a Single Variable

The whole sky — background colour, sun height, moon opacity, fog, ambient light, directional light — is driven by one number: dawnAmount, a float from 0 (full night) to 1 (full dawn). This is how you avoid a lighting system that becomes unmanageable. One float. Every system reads it.

// Sky background lerp
const night = new THREE.Color(0x0c1130);
const dawn  = new THREE.Color(0x3a4a82);
scene.background.lerp(night.clone().lerp(dawn, dawnAmount), smoothing);

// Sun rises from underground to sky
const sunY = -12 + dawnAmount * 62; // -12 to +50 units
sunMesh.position.y = sunY;
sunMesh.visible = sunY > -4;

// Moon fades as sun rises
moonMesh.material.opacity = Math.max(0, 1 - dawnAmount * 2.2);

// Scene lighting scales with dawn
sunLight.intensity = 0.35 + dawnAmount * 1.1;
hemi.intensity = 0.7 + dawnAmount * 0.5;

The sun colour shifts from orange to yellow at 40% dawn — mimicking the red horizon of early sunrise shifting to the cleaner yellow of morning:

sunMesh.material.color.setHex(dawnAmount < 0.4 ? 0xff9940 : 0xffe680);

The six wisps scattered around the village each add 8% dawn when collected — a reward for exploration that makes the world respond to curiosity before the main quest requires it. Each wisp also shifts the lantern to its own colour (teal, blue, green) so the light you carry looks different depending on where you've been.

Challenge 6: The Lantern as a Resource, Not a Flag

The original design treated "carrying light" as a binary state — you either had it or you didn't. That worked mechanically, but it meant every trip from the brazier to a home was identical. No tension, no urgency.

The fix was turning the lantern into a fuel system. Light gathered at the brazier fills a lanternFuel float to 1.0. It drains at roughly 1/85th per second — enough for two or three homes per trip at walking pace. As it drains, the lantern physically dims: intensity and opacity both scale with fuel level. The HUD tracks it with colour: gold when full, orange past the halfway point, red and labelled "almost out!" below 20%.

// Each frame while carrying:
lanternFuel = Math.max(0, lanternFuel - dt / 85);
player.userData.lanLight.intensity = 1.8 * lanternFuel;
player.userData.lanMesh.material.opacity = 0.95 * lanternFuel;

if (lanternFuel <= 0) {
  _clearLantern();
  SV.ui.toast('The light faded — return to the brazier');
}

The brazier itself now reacts to how much of the village you've lit. Its flame scales up ~90% in size by full dawn, and its point light gets 70% brighter. The first time you come back to refill and notice the brazier has grown, it feels like the village is waking up with you.

Everything That Made the World Feel Alive

On top of the core systems:

28 fireflies drifting on parametric Lissajous-style curves: x = ox + sin(t × speed) × rx, z = oz + cos(t × 1.3) × rz — the asymmetric frequencies mean they never loop in a straight line
Occasional shooting stars that spawn at a random point on the sky sphere, trail five fading ghost spheres, animate with requestAnimationFrame, and clean themselves from the scene after 1.2 seconds
Aurora band — 12 semi-transparent planes arranged in a ring at radius 70, each tilted slightly differently for an irregular shimmer
1,200 star particles in a single BufferGeometry draw call
Particle burst system — pool of sphere meshes with velocity and gravity, fading by life fraction, spawned on house lighting
Chimney smoke — every lit home emits slow expanding grey spheres from its chimney top every 0.75 seconds, growing as they rise and fading out, making lit homes visible from across the village
Bell on house lighting — a deep resonant bell rings (four harmonics: 110 Hz, 220 Hz, 440 Hz, 880 Hz, each with a 3.2-second exponential decay) underneath the chord stab, so lighting a home sounds like an event
Footstep audio — alternating low tones (78 Hz / 68 Hz) timed to walking pace via a step timer, faster when running. All Web Audio API, no sound files
Web Audio API ambient drone — five overlapping sine oscillators at 55 Hz, 82.4 Hz, 110 Hz, 164.8 Hz, and 220 Hz (a harmonic series), each with decreasing gain
Touch joystick — thumb delta clamped to 46px radius, normalised to ±1, rotated through camera yaw before being applied to movement
Minimap — Canvas 2D drawn every frame: houses as 8×8px squares (dark until lit, gold with glow when lit), NPC positions as dots, player as a filled triangle rotated to match camera yaw
House interiors — enter any lit home: a full room with ceiling beams, a hearth with animated flame cones, warm flickering point light, a table, a bookshelf, and a rug. Each keeper has a note left on the table — Ash's has a bread recipe, Tovar's has a watchman's log, Mira's has three letters of SOLSTICE written in binary
NPC cross-references — each keeper mentions another by name in their opening line, so the village feels like people who know each other rather than eight isolated quest-givers
NPC dawn gathering — past 50% dawn, all eight keepers slowly walk toward the plaza and face the brazier. At full dawn they're clustered together in a silent celebration
Cat follows you — approach the cat and press E; it trails behind you for the rest of the game. The deer does the opposite: get within five units and it startles, flags a flee direction, and runs at four times its normal speed until you're ten units away
Standing stone reacts to progress — at zero homes lit the stone is cold. Past four it glows. At all eight, the Turing inscription appears
8 unique NPCs with different skin tones, hair styles, and dialogue arcs that change after their home is lit
Tree sway — rotation.z and rotation.x oscillating at slightly different frequencies per tree so they never move in sync

Code

Aryakoste / solsticeGame

Solstice Village

A 3D exploration game built for the June Solstice. You are Sol, the courier. The longest night has fallen and every window in the village has gone dark. Gather light at the central brazier and carry it home to home until the sky turns gold.

Play it here →

Gameplay

Talk to each of the 8 keepers to learn their story
Gather light at the plaza brazier — your lantern holds ~85 seconds of flame
Carry the light to dark homes and deliver it
Watch dawnAmount rise from 0 to 1 as the village lights up — every system in the game (sky colour, sun height, fog, moon fade, brazier size, NPC behaviour) is driven by this single float

There is a second ending. Collect all six spirit wisps scattered around the village without lighting any homes, and the game takes a different path.

Controls

Input	Action
`W`

…

View on GitHub

Prize Category

The Alan Turing Prize Category

One of the NPCs, Mira the clockmaker, says this when you approach her dark house:

"Every lit window is a 1, every dark one a 0. Light mine and we add a bit to the dawn."

That's not just flavour text. At the top of the screen runs a binary strip that displays the ASCII value of each letter in "SOLSTICE" — one letter per house you light. When Bell's house lights up, the strip fills in 01010011 (S = 83). When Fen's lights up, it fills 01001111 (O = 79). Eight houses. Eight letters. Eight bytes spelling out the word in light.

S = 01010011
O = 01001111
L = 01001100
S = 01010011
T = 01010100
I = 01001001
C = 01000011
E = 01000101

And in the secret grove at the northeast edge of the map, a standing stone reads:

"Beneath the runes, a name: TURING. And below it — ones and zeros."

Binary as metaphor for light. Light as computation. Every dark window a zero waiting to be flipped.

Google AI in the Process

Google AI Studio and Gemini were part of the development loop throughout — helping reason through Three.js's coordinate conventions, sanity-checking the spherical camera orbit math, and catching the milliseconds-to-seconds unit mismatch before it became a harder bug. When I described the NPC-facing problem, Gemini confirmed the camera-convention issue with lookAt and helped verify the atan2 formula direction before I changed code. The kind of quick second opinion that saves an hour of trial and error at midnight.

Play It

Works in any modern browser, desktop and mobile.

Controls:

WASD / left joystick — move
Shift — run
Click + drag, or touch the right side of the screen — rotate camera
E / Talk button — interact with NPCs, brazier, homes, wisps

Find the secret grove in the northeast. Read the standing stone — it says something different depending on how many homes you've lit. Pet the cat. Let the deer startle away from you. Light all eight homes and watch the sky turn.

Or don't light any of them. Collect all six wisps instead, and see what the night has to say.

The longest night ends. That's what the solstice is: not the absence of light, but the moment right before it comes back.

#gamedev #javascript #threejs #webdev

ClawCraft: Bringing a Full Visual Studio to OpenClaw 🛠️

Arya Koste — Sat, 25 Apr 2026 22:21:00 +0000

This is a submission for the OpenClaw Challenge.

Building OpenClaw skills is an incredibly powerful way to automate workflows across messaging platforms. But let's be honest: managing them locally, writing YAML/JSON boilerplate, ensuring they are safe to run, and debugging failures without a proper environment can require more context-switching than we'd like.

So, for this developer challenge, I set out to build ClawCraft, a comprehensive local development environment and companion skill specifically designed for OpenClaw.

ClawCraft isn't just a basic tool—it's a powerful Command Line Interface (CLI), a local web dashboard (Client UI) running a Fastify backend server, and an OpenClaw Skill. It allows you to build, scan, debug, and manage your skills without ever touching code—unless you want to.

⭐ Check out the GitHub Repository here! ⭐

🎨 The Client UI: A Beautiful Local Dashboard

First and foremost, ClawCraft launches a sleek, React-based web dashboard locally on your machine. This is your command center.

Instead of messing around with local folders, strict syntax, and terminal logs, the Client UI gives you a visual overview of every OpenClaw skill you have installed, the ability to trigger API commands instantly, and access to all the core developer tools right from your browser.

🔥 Headline Features

1. 🏗️ Visual Skill Builder

Why write boilerplate when you can just drag and drop? The intuitive Client UI uses @dnd-kit to let you string together the logic of your OpenClaw skills visually. For power users who still want granular control over their code, there's a fully integrated Monaco code editor providing a rich, IDE-like fallback experience.

2. 🤖 AI Skill Generation

Have an idea but don't want to drag blocks or write code? Tell ClawCraft what you want! Powered by Anthropic and OpenAI SDKs directly in the backend, you can just type a natural language prompt (e.g., "Make a skill to fetch top 3 hacker news articles"). The AI will scaffold the entire OpenClaw skill structure, parameters, and logic for you instantly.

3. 🚨 Built-in Security Scanner with Trust Scores

You shouldn't just run random skills you find online blindly on your system. ClawCraft includes an automatic security scanner that analyzes any external skill (via URL or name), scanning the implementation logic, and summarizing exactly what it is attempting to do.
The scanner returns a Trust Score directly in the UI:

✅ Safe
⚠️ Review Required
🚨 Dangerous (Do not install!)

4. 🪲 Live Debugger

Testing an OpenClaw skill but it's failing silently in Slack or Telegram? Launch the local debugger dashboard. ClawCraft lets you inspect variables, view the actual HTTP payloads, and trace exactly where the flow broke in real-time.

💻 The Command Line Interface (CLI)

Prefer living in the terminal? You can control your entire OpenClaw setup using the native CLI. Under the hood, this uses commander.js and provides beautifully formatted output.

Here are the commands you have at your disposal:

clawcraft start [--port] [--no-open] - Starts the local Fastify backend and launches the React dashboard.
clawcraft list - Lists all currently installed skills along with their security trust score badges.
clawcraft generate <description> - Uses LLM integrations to immediately scaffold and format an entire SKILL.md file from a single sentence request.
clawcraft scan [target] - Scans all local skills, or a specific skill by URL or name, for malicious patterns and returns the Trust Score and findings list.
clawcraft install <url> [--force] - Scans an external repository and installs it securely. Prompts if it's considered dangerous unless --force is used!
clawcraft fix <skillName> - Immediately opens the browser UI directly to the local debugger for the specified skill.
clawcraft improve <skillName> - An automated AI flow that attempts to rewrite your skill with better guardrails, optimized permissions, and deterministic instructions, and prompts to save!
clawcraft config [get/set] - Read and modify the configuration such as adding API keys safely.

🤯 The Meta Feature: The ClawCraft OpenClaw Skill

Yes, ClawCraft comes with its own native, companion OpenClaw skill (clawcraft tag) within the repo!

Once your local ClawCraft server is running, you can manage your entire OpenClaw development environment directly from Slack, Discord, Whatsapp, or Telegram using slash commands. It's wildly satisfying to build OpenClaw skills using an OpenClaw skill.

/clawcraft build "get current bitcoin price" - Automatically opens your UI and uses AI to generate the skill for you!
/clawcraft scan {skill-url} - Scans the repository for the Trust Score and reads it back to you right in the chat.
/clawcraft list - Returns a list of all your installed skills.
/clawcraft search "find templates" - Searches available community templates and installed skills.
/clawcraft status - See how many times your skills have fired and the estimated time they've saved you!

🛠️ Tech Stack & Architecture

ClawCraft is structured as a modern JavaScript monorepo using npm workspaces:

Frontend (packages/client): React 18, Vite, TailwindCSS for styling, @dnd-kit for drag-and-drop visuals, and Monaco Editor.
Backend (packages/server): A lightning-fast Fastify server providing the core OpenClaw system APIs.
CLI Toolkit: Powered by Commander.js and Chalk.
AI integrations: Native SDK integrations for both Anthropic and OpenAI logic generation.

🚀 Quick Start (Running from Source)

ClawCraft is designed to be cloned and run directly from the source to give you absolute control over your local environment. Here is how you can spin everything up:

# 1. Clone the repository
git clone https://github.com/Aryakoste/ClawCraft.git
cd ClawCraft

# 2. Install dependencies (This securely installs both client and server via npm workspaces)
npm install

# 3. Start the application
npm run dev

(Running npm run dev kicks off a script that concurrently boot up both the Fastify server on port 4000 and the Vite Client UI dashboard simultaneously!)

Some Screenshots for UI

Skill Generator

Template Gallery

Skill Debugger

Skill Composer

Usage Tracker

🧠 Configuring the AI

ClawCraft's powerful generator (clawcraft generate and clawcraft improve) relies on an LLM to do the heavy lifting. You can configure it to use Anthropic, OpenAI, local Ollama endpoints, and more.

Use the built-in CLI to easily securely set your keys and providers (saved locally to ~/.clawcraft/config.json):

# Set your core provider (anthropic, openai, ollama, openai-compat, openclaw)
clawcraft config set llmProvider anthropic

# Provide your authentication key
clawcraft config set apiKey "sk-ant-xxxxxxxxxx"

# Set your preferred model version (Defaults to sonnet!)
clawcraft config set model "claude-3-5-sonnet-20241022"

Once configured, point your messaging app to the local dashboard (http://localhost:4000), load up the skill/ directory, and start giving it slash commands!

Final Thoughts 💭

I loved exploring how endlessly hackable OpenClaw is during this challenge. My primary goal with ClawCraft was to significantly lower the barrier to entry for creating, auditing, and installing those skills. I firmly believe that making OpenClaw visual, secure, and easily manageable will help onboard a lot more non-developers into the AI automation space.

Would love any thoughts, PRs, or feedback from the community!

Drop a ⭐ on the Repo or try it out!

I Put Carbon Pledges on the Solana Blockchain for Earth Day (And Built the AI to Back It Up)

Arya Koste — Sun, 19 Apr 2026 20:00:48 +0000

This is a submission for Weekend Challenge: Earth Day Edition

Did you know that a single cheeseburger emits roughly 3.5 kg of CO₂? That's equivalent to driving 14 km in a petrol car — from a sandwich.

Most of us have no idea what our daily choices actually cost the planet. And even when we do, knowing isn't enough. What if you could prove you're changing — publicly, permanently, on the blockchain?

EcoLens is an AI-powered carbon footprint analyzer that goes beyond awareness. It identifies your impact, proposes greener alternatives, and lets you pledge your commitment on the Solana blockchain — a public, immutable record that your word is real.

The Problem

Carbon footprint calculators exist, but they're tedious. You fill out a form, pick from dropdowns, hit calculate, and get a vague yearly number that means nothing to your Tuesday lunch decision.

The real gap isn't information — it's accountability. People know beef is carbon-heavy. They still order it. What changes behavior is a commitment with skin in the game.

That's the loop I wanted to close: identify → understand → pledge → act.

What EcoLens Does

📸 Vision Analysis

Upload any image — your meal, a shopping receipt, your car, a product — and Gemini 2.0 Flash analyzes it using real lifecycle emissions data. You don't describe anything; just point your camera.

✍️ Text & Voice Analysis

Type or speak a description:

"I flew economy class from Mumbai to London"
→ 1,850 kg CO₂ · Very High Impact · Equivalent to driving 7,400 km

⚖️ Compare Mode

Can't decide? Compare two options side by side — "beef burger vs. black bean burger" — and see exactly how many kg CO₂ you save by choosing the greener option, with a winner crown.

🌿 Structured Results

Every analysis returns:

CO₂ in kg, severity rating, animated breakdown by source
3 specific, actionable alternatives with estimated savings
A relatable real-world equivalent

◎ Solana On-Chain Pledges ← the key differentiator

After every analysis, you can sign a pledge with your Phantom wallet. The commitment is written as a Memo transaction on Solana — permanent, public, tied to your wallet address.

🤖 Streaming AI Agent

A persistent chat powered by Gemini that streams responses token-by-token, secured behind Auth0.

📊 Carbon Budget + History

Set a weekly CO₂ budget. Every analysis is saved to localStorage, tracked against your goal, and visualised in a circular progress meter.

The Tech Stack

Layer	Choice	Why
Framework	Next.js 15 (App Router)	Server components + API routes in one repo
AI	Google Gemini 2.0 Flash	Vision + text + streaming, accurate emissions data
Auth	Auth0 for Agents	Protects AI endpoints, user identity scoping
Blockchain	Solana (Devnet)	On-chain pledge via Phantom + Memo Program
Animation	Framer Motion	Smooth result reveals, animated CO₂ bars
Styling	Tailwind CSS	Custom dark earth-tone design system

How I Used Google Gemini

Gemini is the brain of EcoLens — it handles both image analysis and chat via gemini-2.0-flash.

The key insight was engineering a structured output contract. The model always returns valid JSON so the UI can render rich cards without parsing gymnastics:

const ANALYSIS_PROMPT = `You are EcoLens AI, an expert environmental scientist.
Analyze the input and return ONLY valid JSON:
{
  "carbonKg": number,
  "category": "food" | "transport" | "energy" | "shopping" | "waste" | "other",
  "title": string,
  "summary": string,
  "breakdown": [{"label": string, "kg": number, "percentage": number}],
  "alternatives": [{"action": string, "impact": string, "reduction": string}],
  "equivalent": string,
  "severity": "low" | "medium" | "high" | "very_high",
  "rating": number
}`;

For image analysis, the image and prompt go in a single multimodal API call:

const parts: Part[] = [
  { inlineData: { data: imageBase64, mimeType: file.type } },
  { text: "Analyze the carbon footprint of everything in this image." },
];
const result = await model.generateContent({
  contents: [{ role: "user", parts }],
  generationConfig: { temperature: 0.3 }, // low temp = consistent scientific estimates
});

The AI chat uses streaming via sendMessageStream — responses type out token-by-token with a blinking cursor, making it feel alive:

export async function* streamChatWithEcoAgent(message, history) {
  const result = await chat.sendMessageStream(message);
  for await (const chunk of result.stream) {
    if (chunk.text()) yield chunk.text();
  }
}

The API route pipes this directly into a ReadableStream response — no buffering, no delay.

How I Used Auth0 for Agents

Every call that touches the Gemini AI is gated by Auth0 before the agent acts. This is the "Auth0 for Agents" pattern: the AI doesn't act anonymously, it acts on behalf of a verified identity.

// app/api/analyze/route.ts
export async function POST(req: NextRequest) {
  const session = await getSession();

  if (!session?.user) {
    return NextResponse.json({ error: "Authentication required" }, { status: 401 });
  }

  // Agent acts on behalf of session.user.sub — traceable, auditable
  const analysis = await analyzeCarbon(text, imageBase64, imageMimeType);
  return NextResponse.json({ analysis, analyzedBy: session.user.sub });
}

The same gate protects /api/chat and /api/compare. No anonymous AI calls — every analysis is tied to a real, verified person.

How I Used Solana — The Heart of the Accountability Loop

This is the part I'm most excited about, and the piece that makes EcoLens more than just another carbon calculator.

The idea: awareness without commitment changes nothing. Solana lets us make commitments permanent and public.

The Flow

Gemini analyzes your activity and suggests a greener alternative
You click "Sign pledge with Phantom"
EcoLens constructs a Memo transaction encoding your pledge, the CO₂ saved, and a timestamp
Phantom signs and broadcasts it to Solana Devnet
The transaction is confirmed on-chain — your pledge is now permanent

import {
  Connection, PublicKey, Transaction,
  TransactionInstruction, clusterApiUrl,
} from "@solana/web3.js";

const MEMO_PROGRAM_ID = new PublicKey("MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr");

const memoData = JSON.stringify({
  app: "EcoLens",
  pledge: "I pledge to: cycle instead of drive this week",
  carbonKg: 2.4,
  ts: new Date().toISOString(),
});

const tx = new Transaction().add(
  new TransactionInstruction({
    keys: [{ pubkey: publicKey, isSigner: true, isWritable: false }],
    programId: MEMO_PROGRAM_ID,
    data: Buffer.from(memoData, "utf-8"),
  })
);

const { signature } = await window.solana.signAndSendTransaction(tx);
await connection.confirmTransaction({ signature, blockhash, lastValidBlockHeight });

The pledge is verifiable on Solana Explorer. Anyone can look up your wallet and see your carbon commitments, timestamped and immutable.

Why the Memo Program?

The Solana Memo Program (MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr) is the simplest, cheapest way to write arbitrary data on-chain. A pledge transaction costs a fraction of a cent in SOL and is confirmed in ~400ms. It's perfect for this use case — lightweight, auditable, and human-readable.

Why This Matters Beyond the Demo

Carbon pledges have a trust problem. Corporate net-zero commitments get announced and quietly abandoned. There's no receipt. Solana changes that: your pledge is a transaction hash. It can't be edited, deleted, or denied. Future versions of EcoLens could build a public leaderboard of wallets with the most on-chain green commitments — turning individual accountability into social proof.

A Real Example: From Analysis to On-Chain Pledge

Here's the full EcoLens loop in action:

1. User uploads photo of beef steak dinner
   → Gemini Vision: 6.8 kg CO₂ · High Impact

2. Breakdown:
   Beef (production)    ████████  5.2 kg (76%)
   Cooking energy       ██        0.9 kg (13%)
   Transport/packaging  ▌         0.7 kg (11%)

3. Equivalent to: Driving 27 km in a petrol car

4. Top alternative: "Choose chicken instead — Save ~4.1 kg CO₂"

5. User clicks "Sign pledge with Phantom"
   → Phantom signs memo transaction
   → Confirmed on Solana Devnet in 412ms
   → TX: 3xK7...mNpQ (verifiable on Explorer)

That's the full loop — from a photo to an on-chain commitment in under 30 seconds.

What I Learned

Structured outputs unlock rich UIs. Getting Gemini to reliably return JSON meant the frontend could be fully reactive — no parsing edge cases, no streaming text parsing hacks.

Temperature matters for science. At 0.7, CO₂ estimates drift between calls. At 0.3, they're reproducible and match published lifecycle data.

Solana's Memo Program is criminally underused. It's the simplest on-chain data primitive — 0.000005 SOL per transaction, confirmed in milliseconds, human-readable on Explorer. For any app that needs verifiable records, it's a better solution than most people realize.

Auth-gating AI is a pattern, not an afterthought. Making the AI agent require Auth0 session means every analysis is tied to a real identity — which is the foundation for future per-user carbon portfolios and wallet-linked pledge histories.

Try It Yourself

Aryakoste / ecolens

🌍 EcoLens

AI Carbon Footprint Analyzer with On-Chain Pledges

Snap a photo of your lunch, describe your commute, or upload a receipt — EcoLens uses Google Gemini Vision to instantly reveal the hidden CO₂ cost of your daily choices. Then pledge to do better on the Solana blockchain — a permanent, public, verifiable commitment.

✨ Features

Feature	Description
📸 Vision Analysis	Upload any photo — Gemini Vision identifies items and calculates CO₂
✍️ Text Analysis	Describe any activity and get an accurate, sourced emission estimate
🎙️ Voice Input	Speak your description using the browser's Speech API
⚖️ Compare Mode	Race two options side by side — see the greener choice with a winner crown
◎ Solana Pledges	Sign an on-chain pledge with Phantom — permanent, immutable, verifiable
🤖 Streaming AI Chat	Gemini-powered eco-agent that streams responses token-by-token
📊 Carbon Budget	Set a weekly CO₂ goal and track it against a

…

View on GitHub

git clone https://github.com/aryakoste/ecolens
cd ecolens
cp .env.local.example .env.local
# Add GEMINI_API_KEY, Auth0 credentials
npm install
npm run dev

To test the Solana pledge feature, install Phantom wallet and switch it to Devnet in settings.

What's Next

[ ] Mainnet pledges — real SOL-backed carbon commitments with token rewards for follow-through
[ ] Public pledge leaderboard — on-chain wallet rankings for green commitments
[ ] NFT certificates — mint a Solana NFT when you hit a weekly carbon goal
[ ] Snowflake analytics — aggregate anonymized emissions data across all users for community insights

Prize Categories

Prize	Technology	How it's used
Best use of Solana	`@solana/web3.js` + Phantom	On-chain carbon pledges via the Memo Program
Best use of Google Gemini	Gemini 2.0 Flash	Vision analysis, structured JSON output, streaming chat
Best use of Auth0 for Agents	`@auth0/nextjs-auth0` v3	Auth-gates every AI endpoint — the agent acts on behalf of a verified identity

Every gram of CO₂ you avoid is a gift to the planet. And now, you can prove it. Happy Earth Day 🌍

Built with Google Gemini 2.0 Flash, Auth0 for Agents, and Solana for the DEV.to Earth Day Challenge 2025.

I Built a Government-Grade Button Clicking Certification Program (Because the World Needs It)

Arya Koste — Tue, 07 Apr 2026 16:47:36 +0000

This is a submission for the DEV April Fools Challenge

⚠️ NATIONAL CLICK THREAT LEVEL: ELEVATED

Let me ask you something.

You use buttons every day. Login buttons. Submit buttons. "Accept all cookies" buttons (without reading a single word). Elevator buttons. Crosswalk buttons that don't actually do anything.

But have you ever been certified to click those buttons?

No. You haven't. And frankly, it's reckless.

That's why I built the International Bureau of Button Clicking Certification (IBCC) — a fully interactive, deeply useless, government-bureaucracy-themed web application that puts you through six increasingly absurd examinations to determine if you are, in fact, qualified to press a rectangular area on an illuminated screen.

🏛️ Why Button Clicking Certification Matters in 2026

Let's look at the facts:

The average knowledge worker clicks 4,217 times per day. That's over 1.5 million clicks per year — completely unregulated.
Zero countries currently require a clicking license. Zero. Not even Switzerland, and they regulate everything.
In 1987, a single misclick at the Pentagon accidentally ordered 40,000 rubber ducks. This is not in any official record because they covered it up. But I believe it happened.
Self-driving cars are regulated. Surgeons are licensed. Barbers need a certificate. But the person clicking "Deploy to Production" on a Friday at 4:59 PM? No credentials required. Think about that.

The click economy is booming. AI is automating everything except clicking. If anything, we need more human clickers than ever. And yet, the industry has no standards, no oversight, and no governing body.

Until now.

The IBCC was established in 1847 (citation needed) and has been monitoring global click activity from a basement somewhere ever since.

🖱️ What I Built

A single-page HTML/CSS/JS application that is equal parts:

DMV waiting room (the aesthetic)
Escape room (the challenges)
Fever dream (the experience)

The Core Experience

You land on the page and you're greeted by an official government seal, a scrolling threat-level ticker, and a giant 3D red button that is begging to be pressed.

Every click is tracked. Every click is logged. Every click brings you closer to certification — or further from sanity.

The Stats Dashboard

Because no government bureau is complete without meaningless metrics:

Total Clicks — the only number that matters
Clicks Per Second — your raw throughput
Accuracy™ — a completely fabricated percentage that goes up the more you click, because we believe in positive reinforcement
Click Power — a multiplier that grows every 100 clicks, achieving absolutely nothing

The Clearance Level System

As you click, you ascend through increasingly dramatic security clearances:

Clicks	Clearance Level
0	UNCLASSIFIED
10	CONFIDENTIAL
50	SECRET
150	TOP SECRET
400	COSMIC TOP SECRET
800	ULTRA MEGA SECRET
1,500	BEYOND CLASSIFICATION
3,000	CLICK DEITY

Each level has its own color, its own glow, and its own sense of hollow accomplishment.

The Six Certification Examinations

This is where it gets interactive. Each exam unlocks at a certain click threshold and tests a completely useless skill:

EXAM 1: Speed Clicking Qualification
Click 20 times in 5 seconds. Prove you are not, in fact, a sloth. This is your warm-up. If you fail this, the Bureau recommends a different career path (perhaps data entry, where the stakes are somehow even lower).

EXAM 2: Precision Click Assessment
Five targets appear on screen. They shrink. You must hit them. Missing is described as "a federal offense" in the fine print (it isn't, but the guilt is real). The targets get smaller with each hit because the Bureau believes in escalating psychological pressure.

EXAM 3: Patience Endurance Trial
Hold a button for exactly 7.0 seconds. Not 6.5. Not 7.8. Seven. There's a ±0.5 second tolerance because the Bureau is generous (they aren't, but the lawyers insisted). This exam has a 73% failure rate among developers because we are physically incapable of waiting for anything.

EXAM 4: Rhythmic Click Synchronization
A circle pulses. You click when it lights up. It's like Guitar Hero but with a single button, no music, and no fun. Score 6 out of 10 to pass. The Bureau considers anything below that "arrhythmic clicking" which is, apparently, a diagnosable condition.

EXAM 5: Morse Code Transmission
Tap out S.O.S. in Morse code (short-short-short, long-long-long, short-short-short). This is the exam where most people realize they have no idea what Morse code actually is, despite confidently claiming otherwise at dinner parties.

EXAM 6: The Trust Exercise
This is my favorite. A big red button appears. It says "DON'T CLICK." You must resist for 10 seconds. While the system actively taunts you:

"Come on, just one little click..."
"Nobody's watching... 👀"
"Your finger is already moving, isn't it?"
"Other test subjects all failed at this point..."

If you click it, a giant "DENIED" stamp slams across your screen. You deserve it.

Bonus Chaos

Because six exams weren't enough:

Combo System: Click fast enough and a combo counter appears. Hit 20x for the "UNSTOPPABLE" achievement.
13+ Achievements: From "First Click" (participation trophy energy) to "CERTIFIED CLICKER" (you completed all exams and should probably go outside).
Random Events: A 3% chance per click that the system flags you with alerts like "SUSPICIOUS CLICKING PATTERN DETECTED" or "Agent #404 is now monitoring this session."
The DENIED Stamp: Randomly slams across your screen with a satisfying animation, just to keep you on your toes.
Particle Explosions: Every click spawns emoji particles. Higher combos = more particles. Your screen will look like a New Year's Eve celebration at a bureaucratic office party.
Confetti: At every milestone (10, 50, 100, 500, 1000 clicks), confetti rains down. Because positive reinforcement is free.
Secret Keyboard Shortcuts:
- D — Activates Dance Mode (the entire page starts shifting through hue rotations while the button spins maniacally)
- T — Thermal Vision (high saturation + contrast, makes the button look like a heat signature)
- S — Secret bonus: awards 50 clicks instantly and fires confetti

The Certificate

Complete all six exams and you receive an official Certificate of Completion — a parchment-textured, gold-bordered, absolutely meaningless document that declares you a "Certified Professional Button Clicker (CPBC)."

It includes:

Your name (you get to type it in, very official)
A 3D rotating trophy
A stamp in the corner that reads "VERIFIED USELESS"
A statement that the certificate "carries absolutely no legal weight in any jurisdiction, real or imagined"
A note that it's valid for 0 days

🛠️ Technical Decisions (and Regrets)

Pure HTML/CSS/JS. No frameworks. No build tools. No npm install. Just one file and vibes. If a government bureau from 1847 could build a website, they wouldn't use React either.

CSS 3D transforms for the button (it has actual depth with a translateZ based top and side), the trophy rotation, and the certificate reveal animation.

Pure CSS animations everywhere — the scanning ticker, the seal rotation, the shimmer on progress bars, the particle system, the combo pop, the stamp slam. Sixty percent of the code is CSS, which feels appropriate for something that accomplishes nothing.

No external dependencies. Just Google Fonts. The Bureau doesn't trust third-party packages (honestly, neither should you).

🤖 Google AI: The Bureau's Secret Intelligence Division

Gemini for Ideation

Honestly, half the challenge ideas came from brainstorming with Gemini. I started with "speed clicking test" and asked it to push the absurdity further. The Morse Code SOS exam and the Trust Exercise (where you have to NOT click a button for 10 seconds) were both born from those conversations. Gemini is genuinely great at "yes, and" — give it a silly premise and it will escalate it with you.

Why Gemini Specifically

For a project this stupid, I needed an AI that could commit fully to the bit without constantly trying to be helpful or breaking character with disclaimers. Gemini handled the deadpan tone better than I expected — it never once tried to inform me that button clicking certification isn't real, which I respect deeply.

I also used Gemini to help workshop the bureaucratic tone — the fake fun facts, the threat-level ticker messages, the achievement names. When you need 12 variations of "fake government propaganda about clicking," an AI is genuinely the right tool for the job.

What surprised me: Gemini was really good at the deadpan humor. I expected it to play things safe, but when I told it to commit fully to the bit and write like a 1980s instruction manual that had lost its mind, it delivered.

📋 Form CL-7042: Closing Remarks

Look, I know what you're thinking: "This is completely useless."

Yes. That's the point. That's literally the challenge.

But also — is it? In a world where we click "I have read and agree to the Terms of Service" without reading a single word, maybe we do need a certification program. Maybe we should be tested. Maybe the fact that anyone can deploy to production with a single, untrained, uncertified click is the real problem.

Or maybe I just spent way too long making a 3D button that shoots emoji particles.

Either way, I regret nothing.

Go get certified: https://aryakoste.github.io/buttonClickingCertification/button-certification.html

The International Bureau of Button Clicking Certification. Est. 1847. "Click Responsibly."

P.S. — Your clicks are being monitored. They always have been.

Built for the DEV Challenge: Build Something Useless. This software solves exactly zero real-world problems and I'm proud of it.

I Gave My Notion Workspace a Brain — Here's What Happened

Arya Koste — Sun, 29 Mar 2026 19:43:20 +0000

This is a submission for the Notion MCP Challenge

I spent a weekend building an AI that autonomously operates inside Notion. You type one sentence. It searches your workspace, reasons about what to do, creates pages, spins up databases, populates tasks — and you watch every single step happen in real time. Here's how I built it and why it might be the most useful thing I've ever made.

The Frustration That Started This

I've been a Notion user. My workspace is a sprawling mess of half-finished project pages, meeting notes that never got followed up on, and goals I set in January that I haven't looked at since.

The problem isn't Notion. Notion is incredible. The problem is that Notion is entirely passive. It sits there, waiting. It does nothing unless you tell it exactly what to do, how to structure it, and where to put it.

I kept thinking: what if Notion could just... think? What if I could say "set up a Q2 OKR tracking system" and it would actually do it — build the database, create the objectives, set up the weekly check-in templates, write the guidelines page — without me having to architect every single piece?

That's Apex.

What I Built

Apex is a full-stack AI command center that gives Llama 3.3 70B (via Groq) complete autonomous access to your Notion workspace. You chat with it naturally. It reasons, plans, and executes — using 10 Notion MCP tools in sequence — while you watch every operation happen live on screen.

It's not a chatbot that tells you how to use Notion. It's an agent that uses Notion for you.

Why Groq? Groq's free tier gives you 14,400 requests/day with no credit card required. Llama 3.3 70B handles tool calling excellently — and it's genuinely fast. Zero cost to run.

7 Intelligent Modes

Each mode has a deeply engineered system prompt that makes the AI behave like a domain specialist:

Mode	What It Does
💬 Chat	Natural language Q&A — ask anything about your workspace
🏗️ Project Blueprint	One sentence → hub page + task database + timeline + risk log
🧠 Brain Dump	Raw chaos → organized, searchable Notion knowledge base
📋 Meeting Intelligence	Paste notes → decisions, action items, owners, follow-ups
📊 Weekly Review	AI scans entire workspace → CEO-level intelligence report
🎯 OKR Tracker	Define goals → complete OKR system with check-in templates
📅 Content Calendar	Describe strategy → 20+ content ideas across all channels

The Feature I'm Most Proud Of: Live Tool Use Visualization

Most AI tools are black boxes. You ask, you wait, you get an answer. You have no idea what happened in between.

Apex flips this. As the AI works, you see every single Notion operation as it happens — animated cards streaming in, showing you exactly what the AI is doing and why:

🌐  Scanning Workspace...                          ✓ 12 pages, 3 databases
🔍  Searching Notion...     "Q2 goals"             ✓ Found 2 related pages
📄  Creating Page...        "🎯 Q2 Goals Hub"      ✓ Created
🗄️  Building OKR Database.. "Q2 OKR Tracker"       ✓ Created with 8 fields
➕  Adding Record...        "Grow MRR by 40%"      ✓ Objective added
➕  Adding Record...        "Key Result: MRR > $50k"✓ KR added
📄  Creating Page...        "📋 Weekly Check-in"   ✓ Template created
📄  Creating Page...        "🏆 Wins & Learnings"  ✓ Log created

Eight Notion operations, chained intelligently, executed autonomously. The whole OKR system is live in your workspace before you've finished reading the output.

This transparency is what makes it feel like a genuine AI colleague rather than a magic trick.

Video Demo

Technical Deep Dive

Stack

Frontend: Next.js 14 (App Router) + TypeScript
Styling: Tailwind CSS with glassmorphism, animated ambient orbs, dot-grid background
AI: Llama 3.3 70B via Groq SDK — streaming + multi-turn tool use
Notion: @notionhq/client — 10 MCP-compatible tools
Transport: Server-Sent Events for real-time streaming

The 10 Notion MCP Tools

const NOTION_TOOLS = [
  "search_notion",           // Full-text search across workspace
  "create_notion_page",      // Create pages with rich markdown → block conversion
  "get_page_content",        // Read any page's full content
  "update_notion_page",      // Append structured content to existing pages
  "create_project_database", // Task DB: Status, Priority, Due Date, Assignee, Tags
  "query_database",          // Retrieve records with optional filters
  "get_workspace_overview",  // Scan recent pages and databases
  "add_database_item",       // Insert rows with proper property types
  "create_goals_tracker",    // OKR DB: Objective/KR, Progress %, Owner, Quarter
  "create_content_calendar", // Editorial DB: Channel, Type, Status, Publish Date
]

Tools are defined in OpenAI-compatible format (which Groq uses), so each tool looks like:

{
  type: "function",
  function: {
    name: "create_notion_page",
    description: "Create a new page in Notion with rich content...",
    parameters: {
      type: "object",
      properties: {
        title: { type: "string", description: "Title of the new page" },
        content: { type: "string", description: "Page content in markdown format..." },
        icon: { type: "string", description: "Emoji icon for the page" },
      },
      required: ["title", "content"],
    },
  },
}

The Multi-Turn Streaming Loop

This is the core of the whole thing. The AI doesn't just make one tool call — it chains as many as needed, reasoning about results before deciding what to do next:

const groq = new Groq({ apiKey: process.env.GROQ_API_KEY });

// Keep looping until the model stops using tools
while (true) {
  const streamResponse = await groq.chat.completions.create({
    model: "llama-3.3-70b-versatile",
    tools: NOTION_TOOLS,
    messages: conversationHistory,
    stream: true,
  });

  // Accumulate streamed tool call fragments
  const toolCallsMap: Record<number, { id: string; name: string; arguments: string }> = {};

  for await (const chunk of streamResponse) {
    const delta = chunk.choices[0]?.delta;

    if (delta?.content) {
      // Stream text chunks to the frontend in real-time
      sendSSE({ type: "text", content: delta.content });
    }

    if (delta?.tool_calls) {
      for (const tc of delta.tool_calls) {
        // Accumulate streamed JSON fragments per tool call index
        if (!toolCallsMap[tc.index]) toolCallsMap[tc.index] = { id: "", name: "", arguments: "" };
        if (tc.id) toolCallsMap[tc.index].id = tc.id;
        if (tc.function?.name) toolCallsMap[tc.index].name = tc.function.name;
        if (tc.function?.arguments) toolCallsMap[tc.index].arguments += tc.function.arguments;
      }
    }
  }

  const toolCalls = Object.values(toolCallsMap);
  if (toolCalls.length === 0) break; // No more tool calls — done

  // Notify frontend each tool is starting
  for (const tc of toolCalls) {
    sendSSE({ type: "tool_start", name: tc.name, input: JSON.parse(tc.arguments) });
  }

  // Add assistant message with tool_calls to history
  conversationHistory.push({
    role: "assistant",
    tool_calls: toolCalls.map(tc => ({
      id: tc.id, type: "function",
      function: { name: tc.name, arguments: tc.arguments },
    })),
  });

  // Execute each tool against the Notion API
  for (const tc of toolCalls) {
    const result = await executeTool(tc.name, JSON.parse(tc.arguments));
    sendSSE({ type: "tool_result", name: tc.name, result });

    // Feed result back as a tool message for the next reasoning step
    conversationHistory.push({ role: "tool", tool_call_id: tc.id, content: JSON.stringify(result) });
  }
}

The key insight: the AI sees the result of each Notion operation before deciding what to do next. It's not blindly firing off a pre-planned list — it's actually reading what it created and adapting.

Markdown → Notion Blocks

One of the trickier engineering challenges: Notion's API doesn't accept markdown. Every page has to be structured as typed block objects. I wrote a full converter that handles 8 block types:

function markdownToBlocks(markdown: string): NotionBlock[] {
  return lines.flatMap(line => {
    if (line.startsWith("# "))   return [heading1Block(line.slice(2))]
    if (line.startsWith("## "))  return [heading2Block(line.slice(3))]
    if (line.startsWith("### ")) return [heading3Block(line.slice(4))]
    if (line.startsWith("- "))   return [bulletBlock(line.slice(2))]
    if (/^\d+\. /.test(line))    return [numberedBlock(line.replace(/^\d+\. /, ""))]
    if (line.startsWith("> "))   return [quoteBlock(line.slice(2))]
    if (line === "---")          return [dividerBlock()]
    if (line.trim())             return [paragraphBlock(line)]
    return []
  })
}

Headings, bullets, numbered lists, quotes, dividers, paragraphs — all properly typed and sent to Notion's API.

OKR Database Schema

When you say "set up my Q2 OKRs", Apex builds a database with exactly the right schema:

const okrSchema = {
  Name:     { title: {} },
  Type:     { select: { options: ["Objective", "Key Result"] } },
  Status:   { select: { options: ["Not Started", "On Track", "At Risk", "Behind", "Complete"] } },
  Progress: { number: { format: "percent" } },
  Owner:    { rich_text: {} },
  "Due Date": { date: {} },
  Quarter:  { select: { options: [period] } },
  Notes:    { rich_text: {} },
}

Not a generic template. A purpose-built structure that matches how real OKR systems work.

Features That Make the UX Sing

Beyond the core AI functionality, I obsessed over the interface:

⌘K Command Palette — Hit Cmd+K to open a searchable command palette. Switch modes, fire quick actions, export your conversation, clear the session — all without touching the mouse.

Slash Commands — Type /project, /goals, /meeting directly in the chat input to instantly switch modes. Feels like a native app.

Voice Input — Click the mic button and just talk. Web Speech API converts your speech to text in real time, with animated pulse rings showing it's listening. Perfect for actual brain dumps.

Smart Follow-Up Suggestions — After every AI response, three contextual next-step prompts appear. Click any to instantly continue. It's like the AI is guiding you toward the next useful thing.

Session Stats Bar — A live counter in the top bar shows pages created, databases built, and total Notion operations performed this session. It's a small thing but makes the productivity feel visceral.

Floating Success Toasts — Every time a Notion page or database is created, a beautiful animated toast slides up: "Page created: Q2 OKR Tracker — saved to Notion". Instant feedback, no hunting through your workspace.

Export Conversation — Download your entire session as a formatted markdown file. Great for sharing what you built.

Workspace Dashboard — A separate /dashboard route showing live workspace stats, recent pages and databases, a full capability showcase, and a visual "How Apex Works" flow diagram.

Real-World Demo: OKR Mode in Action

What I typed:

"Set up Q2 OKRs — grow MRR by 40%, improve activation rate to 60%, ship mobile v1, and reduce churn below 3%"

What Apex did (30 seconds):

Scanned workspace for existing goal-related pages
Created a 🎯 Goals Hub page with vision statement and OKR methodology explained
Built the Q2 OKR Tracker database with 8 properly typed fields
Added each of the 4 objectives as database records (Type: Objective)
Added 3 key results per objective (Type: Key Result, with measurable targets)
Created a 📋 Weekly Check-in Template page — duplicate this every Monday
Created a 🏆 Wins & Learnings Log for retrospectives

What I had to do: Type one sentence.

That's the whole thing.

What's Next

Scheduled Reports — Auto-run weekly review every Monday morning via cron
Notion Webhooks — React to workspace changes in real time
Multi-workspace — Switch between different Notion accounts
Template Library — Pre-built prompts for 20+ common use cases

Setup in 3 Minutes

git clone https://github.com/Aryakoste/apex-notion
cd apex-notion-ai
npm install
cp .env.local.example .env.local

Edit .env.local:

GROQ_API_KEY=gsk_...
NOTION_API_KEY=secret_...

npm run dev
# Open http://localhost:3000

Getting your Groq API key (free):

Go to console.groq.com → sign up (no credit card)
API Keys → Create API Key → copy it

Getting your Notion API key:

notion.so/my-integrations → New integration → copy the secret
On each Notion page: ... menu → Add connections → select your integration

That's it. Everything else is handled by Apex.

Why This Matters Beyond the Demo

The reason I'm excited about this isn't the cool UI or the streaming animations — it's what it represents for how we use tools.

Notion has always required you to be the architect. You had to know what a good project page looks like. You had to remember to run your weekly review. You had to structure your OKRs correctly.

With MCP, the AI can be the architect. You just have to know what you want. The gap between intention and implementation collapses from hours to seconds.

I think this is the future of productivity software. Not AI that suggests. AI that does.

GitHub

Full source code: [https://github.com/Aryakoste/apex-notion]

#notionmcp #ai #nextjs #typescript #groq #llama #productivity #buildinpublic