DEV Community: Richard Fu

Six Months of AI Buy Signals: The Honest Numbers

Richard Fu — Mon, 10 Aug 2026 13:40:44 +0000

Part 4 of 4 — the results. Part 1: every safety net failed silently · Part 2: the free stack · Part 3: publishing signals

The first three parts were about how my portfolio monitor works and how its safeguards failed. This one is the question everybody actually asks: do the AI buy signals make money?

The portfolio is up 13.8% on cost basis. Last post, three months ago, that number was 6%. I’ll keep the balances to myself — the ratios are the only part that carries information anyway, and a tool whose whole design premise is “don’t publish your position sizing” is a poor place to publish mine.

Now the four reasons that number tells you much less about the AI buy signals than it looks like it does.

Four caveats before you read anything into it

It’s return on capital deployed, not a time-weighted return. I’ve been adding cash throughout, as the tool flagged gaps — that’s what it’s for. So a dollar that went in last week counts the same as one from February. You can’t line this up against “the S&P did X% over the same window” and call the difference alpha.
The market was up too. Most of 13.8% is beta, not skill. I haven’t done the work to separate them, and I’m suspicious of anyone claiming they have on a six-month sample.
One portfolio is not a backtest. N=1, no control, and I chose which AI buy signals to act on. The tool suggests; I still click the button.
Six months is noise. Any strategy can look good over one up-trending half-year.

What I’d actually want to know about these AI buy signals — whether the STRONG BUY gate has predictive value — needs far more STRONG BUYs than it has produced, which is by design. The unanimity rule made them rarer still. Ask me in two years.

The uncomfortable part: my best trade broke my own plan

44% of that gain came from a single position, MSFT. And MSFT was never in my target allocation.

It was on the watch list : a feature for tickers I’m interested in but haven’t committed to a target weight. On 21 June it came back a STRONG BUY at 88% confidence, Value A. I read the thesis, set a limit order where the card told me to, and it filled at $370.10. Off-plan, discretionary, exactly the kind of decision allocation targets exist to prevent.

Here’s the card, verbatim:

MSFT · STRONG BUY · Value A · 88%

(Watch) Exceptional multi-indicator bottom setup: trailing P/E of 22.6 is below the historical average of 23.4 (price-level signal), 52w position of 12% (price-level signal), price -15.9% below 200MA (price-level signal). RSI of 18.6 is deeply oversold, Stochastic %K of 6.6 is deeply oversold, and %B of 0.11 is at/below the lower Bollinger Band — all momentum signals confirming. Forward P/E of 19.6 below historical avg, 34% ROE, 23.4% EPS growth, low debt, analyst target of $561 (+48% upside). Death cross and bearish MACD are risk flags, but all other indicators overwhelmingly support a bottom-forming scenario. Historical conviction has been strengthening (42% → 88% → 70%). Risk: macro headwinds (high yields, strong USD) may extend the drawdown.

Momentum: bearish · RSI 18.6 · 50MA $412.98 (-8.1%) · 200MA $451.35 · death cross · MACD hist -5.027 · %B 0.11

Limit order: $370 — Set just below current price at ~$370, near the prior consolidation zone and round-number support; provides a small buffer given ATR-implied volatility

Bottom signal: RSI < 30, price below 200MA, death cross, 52w position < 30% — 4 of 4 bottom indicators active for a stock

RSI 18.6 on a mega-cap. I had to re-read that. A reading that deep on the largest companies in the world is rare — it’s what you get in a capitulation, which is precisely what the reasoning says. Two days later the same ticker printed 9.3 , and that card is a story of its own.

The generous reading is that the feature did its job, and I’d go further: this is not a marginal call the gate waved through. Six independent signals — three price-level, three momentum — four of four bottom indicators, forward P/E below its own historical average, and the part I care most about: the risks are named, not buried. Death cross present. MACD bearish. Momentum bearish. Macro headwinds that may extend the drawdown. The model argued past those rather than omitting them, and left me a written thesis I could audit six weeks later.

That auditability is the real product. AI buy signals you can’t interrogate afterwards are just a number with a colour.

The historical-conviction line is the reasoning-persistence store paying off, too. Three features compounding: the watch list surfaced a ticker I didn’t own, the bottom-fishing model caught the extreme, and the 7-day history put the reading in context.

There’s also a fourth mechanism that was supposed to be involved and wasn’t. Both of these cards — the 88% I bought on and the 91% two days later — came from Claude alone. Gemini was quota-exhausted, so the cross-model agreement check never ran on either, and nothing in the email said so. The number I acted on was a single model’s opinion wearing the same badge a two-model consensus would have worn. That story is Part 1, and it’s the reason v1.9 exists.

I followed the one instruction it gave me. That was the mistake.

The card told me to set a limit at $370 — “just below current price at ~$370, near the prior consolidation zone and round-number support.” I did exactly that, at $370.10, and it filled.

Then MSFT came back a STRONG BUY the next day, and the day after that — 88%, 88%, 91% across 21, 22 and 23 June — trading lower each time. There was no window closing on me. The signal was still there three days later, and by then the same feature was naming a different price: $360 , reasoning from the 90-day consolidation floor with the 10th percentile at ~$354. MSFT traded down to $349.20 shortly after.

Put those two limit prices side by side and the flaw is hard to unsee. The second one is anchored to a distribution — where the stock has actually spent the last 90 days. The first is anchored to the spot price: a small buffer below wherever MSFT happened to be trading that morning, dressed up in the vocabulary of support. Only one of them is a limit price in the sense I built the feature for. The other is “buy it now, but ten dollars less.”

That cost about four percentage points on the position: 33.7% instead of the 37.5% a $360 fill would have returned. Trivial in absolute terms, and the most instructive line in this whole series — because I did everything right by the process. I read the reasoning, I agreed with it, I placed the order at the number it gave me. There was no 11pm override to blame.

There is one tell, though, and it’s mine. The card said $370 and I set $370.10 — ten cents up, to be sure of the fill. I wanted the position more than I wanted the price, and I expressed that in the only digit the tool had left me.

If you build AI buy signals for yourself, the lesson isn’t “trust the limit price” or “don’t.” It’s that a suggested number gets exactly as much credibility as the thing it’s anchored to, and a model will narrate a spot-price offset in the same confident register it uses for a real support level. I couldn’t have caught that from one card. It took three of them across three days, which is the argument for persisting the reasoning rather than just acting on the number at the bottom of it.

The honest reading of six months of AI buy signals

A good thesis and a good outcome are different things. Everything in that card was true on 21 June, and it would still have been true if MSFT had kept falling. “Buy the capitulation” works until the death cross the model waved past turns out to have meant something. I got the outcome; I can’t claim the process is validated by it.
N=1. If this trade had gone the other way, the same feature and the same reasoning would have produced the opposite anecdote — and I probably wouldn’t be writing a section about it. That asymmetry is worth naming, because it’s how every tool’s success story gets written.
The split is unflattering to the plan. That single off-plan position returned 33.7%. The other fourteen — only nine of which are the actual target allocation — returned the remaining 56% of the gains on a much larger base, about 9.4%. My least disciplined decision beat my whole system by 24 points, which is either a lesson about signals or a lesson about small samples, and I genuinely don’t know which.
44% of gains in one unplanned position is a concentration risk , not a result. I’d flag it red in anyone else’s portfolio.

So I’m recording it, not celebrating it — one lucky trade is not evidence about AI buy signals in general. Ask me again after the tenth watch-list buy.

The bug this exposed

There’s a design gap underneath the anecdote, and it’s more useful than the anecdote.

Buying a watch-list ticker gives it nowhere to go. I took MSFT off watching, but never gave it a target allocation — so it became what the codebase calls a held-only ticker : held, no target, not watched. Its allocation gap is permanently negative against an implied 0% target, which means:

the daily brief rendered it as HOLD/WAIT noise (“MSFT is N% overweight vs. a 0% target”), and
the weekly rebalancing report handed it a standing TRIM , every week, forever.

My best-performing position was being told to sell itself on a schedule, because I bought it through a path with no final step. The watch list can surface a ticker and hand me a signal, but there is no promote to portfolio — no moment where a watch-list buy becomes a target allocation with a real percentage.

I’d written a design for half of it back in June, before MSFT gave me a reason to care — the standing TRIM was already visible on other holdings, just not on one I felt anything about. It shipped in v1.10: held-only tickers route to a separate untrackedItems array, so they stop generating buy and trim recommendations while still counting toward portfolio value, beta, dividends and ETF overlap. The weekly report now lists them neutrally — value and current %, no action verb.

The nice side effect is token cost. Every consumer that feeds the AI iterates the tracked-items array, so removing them from it took them out of the prompt entirely. Four tickers I was paying to have opinions generated about, opinions I could never act on.

That still doesn’t fix the real gap. Silencing the TRIM is not the same as deciding what MSFT’s target weight should be, and that decision is mine, not the tool’s. The most a tool can honestly do is stop pretending a deliberate off-plan holding is a rebalancing error — and then leave the question with me.

One more thing I only noticed while implementing it. Two other holdings, MU and MRVL, sit in both currentHoldings and watching, because I bought them off watch-list signals and never cleaned up. That combination accidentally did the right thing all along: watched tickers were already excluded from the allocation table, so those two never got the standing TRIM the others did. I’d been running the fix by hand, on two tickers, without knowing it.

Where that leaves the experiment

Six months in, the honest summary is that I can’t tell you whether AI buy signals beat buying the index, and neither can anyone else with one portfolio and one up-trending half-year. What I can tell you is what changed about using it: I read the briefs again. Before the frozen-data guard, a Telegram buzz meant “maybe something happened,” and I’d started ignoring them.

That’s the real failure mode for a tool like this — not being wrong, but being noisy enough that you stop reading it. Fixing the noise was worth more than any individual recommendation — AI buy signals you’ve stopped opening are worth exactly nothing.

Still looking for alpha testers

Richfolio is open source and free to run: github.com/furic/richfolio, docs at furic.github.io/richfolio. Fork it, add your allocations to a config file, set a Gemini key, and GitHub Actions does the rest.

Most useful to me right now:

Non-US portfolios , especially LSE/JSE tickers — the sub-unit currency guard in Part 1 came out of exactly one such bug, and I doubt it’s the last
Larger universes (20+ tickers) — both truncation bugs this cycle came from a big universe, and mine isn’t big
Anyone running two AI providers — Gemini + Mistral is now free on both sides, so this costs nothing to try. I’d like to know how often two models actually disagree on portfolios that aren’t mine, because the unanimity rule is only worth its complexity if that number is meaningfully above zero

Open an issue on the repo or DM me.

Nothing here is financial advice. It’s a description of a tool I built for myself and the mistakes I made using it.

The post Six Months of AI Buy Signals: The Honest Numbers appeared first on Richard Fu.

LinkedIn API Approval Rejected: What They Actually Require

Richard Fu — Sun, 09 Aug 2026 13:38:21 +0000

Part 3 of 4 — publishing. Part 1: every safety net failed silently · Part 2: the free stack · Part 4: what it returned

I built social posting into my portfolio tool so it could publish its own buy signals — four platforms: X, Facebook Page, Threads, LinkedIn Page. The code took hours per platform. Getting permission — the LinkedIn API approval in particular — took weeks, and two of the four never sent a single request.

The LinkedIn API approval is the one worth writing down, because the rejection reason isn’t in the docs and I couldn’t find a first-hand account of it anywhere.

Two of the four have never posted anything

Platform	Status	Blocked by
Facebook Page	live	—
Threads	live	—
X	dormant	no free tier since Feb 2026; ~$0.015/post, more with a link
LinkedIn Page	dormant	identity vetting failed — appeal in flight

X is a straightforward economic decision. The API works, the OAuth 1.0a signing works, and I’m not paying per post to broadcast signals nobody asked for. My includeLinkInX flag defaults to false for the same reason — adding a link raises the per-post cost by more than 10×. If I ever turn it on, that flag is why.

LinkedIn is the interesting failure, and the rest of this post is about it.

What the LinkedIn API approval process actually checks

Posting to a LinkedIn Page as an app requires the w_organization_social permission, which is gated behind their “Share on LinkedIn” product review — that review is the LinkedIn API approval. The API itself is free. So I:

created the app and associated it with a Page
wrote a privacy policy page specifically for this review (and Meta’s)
documented what the app posts, how often, and what data it touches
submitted, and waited two weeks

The LinkedIn API approval rejection, when it arrived, mentioned none of that. Not the code, not the privacy policy, not the posting behaviour, not the data handling. The developer portal gave one reason:

Identity vetting failed. We were unable to verify that your organization is a legally registered, active entity.

The fix it suggested was a valid link to an organizational website. I had given them the project’s GitHub Pages documentation site. Not accepted.

Those two things are worth separating, because I ran them together for weeks. The requirement is proof that a legally registered entity exists. The website is only the evidence they ask for by default, because for most applicants it’s the fastest thing for a reviewer to check. A docs site on github.io demonstrates that a project exists. It demonstrates nothing about registration.

The signal was there in the permission name: w_organization_social. The product is built for organizations posting as themselves, and a reviewer asking “is there a registered entity behind this” is doing the job correctly.

What I got wrong is that I read the question as being about size, and answered no — there’s a repository and one user. It isn’t about size. I’ve held an active sole-trader ABN, an Australian business registration listed on a public government register, since months before I created the app. I never gave it to them. I gave them a documentation site and expected substance to stand in for registration.

The options, and the one I missed

Two ways forward, as I saw it at the time:

Stand up a real site. Buy richfolio.app, build a landing page, resubmit, wait another two weeks, probably pass.
Leave LinkedIn dormant.

I picked the second, and I’d still pick it over the first. Buying a domain and building a marketing site whose only purpose is to unlock a posting integration — for a tool with one user — is the tail wagging the dog. If the project ever justifies a site on its own merits, I’ll do it then and the LinkedIn API approval becomes a free side effect rather than the reason.

What I’d missed is that the rejection isn’t the end of it. The denial notice links to a vetting appeal form, and the appeal asks for the thing my original application never contained: documentation that a legally registered entity exists. Not a website. A registration someone can look up.

So there’s a third option, and it’s the one I’m taking — appeal with the ABN and let a reviewer check it against the public register. That’s in flight as I publish this, and I don’t know yet how it lands. If a website turns out to be required in practice regardless of what the appeal form asks for, the conclusion I started with stands. If it isn’t, then two weeks of this was me answering a question nobody had asked.

That’s not a complaint about LinkedIn either way. The bar is a fair rule, enforced consistently. I just spent two weeks failing to notice which rule it was.

The estimate I got wrong

I planned all four integrations as engineering work, and the engineering was genuinely small — each platform is roughly fifty lines against a shared content builder, gated on its own credentials, wrapped in its own try/catch so one dead token can’t block the others.

Platform access was the real cost: weeks of calendar time, and two of four failed on criteria no amount of code could satisfy. For X the blocker is a price. For LinkedIn it was an identity check I answered with the wrong document.

If you’re scoping “post to social” for a personal project, the useful advice is: budget the approvals, not the integrations — and expect a nonzero share to simply not happen. Two of mine didn’t. I’d plan for that ratio next time rather than treating it as bad luck.

There’s one more thing worth flagging, which connects to Part 1: both dormant integrations are in the codebase, tested, and permanently no-op because their credentials are unset. That’s the correct design — every platform skips silently when unconfigured, which is exactly what you want when a token expires overnight. But it does mean “shipped in the repo” and “running in production” are two different claims, and the code can’t tell you which one it is.

The part I’d have written even if all four worked

The interesting engineering problem was never the four APIs. It’s that every recommendation object in my pipeline carries private data — suggested buy amounts, allocation gaps, current and target percentages, ETF overlap discounts — and I’d rather not publish my position sizing to the internet.

The approach: one chokepoint that projects onto an explicit allowlist, rather than N call sites each remembering to omit the right fields.


/**
 * Privacy chokepoint. Filters to publishable buy signals and projects each
 * onto the generic allowlist — nothing else from the source object survives.
 */
export function buildSignalLines(sources: SignalSource[]): SignalSource[] {
  return sources
    .filter((s) => s.action === "STRONG BUY" || s.action === "BUY")
    .map((s) => ({
      ticker: s.ticker,
      tickerFullName: s.tickerFullName ?? null,
      action: s.action,
      confidence: s.confidence,
      reason: sanitizeReason(s.reason),
      valueRating: s.valueRating,
      analysisUrl: s.analysisUrl,
    }))
    .sort(/* action rank, then confidence */);
}

Explicit construction, not delete or destructured rest. A new private field added upstream can’t leak by default — it simply isn’t in the projection. And that module deliberately imports no config and does no network calls, so it’s unit-testable with no config file present. There’s a test asserting private values never appear in the output.

The harder half is prose. The reason text is written by the AI for me, so it says things like “underweight by 2.3%, fill ~$4,180 after ETF overlap discount” (figures illustrative — that sentence is exactly what must never reach a feed). Field-level allowlisting doesn’t help when the leak is inside a sentence:


const PRIVATE_SENTENCE =
  /(\$\s?\d{1,3}(?:,\d{3})+|allocation gap|overlap discount|after etf overlap|under-?weight|over-?weight|portfolio (?:value|total)|position siz)/i;

Sentence-level filtering: split on sentence boundaries, drop any sentence that trips the pattern, keep the rest. Then a backstop regex strips any comma-grouped dollar figure that survived in a kept sentence.

The comma-grouping detail is deliberate. $4,180 is a position size; $205 is a share price, which is public information and useful in a post. Requiring comma-grouped thousands separates the two without needing to know which is which semantically.

The same pass strips internal guard annotations and any sentence mentioning the watch list — because the subtler leak isn’t dollars. If posts labelled tickers as “portfolio” versus “watching”, I’d be broadcasting exactly what I own. So portfolio and watch-list signals merge into one undifferentiated list. Which tickers I hold is not derivable from the output.

That was the design constraint I cared about, and it’s the half that works. The half that didn’t work was asking four companies for permission.

Next: Part 4 — what six months of AI buy signals actually returned, including the trade that beat my whole system and the reason that’s uncomfortable.

Richfolio is open source: github.com/furic/richfolio · docs

The post LinkedIn API Approval Rejected: What They Actually Require appeared first on Richard Fu.

Free LLM API Tiers: Running Three Models for $0/month

Richard Fu — Sat, 08 Aug 2026 14:24:02 +0000

Part 2 of 4 — the stack. Part 1: every safety net failed silently · Part 3: publishing signals · Part 4: what it returned

Part 1 was about the safeguards in my portfolio monitoring tool and the six ways they silently stopped running. This one is the boring, useful half: what it actually runs on, why every component is a free LLM API or free tier, and which of those free tiers turned out to be load-bearing in a way I hadn’t thought about.

The free LLM API stack — back to $0/month, the second time around

Component	Service	Free tier
Prices, fundamentals, technicals, ETF holdings	Yahoo Finance (`yahoo-finance2` v3)	unofficial, unmetered
Headlines	NewsAPI.org	100 req/day
AI analysis	Google Gemini 2.5 Flash	~20 req/day
AI analysis (second opinion)	Mistral Large	~1B tokens/month (Experiment tier)
AI analysis (third opinion)	Anthropic Claude Sonnet 4.6	Claude Pro subscription — no per-token cost
Email	Resend	3,000/month
Telegram	Bot API	free
Scheduler	GitHub Actions	free (public repo)
Docs site	GitHub Pages	free

That second-opinion row spent most of this window saying “Anthropic Claude — pay-per-use”, because Claude has no free LLM API tier. Then the balance ran out, and I got a useful lesson in what a free tier is actually load-bearing for: not cost, continuity.

A free LLM API tier is a promise about next month; pay-per-use inside a zero-maintenance system is a scheduled outage with an unknown date. Mine landed silently. Because the orchestrator degrades gracefully when a provider fails, every brief kept arriving — just quietly weaker — and it took me days to notice. The failure mode wasn’t the bill; it was that nothing broke loudly enough to tell me.

Why not DeepSeek

DeepSeek was the obvious replacement and I skipped it. Its free LLM API allowance is a one-time 5M-token grant valid for 30 days, not a perpetual tier. After that it’s pay-as-you-go — very cheap, roughly $1/month at my volume after the ~75% price cut in May 2026, but that’s the same trap with a longer fuse. I’d be back here in a month, and the whole point of this project is that I don’t want to maintain it.

If you’re happy paying a dollar rather than managing a free LLM API allowance, DeepSeek is a genuinely good answer. It just isn’t a free one.

Why not Groq or Cerebras

Both offer generous permanent free tiers — Groq at ~30 requests/minute serving Llama 3.3 70B, Cerebras at 1M tokens/day — and both are far faster than what I’m using. I still skipped them, for a reason that has nothing to do with their free LLM API terms.

Free LLM API generosity was never the deciding factor. My system caps a STRONG BUY unless every model independently agrees. That means an extra model only adds information when its disagreement reflects the data rather than the model being weaker. Pair a strong model with a noticeably weaker one and you don’t get a cross-check, you get a random gate: the weaker model dissents on cases it simply handled worse, and your best signals get suppressed for the wrong reason.

A 70B open-weight model against Gemini 2.5 Flash would have been a downgrade dressed as an upgrade. Its dissent would mostly tell me about the model.

Why Mistral

Mistral Large sits at comparable capability to Gemini Flash on this kind of structured reasoning, on a genuinely different model lineage, with a permanent Experiment tier of roughly 1B tokens/month against my actual usage of about 7M. That combination — capable, independent, permanently free — is the only free LLM API pairing where a disagreement between the two is worth reading.

It also has proper strict structured output , which matters more than it sounds. More on that below.

Claude came back, and not through the API

Claude still has no free LLM API tier — that part of this post hasn’t aged. What it has is a route I’d been ignoring: if you already pay for Claude Pro, claude setup-token mints a long-lived credential that authenticates against your subscription allocation instead of API credits. Same models, no per-token bill.

So the second opinion became a third. That matters more than “one more model” — the unanimity rule below is only as strong as the number of genuinely independent votes behind it, and going from two to three changes what a dissent means.

The catch is that this isn’t the Messages API. It runs through the Claude Agent SDK, which spawns a Claude Code subprocess per call, and that has a shape of its own:

A full daily run went from ~2 minutes to ~20. Irrelevant against a cron that fires hours apart. Genuinely annoying when you’re iterating on one ticker.
It enforces its own 32,000 output-token ceiling , separate from the API’s max_tokens. A 21-ticker decision stage sailed straight past it, Claude threw, and the brief degraded to two providers. I caught that in one run instead of a week, purely because the degradation badge from Part 1 was already there to say so.
It emits noticeably more output than the API path for identical input. The API path finishes the same work inside 16K tokens. Whatever the harness wraps around the call, you pay for it out of the same allocation.

None of that is a reason to skip it. But “free” here buys you a slower, chattier transport — not the same call with the bill removed. Point a coding-agent harness at a batch inference job and that’s the trade you’re making.

One constraint hasn’t changed across any of this: it was never really about money, it’s about request budgets. When I started, Gemini’s free tier was 250 calls/day. It’s now 20 for 2.5 Flash — and two-stage prompting across six scheduled runs needs 12 before the news filter gets a look in. A free tier is a promise about next month, and this one was quietly revised downward mid-project. Every design decision downstream is shaped by that ceiling.

The database is a cache, and that’s fine

There’s a state/ directory holding two files: the morning baseline that intraday runs compare against, and the 7-day rolling reasoning history the prompts read. Both need to survive between runs of a workflow whose machine is destroyed every time it finishes.

The whole persistence layer is this:


- uses: actions/cache@v5
  with:
    path: state/
    key: intraday-state-${{ github.run_id }}
    restore-keys: |
      intraday-state-

The run_id in the key is the part worth stealing. Cache entries in GitHub Actions are immutable — you cannot overwrite a key once it exists. A stable key like intraday-state-v1 looks obviously right and then silently stops saving after the very first run, because every subsequent save is a no-op against an existing key. Making the key unique per run means the save always succeeds, and restore-keys prefix-matches to pull back the most recent entry. Each run reads the previous run’s state and writes a new one: a rolling single-writer chain, no database, no S3 bucket, no credentials.

What makes this acceptable rather than reckless is that nothing important lives only there. It’s a cache, and GitHub will evict it — 7 days without access, or LRU once the repo passes 10 GB. So every consumer treats absence as normal, not exceptional:


const ageHours = (Date.now() - new Date(data.timestamp).getTime()) / (1000 * 60 * 60);
if (ageHours > 18) {
  console.log(`Baseline is ${ageHours.toFixed(1)}h old (max 18h) — skipping comparison`);
  return null;
}

A missing baseline means the intraday run exits quietly instead of comparing against stale numbers. A missing reasoning history means the prompt omits its HISTORICAL CONTEXT section — the analysis is slightly worse that day and nothing breaks. When the history schema changed in v1.7 I discarded the old entries rather than writing a migration, on the grounds that seven days of conviction snapshots isn’t precious data. That’s only defensible because the storage was never load-bearing.

The trap I did fall into: for months I assumed my local state/ reflected what production was doing. It doesn’t — they’re two completely separate lineages. My working copy is only written by local runs, so it had been frozen at 23 June while Actions quietly maintained its own chain in the cache. When I went looking for the run that produced a particular signal, the file on my disk had nothing to do with it. Worth knowing before you try to debug a scheduled job by reading your own checkout.

Making the AI layer pluggable

v1.6 was Gemini-only, and the Gemini SDK was threaded through the analysis module. Adding a second provider meant first removing the first one from the plumbing.

What came out is a provider interface and a registry:


src/providers/
├── types.ts # AIProvider interface + canonical AIBuyRecommendation
├── prompts.ts # SDK-agnostic prompt builders
├── schemas.ts # shared JSON Schemas + strictify() for strict-mode dialects
├── gemini.ts # GeminiProvider (@google/genai)
├── claude.ts # ClaudeProvider (@anthropic-ai/sdk, tool-use)
├── mistral.ts # MistralProvider (native fetch, strict json_schema)
└── index.ts # buildActiveProviders() — reads env, returns what's configured

src/aiOrchestrator.ts # runs active providers concurrently, applies guards
src/aiAggregation.ts # consensus action, averaging, the unanimity rule

The part that mattered was pulling the prompt builders out of the SDK calls. Every provider gets byte-identical prompts; only the transport differs — Gemini’s responseSchema, Claude’s tool-use, Mistral’s json_schema with strict: true. Adding a provider really is about fifty lines, and the guard pipeline, reasoning history, degradation policy and renderers all pick it up for free. I know it’s fifty lines because I did it twice: Claude in v1.7, Mistral in v1.10, the second needing no changes to anything upstream.

Behaviour is keyed off how many keys you set. One key → single-provider mode. Two or more → multi-model mode auto-engages, providers run concurrently, and every email and Telegram message shows a per-AI breakdown under each consensus call.

One practical note on picking a free LLM API for this kind of work: adding Mistral needed no SDK at all. Its endpoint is OpenAI-compatible, so it’s native fetch and zero new dependencies — the same approach the social posting module takes for four platforms.

One refactor worth the effort

schemas.ts. The two-stage output contract started life inside claude.ts, then got copied into detailedAnalysis.ts, and adding a third provider would have made three hand-maintained copies of the same JSON Schema.

They’re one module now, with strictify() deriving the strict-mode variant rather than a second copy maintained by hand. Strict dialects — Mistral’s json_schema with strict: true, OpenAI’s structured outputs — require every object to declare additionalProperties: false and list all properties in required. That’s mechanical, so derive it:


export function strictify<T>(schema: T): T { /* walk the tree, add what strict mode demands */ }

Two providers asking for subtly different fields would mean the same portfolio produces structurally different recommendations depending on which model answered. That’s a bug that would have been invisible in exactly the way Part 1 is about — so it’s worth spending a module to make it impossible.

Worth knowing if you’re evaluating a free LLM API for structured work: “supports JSON” and “constrains decoding to a schema” are different guarantees. JSON mode gets you parseable output. Strict schema mode gets you output with the fields you asked for. The second one removes an entire category of repair code, and not every provider has it.

The unanimity rule

Consensus is mode-of-votes with a confidence-sum tiebreaker, and if that still ties, it falls to whichever action is more conservative. Under-recommend rather than over-recommend.

Then one extra rule on top:


// Unanimity rule for STRONG BUY
if (consensus === "STRONG BUY") {
  const allStrongBuy = scores.every((s) => s.action === "STRONG BUY");
  if (!allStrongBuy) {
    consensus = "BUY";
  }
}

Four lines, and they’re the whole point of running more than one model. STRONG BUY here is supposed to be rare and high-conviction — gated on a ≥2% allocation gap, ≥80% base confidence, two or more entry signals including a price-level one, and a maximum of two live at any time. Averaging providers’ confidence would have quietly softened that: an 88% and a 74% average to 81%, which clears a bar neither model individually agreed on. At three providers the rule bites harder — one dissenter out of three still caps the whole thing.

So a dissent caps the consensus at BUY. If one model thinks a setup is exceptional and the other doesn’t, that’s not an exceptional setup — that’s a disagreement, and it gets displayed as one (unanimous / majority / split badge).

The one place dissent survives is the detailed analysis page. If any provider voted STRONG BUY, the ticker still qualifies, and the page is generated from that provider’s thesis:


export function hasStrongBuyVote(rec: AIBuyRecommendation): boolean {
  if (rec.action === "STRONG BUY") return true;
  if (!rec.providers) return false;
  return rec.providers.some((p) => p.action === "STRONG BUY");
}

The dissenting recommendation is frequently the most interesting thing in the brief. Capping the headline action doesn’t mean throwing away the argument.

What I still don’t know is how often capable models disagree on the same portfolio. On mine the sample is too small to say, which makes the unanimity rule a well-reasoned bet rather than a validated one. If you run it, that’s the number I’d most like to hear about.

Next: Part 3 — publishing signals publicly without publishing my portfolio, where two of four integrations never sent a single request.

Richfolio is open source: github.com/furic/richfolio · docs

The post Free LLM API Tiers: Running Three Models for $0/month appeared first on Richard Fu.

AI Portfolio Monitoring: Every Safety Net Failed Silently

Richard Fu — Fri, 07 Aug 2026 14:02:42 +0000

Part 1 of 4 — the safeguards. Part 2: the free stack · Part 3: publishing signals · Part 4: what it returned

Three months ago I wrote up how Richfolio went from v1.0 to v1.6 — the guard pipeline, the two-stage Think/Plan prompt, the reasoning persistence, all of it borrowed from patterns I liked in OpenAlice. Richfolio is my AI portfolio monitoring system: a cron job that reads my holdings, asks two language models what to buy, and emails me a brief.

Four releases since then. v1.7 made the AI layer pluggable and put two providers side by side. v1.8 taught it to publish, to watch tickers I don’t own, and to stop lying to me about prices. v1.9 and v1.10 are the ones I didn’t plan — they exist entirely because of what writing this post turned up.

Those are the features. They’re not what I learned.

What I learned is that I spent six releases building safeguards — a price-move deadband, a unanimity rule, a guard pipeline, a fail-open policy for missing data — and then discovered, one at a time, that a safeguard which isn’t running is indistinguishable from a safeguard that ran and approved. Same alert in my inbox. Same clean number on the card. Same plausible file on my disk. Same green test suite. Six separate instances in one release window, and I found every one by accident — three of them while drafting this post, which is the part that should worry me most.

That’s this post. The features are how I got there.

What this AI portfolio monitoring system does now

Still one Node.js + TypeScript pipeline on GitHub Actions cron. No server, no dashboard, no database — just a state/ directory cached between runs. Part 2 covers the stack and architecture if that’s the interesting half for you.

Four modes:

Daily (8am AEST) — allocation gaps, buy signals, news, the full brief
Intraday (4× on weekdays) — re-runs the analysis, alerts only when a recommendation materially changes
Weekly — rebalancing report
Refresh (npm run refresh -- SMH) — re-analyze one ticker on demand

Output goes to email and Telegram, and optionally to social — which turned out to be a story about approvals rather than code.

Everything below is about the intraday mode, because that’s where an AI portfolio monitoring tool earns or destroys your trust.

Case study: the day my AI portfolio monitoring alerts started whipsawing

This is the bug I’d share if I could only share one.

Late July, my Telegram lit up twice in ninety minutes:


4:32pm VOO BUY → STRONG BUY 64% → 87% $670.63 → $673.20 (+0.38%)
6:05pm VOO STRONG BUY → BUY 87% → 76% $673.20 → $672.00 (−0.18%)

My first instinct was that the AI was being flaky. It wasn’t. I pulled both runs’ technicals and they were byte-identical — same RSI, same MACD histogram, same Bollinger %B, to the last decimal. A 23-point confidence swing and back, on a ticker that had moved half a percent.

Here’s why. Intraday technicals are computed from Yahoo daily candles, and a daily candle only updates at the US close. My four intraday crons were at 10am / 12pm / 2pm / 4pm AEST — every single one firing while the US market was shut. So on all four runs, the indicators feeding the AI were the same frozen numbers from the last US close.

Which means an action flip between two of those runs contained zero new information. It was a provider’s confidence drifting across the 80% line by a couple of points — scoring noise on identical inputs — and my alert logic was faithfully paging me about it.

Two fixes, one tactical and one structural.

The tactical one: require a real price move before any alert fires. Prices do update off-hours (that’s the after-hours quote), even when daily candles don’t, so price movement is the honest signal that something changed.


// An action/confidence flip with no material price move on frozen off-hours
// data is AI scoring noise, not a real signal, so suppress it. Fail open when
// we lack both prices (can't prove it's noise) or the threshold is disabled (0).
if (
  triggerType &&
  config.minPriceMovePctToAlert > 0 &&
  morningPrice > 0 &&
  currentPrice > 0 &&
  Math.abs(priceDelta) < config.minPriceMovePctToAlert
) {
  triggerType = null;
}

Default threshold is 1.0%, configurable. Note the fail-open conditions — if either price is missing, or you set the threshold to 0, you get the old behaviour. I didn’t want a data gap to silently mute alerts; a guard that fails closed on missing data is a guard that eventually hides something real.

That module had no unit tests before this. It has them now, and the first two replay both halves of that VOO whipsaw with the numbers straight out of the logs.

The structural fix: the crons were badly placed to begin with. All four sat inside the US-closed dead zone because I’d picked times convenient for me, not times when the underlying data changes. Respaced ~3.75h apart across my waking window:


- cron: "15 3 * * 1-5" # 1:15pm AEST (US closed)
- cron: "0 7 * * 1-5" # 5:00pm AEST (US closed)
- cron: "45 10 * * 1-5" # 8:45pm AEST (US pre-market)
- cron: "30 14 * * 1-5" # 12:30am AEST next day (US market open)

The last two now land in US pre-market and the US open, where prices actually move. The first two still fire on frozen data, and the guard keeps them quiet unless price moved for real.

One lesson I’d have written up right there, if I’d stopped at this point: a scheduled job’s cadence should be derived from when its inputs change, not from when you’d like to read the output. I’d had that backwards for five releases.

Then it happened again

Five days after that guard shipped, I was searching my mail for something unrelated and saw this:


Tue 16:08 GOOG signal weakened
Tue 19:43 GOOG signal strengthened
Tue 22:33 GOOG signal weakened

The same whipsaw. Three flips in six and a half hours, two of them on runs where the US market was shut and the candles were frozen. The guard I’d just written, tested, and blogged about in my head was sitting right there in the code path, doing nothing.

The reason is a good one, in the sense that I’d never have found it by re-reading the guard. GOOG is a watch-list ticker.

Watch-list tickers are deliberately excluded from report.items — that’s the whole design, the thing that stops them polluting allocation percentages. But the intraday price map was built like this:


const priceMap: Record<string, number> = {};
for (const item of report.items) { // ← watch-list tickers are not in here
  priceMap[item.ticker] = item.price;
}

So for GOOG, morningPrice and currentPrice were both 0. And look again at what the guard requires:


if (
  triggerType &&
  config.minPriceMovePctToAlert > 0 &&
  morningPrice > 0 && // ← false
  currentPrice > 0 && // ← false
  Math.abs(priceDelta) < config.minPriceMovePctToAlert
)

It fails open on missing prices — the decision I described two paragraphs ago as deliberate, and still think is right for a genuine data gap. Except this wasn’t a data gap. The prices existed; they just weren’t in the map I handed the guard. So the guard didn’t fail open on bad data, it quietly declined to run at all, for exactly the tickers a feature in the same release had introduced.

Two v1.8 features that don’t compose, which is a recurring hazard in AI portfolio monitoring: the watch list can raise intraday alerts, and the guard that silences noisy intraday alerts couldn’t see watch-list tickers. Neither feature is wrong in isolation. Nobody reviewing either diff would catch it.

The fix, shipped as v1.8.1, is small — one shared builder, used by both the daily baseline and the intraday comparison, so the two maps can’t drift apart again:


export function buildPriceMap(report: AllocationReport): Record<string, number> {
  const map: Record<string, number> = {};
  for (const item of report.items) map[item.ticker] = item.price;
  for (const item of report.watchingItems) map[item.ticker] = item.price;
  return map;
}

The lesson I actually took, which is better than the cron one:

A fail-open guard cannot tell you it isn’t running. Mine had no way to distinguish “I checked and this is a real move” from “I had no data so I waved it through,” and both outcomes look identical from outside: an alert arrives. I’d built a safety net, verified it on the case that motivated it, and never asked which inputs it silently didn’t cover. Every day it did nothing on GOOG, the observable behaviour was the same as a working guard on a genuinely moving stock.

The concrete practice I’d extract: when a guard fails open, the fail-open branch deserves a log line and a test of its own — not just the happy path. And the regression test that matters is not “does the guard suppress noise” (it always did, when it ran). It’s “does every ticker that can produce an alert have the data the guard needs?” That’s a coverage question about the inputs, not a behaviour question about the function, and it’s the test I didn’t have:


test("every watch ticker gets a non-zero price (the guard needs > 0)", () => {
  const map = buildPriceMap(report);
  for (const w of report.watchingItems) {
    assert.ok(map[w.ticker] > 0, `${w.ticker} must have a price or the guard fails open`);
  }
});

The price that lied

Same theme, different surface. Any AI portfolio monitoring pipeline has to decide which price is authoritative, and v1.7 already preferred the freshest quote — after-hours → pre-market → regular close — because a brief showing yesterday’s close after an earnings gap is useless.

But it only swapped quote.price. Everything derived from price kept using the close. So on a big earnings gap the brief would show the fresh price beside a P/E and a 52-week position both still computed off the stale close — a ticker up 15% after hours would print the pre-gap P/E, making it look cheaper than the price I was actually being asked to pay. Internally inconsistent, and worse, the AI was reasoning about a valuation that didn’t match the price it was given.

The fix is arithmetic, not cleverness. EPS is fixed between earnings reports, so P/E scales linearly with price:


const ratio = latest.price / regularPrice;
if (quote.trailingPE != null) quote.trailingPE *= ratio;
if (quote.forwardPE != null) quote.forwardPE *= ratio;
if (quote.fiftyTwoWeekHigh != null && quote.fiftyTwoWeekLow != null && ...) {
  quote.fiftyTwoWeekPercent = /* recompute from latest.price within the 52w range */;
}
quote.price = latest.price;

Then the same question for the moving averages, where it gets more interesting. Distance from the 50/200-day MA should obviously use the fresh price — that’s the number I’m acting on. But feeding a spot price into a series derived from raw chart closes has a units trap:


export function resolveTrendPrice(closeLast: number, spotPrice?: number | null): number {
  if (spotPrice != null && spotPrice > 0 && closeLast > 0) {
    const ratio = spotPrice / closeLast;
    if (ratio >= 0.5 && ratio <= 2) return spotPrice;
  }
  return closeLast;
}

That ±50% band catches two real failure modes I hit. Sub-unit currencies : LSE tickers quote in pence, and my pipeline divides quote.price by 100 to normalise — but the raw chart closes aren’t divided, so the ratio comes out at 0.01 and the MA distance would read as a 99% crash. And thin after-hours prints : an illiquid ticker can trade at an absurd price on a handful of shares after the close, which isn’t a move, it’s an artifact.

The line I had to draw carefully: oscillators (RSI, MACD, Bollinger, Stochastic), ATR%, the 90-day percentile and the 1-day change all stay on completed daily closes. They’re defined on the close series. You can’t retrofit a single spot price into a 14-period average and call it an update — you’d get a number that looks precise and means nothing. Only the metrics that are genuinely “price versus a reference level” get the fresh price.

Both of these bugs, and the whipsaw, are the same mistake in different costumes: mixing data from two different clocks and not noticing.

The check that wasn’t running

The most expensive instance involved no bug at all — just a rule that quietly had nothing to do.

Any AI portfolio monitoring setup running two models needs a policy for disagreement. Mine is the unanimity rule : a STRONG BUY requires every configured provider to vote STRONG BUY independently, otherwise the consensus caps at BUY. Four lines, and they’re the whole justification for paying two models to look at the same portfolio. (Part 2 has the full consensus logic.)

On 23 June my system produced the strongest signal it has ever produced: a STRONG BUY on MSFT at 91% confidence, with six independent entry signals and an RSI of 9.3. I read it and acted on it. Part 4 covers what that trade did.

Six weeks later, writing this, I went looking for the run — and found that Gemini was down that day , quota-exhausted. That STRONG BUY was one model, alone.

Which means the unanimity rule never ran:


function computeConsensusAction(scores: ProviderScore[]): string {
  if (scores.length === 0) return "HOLD";
  if (scores.length === 1) return scores[0].action; // ← straight through
  // ... tally, tiebreak, then the unanimity rule
}

One provider, so the action passes through untouched. No unanimity check, because unanimity among one model is trivially satisfied.

This is the graceful degradation I wrote up in the v1.7 notes as a feature, and it is one — a provider hitting its quota shouldn’t cost me the whole brief. But look at what it produced. My largest signal skipped the exact safeguard I’d built to make STRONG BUY mean something, and nothing in the output said so. No avg tag, no agreement badge, no “1 of 2 providers responded” line. Just a clean 91%, identical in every visual respect to a vetted consensus.

Graceful degradation is fail-open by another name. When Gemini dropped out, the system silently downgraded from “two models must agree” to “one model decides” — a materially weaker guarantee, presented in exactly the same language as the strong one.

Which is the GOOG whipsaw wearing different clothes. There, a guard didn’t run because its inputs were missing, and the output looked like a guard that had run and approved. Here, a rule didn’t run because a provider was missing, and the output looked like a rule that had run and approved. Both times the absence of a check was invisible at exactly the moment it mattered.

v1.9.0 exists because of this. Every recommendation from a degraded run now carries what was lost:


degradation: { configured: 2, answered: 1, missing: ["Google Gemini"] }

and STRONG BUY caps at BUY, because cross-provider agreement is part of the STRONG BUY criteria and it demonstrably did not happen. The email shows a ⚠ 1/2 AI badge with the missing providers in the tooltip, Telegram shows the same tag — and both render even in single-provider mode , which is the entire point. That’s exactly where the old code hid it.

Run that same 23 June brief through today’s code and MSFT arrives as BUY 91% ⚠ 1/2 AI. Same analysis, same reasoning, same outcome — but labelled as the unverified single-model call it actually was, which is the only thing I ever wanted from it.

One case is deliberately left alone: if you only ever set one API key, nothing changes. That configuration never promised unanimity, so it isn’t degraded — no cap, no badge. It has its own negative test, because getting that wrong would silently downgrade every single-key user’s recommendations, which would be the same category of mistake in the opposite direction.

Capping is configurable (ai.strongBuyRequiresAllProviders: false keeps the survivor’s action). The badge isn’t. Whether a lost guarantee should change the recommendation is a judgement call; whether you get told about it isn’t.

What connects all of this

Six incidents in one release window, and they’re the same incident:

The safeguard	Why it wasn’t running	What I saw
Frozen-data deadband	watch tickers had no price in the map; the guard fails open on missing prices	an alert arrived, looking like a real move
STRONG BUY unanimity rule	one provider answered, so consensus short-circuits	a clean `91%` card, looking vetted
Fresh-price consistency	P/E and 52w position still computed off the stale close	a brief where every number looked like it agreed
Production `state/`	my local directory is a separate lineage from the Actions cache	a plausible file on disk with nothing to do with production
`AI_DETAILED_PROVIDER` fallback	validated once, then overridden downstream with the raw env value	a pinned provider that would fail every ticker
The test suite itself	`npm test` enumerated three filenames by hand, so new test files never ran	`104 passing`, green, confident

The fifth annoys me most, because the fallback was correct. pickDetailedProvider() checked whether the pinned provider had an API key and fell back when it didn’t. Then thirty lines later, the per-ticker loop did this:


explicitOverride === "gemini" || explicitOverride === "claude"
  ? (explicitOverride as DetailedProviderId) // ← never verified it was configured

and threw the decision away. I’d written the guard, written the fallback, and then quietly bypassed both from the code that consumed them. A working safeguard and a bypassed one are indistinguishable until the day the bypass matters.

The last one deserves its own moment. I wrote nine tests for the v1.9 fix, ran the suite, watched it report a clean pass — and the count hadn’t moved, because the runner was a hardcoded list of three files:


- "test": "node --import=tsx/esm --test test/util.test.ts test/social.test.ts test/intradayCompare.test.ts"
+ "test": "node --import=tsx/esm --test test/*.test.ts"

A test that isn’t executed looks exactly like a test that passed. I had spent the previous hour writing about precisely this failure mode, in the tool I was using to verify the fix for it. The real total was 113 all along, with 9 of them not running.

None of these six threw. Nothing logged a warning. In every case the degraded output was rendered in exactly the same visual language as the healthy output, which is why they all survived for weeks and why I found each one by accident rather than by looking.

The shared root cause isn’t carelessness in any single diff — each is defensible in isolation, and I’d approve all six in review today. It’s that I only ever tested the presence of a check, never its absence. I had tests proving the deadband suppresses noise. I had none asking which tickers it could see. I had a unanimity rule with a clear spec. I had nothing asserting it was in force on the run that produced a STRONG BUY. I had a green suite. I had nothing checking the suite was running what I thought it was.

Four practices I’m taking forward:

Every fail-open branch gets a log line. If a guard waves something through because data was missing, that’s an event, not a non-event. Silence should mean “checked and fine,” never “couldn’t check.”
Test the inputs, not just the behaviour. The regression test that would have caught the GOOG bug isn’t “does the guard suppress noise” — it always did, when it ran. It’s “does every ticker that can raise an alert have the data the guard requires?” That’s a coverage assertion about inputs, and a different shape of test than I was writing.
Degraded modes must be visibly degraded. If two providers are configured and one answers, say so on the card. A guarantee I can silently lose is not a guarantee.
Testability is a design constraint, not a chore. Two modules I needed to test couldn’t be imported at all: config.ts reads config.json at module load and throws when it’s absent, and CI runs without one — so anything importing it, directly or three hops away, was permanently untestable. That’s not a testing problem, it’s a coupling problem wearing a testing problem’s clothes. Both got split into a pure module taking config as an argument and a thin wrapper injecting it. The tests I wanted became possible the moment the coupling went.

None of that is specific to AI portfolio monitoring, or to AI at all. It’s what happens when you build defences and then only ever verify them on the day you wrote them.

An AI portfolio monitoring tool’s real failure mode isn’t being wrong — it’s being noisy enough that you stop reading it. I’d started ignoring my own Telegram alerts before the frozen-data guard shipped. The reason I trust them now isn’t that I added a guard; it’s that I went and checked the guard was running.

Next: Part 2 — the free LLM API stack behind it, including the provider I had to replace when its balance ran out.

Richfolio is open source: github.com/furic/richfolio · docs

The post AI Portfolio Monitoring: Every Safety Net Failed Silently appeared first on Richard Fu.

Background agents that feel alive and cost almost nothing

Richard Fu — Thu, 30 Jul 2026 15:31:37 +0000

Most games are full of things that don’t matter. The crowd behind the fence, the birds, the cars in the next lane over — none of it is gameplay, but all of it is the difference between a world and a set. The catch is that “doesn’t matter” has to also mean “doesn’t cost much,” because the moment your ambient decoration starts eating frame time you’ve paid a lot for something the player was never looking at directly.

I recently built a lane of background traffic that had to read as a believable stop-and-go jam, play engine audio, and physically block the player under one specific condition — all while staying cheap enough to run on mobile WebGL. The three problems it solved are ones you hit with almost any ambient system: how to make many agents move convincingly, how to make them sound right without a wall of audio sources, and how to give them physics without paying for it every frame.

Here’s how each one works, with the game-specific parts filed off.

One controller, no per-agent scripts

Before any of the tricks: the whole system is a single MonoBehaviour that owns a flat list of lightweight structs. There are no MonoBehaviours on the individual agents, no per-agent Update, and — until the very end — no colliders. Every agent is just a Transform plus a few floats.


class Agent {
    public Transform t;
    public float halfLength; // measured from renderer bounds at spawn
    public float speed; // current, always >= 0
    public bool rolling; // in a "go" phase, or paused?
    public float moveBudget; // distance still owed this go-phase
    public float stopTimer; // seconds left in the current pause
}

This matters more than it looks. A hundred Update() calls have real overhead in the engine’s script dispatch, and a hundred MonoBehaviours is a hundred managed objects the GC has to know about. One loop over a List<Agent> is cache-friendly, trivially cheap, and — a nice side effect — completely deterministic if you feed it your own RNG instead of the global one.

1. A jam that moves like a jam

The naive version of moving traffic is a conveyor: every car drives at the same constant speed, spacing never changes. It reads as “cars exist,” never as “traffic.” A jam is the opposite — dense, mostly stopped, lurching forward in fits. Getting that feel taught me two non-obvious lessons.

Pack tight, brake late

The obvious model is car-following: each agent looks at the gap to the one ahead and picks a safe speed from it. The standard safe-following formula is


float safe = Mathf.Sqrt(2f * brake * Mathf.Max(0f, gapAhead - stopDistance));

which is just “how fast can I go and still brake to a stop before I hit them.” Reasonable. But look at what it does when cars are packed bumper-to-bumper: gapAhead ≈ stopDistance, so safe ≈ 0. The default state of a tightly packed line is frozen. Nothing moves unless something ahead of it opens room first, which means motion can only ever trickle backward from whatever agent happens to have open road in front of it.

That’s fine for a line whose leader has somewhere to go. It is fatal for a line whose leader doesn’t — say, oncoming traffic in a world that scrolls past the player, where the “front” of the line is constantly being consumed at the edge before it can pull anyone. One lane flows, the mirror-image lane sits frozen for ten seconds at a time. Same code, opposite behaviour, purely because of which end has runway.

The fix is to stop conflating two different distances:

Packing distance — how close cars sit when stopped (visual density).
Braking distance — how close a car gets before it actually brakes.

Make the braking distance much smaller than the packing distance:


// packingGap ≈ 2.5 (how dense the jam looks)
// brakeGap ≈ 0.6 (how close before braking)
float safe = Mathf.Sqrt(2f * brake * Mathf.Max(0f, gapAhead - brakeGap));

Now a car sitting at its normal packed spacing still has packingGap - brakeGap of headroom, so it can creep at full crawl speed. The line stops behaving like a gridlock (“frozen unless pulled”) and starts behaving like a conveyor (“moving, braking only to avoid a bump”). Direction stops mattering. Every lane flows.

This is the kind of bug that’s invisible in the math and obvious the moment you watch it: the model was technically correct and produced a dead lane.

Commit to a distance, not a duration

For stop-and-go, each agent alternates between “go” and “stop” phases. The tempting way to time a “go” phase is a clock: drive for N seconds, then pause. Don’t. In a jam an agent spends most of a wall-clock “go” phase blocked — pressed up behind a stopped car, burning down its timer while going nowhere. By the time the road clears it has almost no “go” left, so it lurches forward a few centimetres and stops again. The whole jam does a nervous little shuffle.

Commit each move to a distance instead, and spend that budget only with actual forward progress:


if (!a.rolling) {
    a.stopTimer -= dt;
    if (a.stopTimer <= 0f) {
        a.rolling = true;
        a.moveBudget = Rand(0.8f, 2f) * (2f * a.halfLength); // 0.8–2 body-lengths
    }
}

float target = a.rolling ? crawlSpeed : 0f;
float desired = Mathf.Min(safe, target);
a.speed = Mathf.MoveTowards(a.speed, desired, (desired > a.speed ? accel : brake) * dt);

float movedBefore = a.pos;
a.pos += a.speed * dt;
ClampBehindNeighbour(ref a.pos, brakeGap); // never overlap the one ahead
float actuallyMoved = a.pos - movedBefore; // could be ~0 if blocked

if (a.rolling) {
    a.moveBudget -= Mathf.Max(0f, actuallyMoved); // blocked time doesn't count
    if (a.moveBudget <= 0f) {
        a.rolling = false;
        a.stopTimer = Rand(0.4f, 1.2f);
    }
}

Because the budget only drains when the agent genuinely advances, every move covers its full one-or-two body-lengths no matter how long the agent waited for the gap to open. Blocked cars wait patiently; when the road clears they pull forward a real, visible distance and then brake. The randomised stop durations, staggered across the line, produce the backward-travelling “wave” that reads unmistakably as a jam.

An endless belt from a finite list

You never need more agents than fit on screen. Anchor a window to the camera; spawn agents to fill it; when one falls off the trailing edge, teleport it to the leading edge and re-pack it against the current front of the line. Because agents in a single lane can’t overtake (a follower always brakes before passing), their order never changes — which means recycling is just “pop the tail, push the head,” no sorting, no bookkeeping. A few dozen agents give you an infinite road.

2. Audio that only plays when it should

Give every agent a looping AudioSource and press play, and you get two problems at once: dozens of voices competing for mixer time, and a muddy drone that never stops. Neither is what “a car passing you” sounds like.

The better model treats the clip as a steady bed and does all the shaping in code. Each frame, decide whether this agent should be audible right now — is it actually moving, and is it within earshot of the listener — and drive the volume toward that:


bool audible = a.speed > movingEps
            && (a.t.position - listener.position).sqrMagnitude < earshot * earshot;

float target = audible ? baseVolume : 0f;
src.volume = Mathf.MoveTowards(src.volume, target, baseVolume / fadeTime * dt);

if (src.volume > 0.0005f) { if (!src.isPlaying) src.Play(); }
else if (src.isPlaying) src.Stop();

Three things fall out of this:

You only ever pay for audible voices. A source that isn’t near the listener never gets Play()d, so it costs nothing. In practice, out of ~80 agents only a handful are ever playing at once. 3D spatial blend and distance rolloff still handle the actual attenuation; the earshot check just avoids spinning up voices you’d never hear.
Motion gates sound. A stationary agent stays silent even if the listener is right next to it. That’s a deliberate design choice — a stopped car doesn’t make a pass-by noise — and it’s a one-line consequence of the a.speed > movingEps term.
The fade is free and continuous. MoveTowards ramps the volume up when the agent starts moving and down when it stops, so the sound lasts exactly as long as the motion, with no clicks.

One trap worth calling out: your loop clip must be constant-volume. A clip with a baked fade-in/fade-out envelope (very common for one-shot “whoosh” sounds) will pulse when you loop it, and pulse even worse when several overlap. If you’re repurposing one-shot assets into loops, flatten them to constant RMS and trim the quiet tails first, so the only volume shaping is the one you’re doing in code. Otherwise you’ll spend an afternoon convinced your fade logic is broken when it’s the source material.

3. Physics you don’t pay for until you need it

The system’s agents move every single frame. That detail alone dictates the entire physics approach, because of a mistake that’s very easy to make: a bare collider that moves is a static collider that moves, and moving a static collider forces the physics engine to rebuild its static broadphase tree — every frame, for every collider that moved. With a lot of moving colliders that’s a genuine frame-killer, and it’s worse on single-threaded WebGL builds.

The rule is simple: if a collider moves, it needs a kinematic Rigidbody. That tells the engine “this thing moves, treat it as a moving body,” and the static-tree rebuild goes away.

But there’s a second, bigger optimisation available if collisions only matter sometimes. In my case the agents only ever needed to physically block the player under one rare condition. During normal play they were pure decoration. So the colliders start disabled — zero broadphase cost — and only wake up, near the player, when that condition fires:


// At spawn: a disabled, kinematic collider on a dedicated layer.
var col = go.AddComponent<BoxCollider>();
col.enabled = false; // costs nothing until enabled
var rb = go.AddComponent<Rigidbody>();
rb.isKinematic = true; // moving collider, no static-tree churn
rb.useGravity = false;
go.layer = agentLayer;

// On the rare event, wake only what's near the actor — and keep following it,
// because the actor is moving too.
IEnumerator WakeColliders(Transform actor, float seconds) {
    float end = Time.time + seconds;
    float r2 = wakeRadius * wakeRadius;
    while (Time.time < end) {
        Vector3 p = actor.position;
        foreach (var a in agents)
            if (a.col != null && !a.col.enabled
                && (a.t.position - p).sqrMagnitude <= r2)
                a.col.enabled = true;
        yield return null;
    }
}

So the physics bill is: nothing for the entire normal run, and then a handful of small kinematic boxes for a few seconds around one event. A box collider is the cheapest shape there is, and waking three of them near the player is not something any profiler will ever flag.

Two supporting details make this behave:

Freeze the movement while the colliders are live. If your agents recycle or teleport (like the endless belt above), an agent the player is leaning against could suddenly warp away mid-contact. Halting agent movement for the duration of the event keeps the collision honest.
Use a dedicated layer and the collision matrix. Put the agents on their own physics layer and configure the matrix so that layer only interacts with the one actor that matters. This isn’t about performance so much as correctness: it stops the player’s trigger volumes (the ones that detect pickups, gates, whatever) from firing on your ambient props. A physics layer is a filter, and the cheapest collision is the pair the broadphase never even considers.

The through-line

None of these is a clever algorithm. They’re all the same instinct applied three ways: spend effort only where the player can perceive the result, and never a frame before.

The jam runs from one controller over a flat list, and only cares about the window on screen.
Audio spins up a voice only for agents that are both moving and within earshot, and lets everything else stay silent for free.
Physics stays completely inert until a specific moment, then wakes only the few colliders near the player.

Ambient systems are where budgets quietly go to die, because “it’s just background” makes it easy to justify a little waste per object, and then you have four hundred objects. The fix isn’t heroic optimisation — it’s noticing that the player can only look at, listen to, and bump into a tiny slice of the world at any instant, and building each system so that slice is the only part that costs anything.

The post Background agents that feel alive and cost almost nothing appeared first on Richard Fu.

Particle Trail Stuck at X=0: A Unity Update-Order Bug (and Six Wrong Fixes)

Richard Fu — Tue, 30 Jun 2026 15:25:04 +0000

I wanted a simple thing: a little particle trail that streams behind a fast-moving character as it runs down a lane and slides left/right. A few hours and six failed fixes later, I finally understood why the particles kept piling up in the dead center of the lane while the character was clearly off to one side.

The bug had one strange, very specific signature that I ignored for far too long:

The trail followed the character in Y and Z , but its X was always pinned to 0.

That asymmetry was the whole answer. It took me most of the session to listen to it. This is the honest version — wrong turns first, then the root cause, then the fix and the lessons.

The setup

A Unity 6 / URP game. A character runs forward automatically and is nudged left/right between lanes. I attach a looping CPU particle trail (a standard Shuriken system from an art pack) to the character so it leaves a fun streak.

In the editor, if I grab the character and drag it around by hand, the trail follows perfectly. In play mode, the streak renders in the center of the lane no matter where the character actually is. New particles don’t appear at the character — they appear at world X ≈ 0.

Wrong turn #1 — “the spawn position is wrong”

My first instinct: I’m instantiating the trail at the wrong place, or not parenting it. I “fixed” the parenting and zeroed the local position. No change.

Wrong turn #2 — “stop re-instantiating; cache and reuse”

I rewrote it to pre-instantiate one trail per type and just activate/deactivate them, reasoning that per-event Instantiate was somehow mis-placing things. Cleaner code. Same bug.

Wrong turn #3 — “it’s World-space particle semantics + speed”

I reasoned that with World simulation space , particles are stamped into the world where they’re born and left behind, and with a long lifetime over a fast run they’d stretch back toward the start (≈ X=0). So I shortened particle lifetime to make a tight “comet tail.” Same bug — still centered.

Wrong turn #4 — “use Local space, it’ll stick to the character”

I forced Local simulation space. Now the particles did stick to the character… but they clustered on it with no trailing streak at all. I’d traded one wrong behavior for another, and — critically — I never confirmed Local had actually taken effect (more on that below).

Wrong turn #5 — “add a world-space backward velocity to fake the streak”

Local emission + a world-space backward velocity to make particles hang behind. This threw Particle Velocity curves must all be in the same mode (you must set X/Y/Z velocity curves together), and when fixed, re-introduced the X=0 behavior. I’d reintroduced a world-space transform path and the bug came back with it.

At this point I had changed six things and understood nothing. That’s the signal to stop guessing and start measuring.

The measurements that cracked it

Two probes finally produced facts instead of theories.

Probe 1 — the emitter vs. the particles. I logged, every frame, the emitter’s world position and the particle system’s render-bounds center (where the particles actually are in the world):


emitter world = (1.04, 0.69, 30.28)
particle bounds center = (-0.04, 0.69, 30.24)

The emitter was genuinely at X=1.04. The particles were at X≈0. Y and Z matched the emitter; only X was wrong. So this was never a parenting bug — the GameObject was on the character. The particles were being born at the wrong X.

Probe 2 — what simulation space is actually running. The same log printed:


sim = World

…even though my code now set the field default to Local. That’s a Unity trap I’d walked straight into:

Changing a field’s default in code does not change the value already serialized on a component. The component had been saved with simulationSpace = World earlier, so every “Local” change in code was silently ignored.

So my “Wrong turn #4” had never even run as Local. Once I set the serialized value to Local, the particles finally tracked the character’s X — confirming the bug was specific to World-space emission.

The root cause: particle trail emission timing

Now the axis asymmetry made total sense. The character’s motion was split across two scripts on two different update steps :

Forward (Z) was applied in Update.
Lateral (X) was applied as an override in LateUpdate — a second controller wrote transform.position.x = laneX late in the frame.

For most of the frame, the character’s X sat at ~0 (the forward controller pulls it toward a neutral target); only LateUpdate slammed it back to the real lane value. A World-space particle system samples the emitter’s position when it emits — before that LateUpdate correction lands — so every particle was stamped at X≈0. Z was never overridden late, so Z was always correct. Hence: follows Y and Z, stuck at X=0.

It was never the prefab, the parenting, the scale, the lifetime, or the simulation space by itself. It was frame update order colliding with how/when particle systems read the emitter transform. Any World-space particle trail attached to this character would break identically — so “try a different particle pack” would have wasted even more time.

The fix: a Local-space particle trail

I stopped trying to make World-space emission work and rebuilt the particle trail on Local space, which is immune to the timing problem because it emits relative to the emitter no matter when the transform settles:

Local simulation space — emission is always at the character (correct X). Confirmed by render-bounds tracking the emitter.
A local −Z backward drift ≈ the run speed — so particles, born at the character, drift backward in the character’s frame at roughly the speed the character moves forward. Net world motion ≈ zero, so they hang on the ground and fade — a real leave-behind trail, but produced by velocity rather than by world-space emission.
Disable the prefab’s Limit-Velocity (clamp) module — it was capping speed to ~1 and damping the backward drift to nothing (particles clustered). This was the difference between “blob on the character” and “streak.”
Lower the particles’ Start Speed — the prefab fired them outward at random; with the clamp off, that randomness sprayed everywhere. A low start speed lets the drift line them up.
Spawn-per-event, self-despawning — each pickup spawns its own short-lived instance that stops emitting after its duration and destroys itself once the tail fades; long-lived trails are stopped on a game event. Simple, no pooling.

Everything became an inspector knob (drift speed, lifetime, start speed, emit height per trail type), because the “right” values are pure visual taste.

Pitfalls, collected

Listen to axis asymmetry. “Y and Z are fine, X is wrong” is not a particle problem — it’s a which-thing-touches-X-differently problem. That should have pointed me at the lateral controller and update order in minute five.
Measure the particles, not the emitter. I kept confirming the emitter followed the character (it did) and concluding “so it should work.” The particles’ render-bounds center was the only thing that mattered, and I logged it last instead of first.
Don’t trust idle samples. An early probe showed the character at (0,0,0) and I briefly concluded “the world scrolls, the character is stationary.” It was just sampling before the run started. One bad sample sent me down a whole wrong model.
Serialized values silently override code defaults. Changing a public field’s initializer doesn’t touch components already saved in a scene/prefab. If a code change “does nothing,” verify the actual runtime value, not the source default.
Particle velocity curves are all-or-nothing per mode. Set X/Y/Z together or Unity throws.
A “Limit Velocity over Lifetime” module will quietly eat any velocity you add. If your forces seem to do nothing, check the clamp.
Six fixes without a measurement is a process failure, not bad luck. The rule should kick in much earlier: after the second failed fix, stop and instrument.

Self-reflection

The technical lesson is real (update order vs. particle emission timing, and Local-space + drift as a robust workaround). But the meta-lesson is the one that actually cost the hours: I pattern-matched to plausible causes — parenting, instantiation, world-space semantics — and “fixed” each before I had any evidence it was the cause. Every one of those fixes was a guess wearing a confidence costume.

The turning point wasn’t cleverness; it was switching from explaining to measuring — logging the emitter against the real particle positions, and printing the runtime simulation space instead of assuming my code default applied. Both took five minutes and immediately ended the guessing. The clue I needed (Y/Z follow, X doesn’t) was in the very first bug report. Next time: when a symptom is that specific, treat the specificity as the lead, and reach for the probe before the fix.

And there was a second clue I held the whole time and failed to read. Early on I’d parented the trail under the character and, in play mode, dragged the character around by editing its Transform position by hand — and the trail followed perfectly. I filed that under “so the parenting is fine” and moved on. But it was telling me something sharper: a manual Inspector edit sets the transform directly and statically — it is not re-applied every frame by a script, so it never participates in the Update→LateUpdate tug-of-war that the runtime controllers do. With the scripts off the hook, the emitter X just sat at the value I dragged it to, and World-space emission sampled it correctly. The only difference between “works” (manual drag) and “broken” (play mode) was whether scripted, frame-ordered position updates were involved at all. That contrast points almost directly at update timing — if I’d asked “what is different about how position gets set in the two cases?” instead of “is it parented?”, I’d have arrived at the LateUpdate override hours earlier. A test that works is not just reassurance; the reason it works is often the diagnosis.

The post Particle Trail Stuck at X=0: A Unity Update-Order Bug (and Six Wrong Fixes) appeared first on Richard Fu.

Unity WebGL Particles Invisible? Causes and How to Fix It

Richard Fu — Sun, 28 Jun 2026 15:39:18 +0000

I spent the better part of a day chasing a celebration firework that played perfectly in the Unity editor and rendered absolutely nothing in the WebGL build. No errors. The particles spawned, played, sat right in front of the camera — and stayed invisible.

I diagnosed it confidently four times. The first three were wrong. The only thing that ever found truth was a dumb A/B test in the actual build — not in the editor, not by reading shaders, not by theorizing. That turned out to be the real lesson, so I’ll tell it honestly — wrong turns and all — and then map out what WebGL genuinely can and can’t do with particles.

The setup

A Unity 6 / URP mobile-style game shipped to WebGL. The win screen opens a treasure chest with a firework burst and a soft neon glow over the whole scene. Two things broke only in the WebGL build:

The bloom/glow was missing.
The firework was completely invisible — despite the particle system clearly running.

They turned out to be unrelated, which is part of why this took so long.

Wrong turn #1 — right, but only for the glow: shader variant stripping

URP strips “unused” shader variants from builds to save size, and the editor never strips. So editor-works / build-doesn’t should make you suspect stripping first.

The missing bloom was exactly that — URP’s Bloom post-processing variant was being stripped on WebGL (Strip Unused Post Processing Variants). Disabling it brought the glow back (I later moved the glow to MK Glow , a renderer feature — see the quality-tier trap below).

Good fix — for the glow. Then I made the classic mistake: I assumed the firework had the same villain.

Wrong turn #2 — “the Shader Graph must render black on GLES3”

The firework was from a popular Shader-Graph-based pack (Cartoon FX Remaster). I instrumented the celebration code:


firework diag @t=2.5s: totalParticles=164 anyPlaying=True anyVisible=True
shaders=[Cartoon FX/Remaster/Particle Procedural Glow, Particle Ubershader]

Particles exist , system playing , renderer on-screen , real shaders (not the magenta error shader). Yet no visible color — even when I cranked a glow pass to blow out the whole screen, the firework area simply never appeared.

My conclusion sounded airtight: Unity WebGL = WebGL 2.0 = OpenGL ES 3.0 , and Unity cross-compiles its HLSL down to GLSL ES 3.00. For a big particle “ubershader,” I figured the cross-compiler was emitting GLSL that compiles but outputs black — a translation bug that bites only on the GLES3 path, never in the editor (Metal/D3D).

Plausible. Confident. Wrong — as I’d find out two diagnoses later.

The fix that worked — for a different reason than I thought

I swapped the Shader-Graph firework for an Epic Toon FX firework — CPU ParticleSystem (Shuriken) + URP/Particles/Unlit. Plain, old, boring tech. It rendered in the editor immediately.

…and was invisible in the WebGL build. Again.

Wrong turn #3 → the first confirmed truth: Soft Particles need a depth texture

Same signature — plays in editor, audio + feedback fire (so it’s emitting), nothing on screen. But this time the cause was real and provable. I inspected the live materials:


shader: Universal Render Pipeline/Particles/Unlit
keywords: [..._SOFTPARTICLES_ON...] _SoftParticlesEnabled = 1
URP 'High' (WebGL tier): supportsCameraDepthTexture = False

Soft Particles — the fade where a particle meets opaque geometry — needs the camera depth texture , and the WebGL tier wasn’t generating one. With no depth bound, the fade reads an unbound texture: desktop returns “far” (visible); WebGL GLES3 returns 0 → alpha ≈ 0 → fully transparent. Same material, opposite result per platform. No shader error — it compiles fine and fades itself to nothing.

Confirmed via the WebGL console (Playwright): zero shader errors — a runtime fade, not a compile failure. The fix was one toggle: turn Soft Particles off (an open-air firework never intersects geometry, so they did nothing anyway). The firework finally rendered on WebGL. 🎆 It’s also why the coins were fine the whole time: opaque, no soft particles, no depth dependency.

So I’d “solved” it — and, generalizing, told myself the original CFXR firework must have been soft particles too. Tidy unified theory. Also wrong.

The reckoning: a 30-second A/B test demolishes my Shader-Graph theory

The chests also carried a CFXR glow halo (CFXR3 LightGlow A (Loop)). If “CFXR renders black on WebGL” were true, those would be invisible too. So I tested it the only way that matters — in the build : two chests at the start line, one with the CFXR glow, one without.

The one with the CFXR glow glowed. On WebGL. The pack I’d declared “renders black” was rendering just fine.

So I pulled the shader keywords of a CFXR material that works (the glow) and one that fails (the firework):


WORKS "cfxr stretch ray blur add" → _CFXR_ADDITIVE, _FADING_ON
FAILS "cfxr stretch trait blur add" → _CFXR_ADDITIVE, _FADING_ON ← identical

Identical shader, identical keywords, identical soft-particle settings — one renders, one doesn’t. That kills every shader-level theory at once: not the Shader Graph, not the variant, not soft particles, not HDR. The same compiled shader draws in the loop-glow and draws nothing in the firework burst.

The real differentiator is at the ParticleSystem / effect level — the failing effects are complex one-shot bursts (sub-emitters, velocity, lifetime curves, the pack’s lifecycle script); the working one is a simple loop glow. Something in the burst machinery doesn’t survive the WebGL runtime — particles spawn and the renderer reports on-screen, but they contribute no visible pixels. I never pinned the exact module, and didn’t need to: the game ships the working glow + the fixed CPU firework.

The honest scoreboard:

The glow was shader-variant stripping. ✅ correct
The CPU firework was Soft Particles + no depth. ✅ confirmed
“CFXR renders black on GLES3”? ❌ wrong. CFXR renders on WebGL; some of its burst effects don’t, for a non-shader reason I never proved.

Three confident diagnoses, one survivor. The thing that exposed each wrong one was the build , not the editor.

Which Unity WebGL particles actually render (a GPU-feature wall)

The useful map. WebGL 2.0 / GLES3 supports modern vertex/fragment shaders (GLSL ES 3.00) but has no compute, geometry, or tessellation shaders.

Tech	Runs on WebGL2?	Why
Built-in / URP standard shaders	✅ always	simple frag/vert, cross-compiles cleanly
CPU `ParticleSystem` (Shuriken)	✅	CPU sim + standard shaders
Shader Graph	✅ usually	generates a normal shader; mostly fine on GLES3
VFX Graph	❌ never	GPU-simulated via compute shaders — absent on WebGL2
Geometry / tessellation	❌ never	absent on WebGL2

I deliberately softened the Shader Graph row from my first draft — I’d written “can render black,” but my own A/B test later showed the Shader Graph renders fine and the failures were elsewhere. Shader Graph is an authoring tool that emits an ordinary shader: treat it as “usually fine, verify in build,” not “cursed.”

VFX Graph is the categorical wall: it simulates particles on the GPU via compute shaders, and WebGL2 has no compute, so it can’t run at all. That’s why “Realistic Fireworks — VFX Graph, supports URP!” asset-store packs are a non-starter for WebGL.

“Supports URP” describes the render pipeline, not the platform. Your constraint is WebGL, not URP.

A bonus trap: the editor lied via the quality tier

When I added MK Glow it rendered in the WebGL build but did nothing in the editor — sliders had no effect. I burned time on render-graph theories before introspecting the live editor:


QualityLevel 2 (PC) → PC_Renderer (no MK Glow)
QualityLevel 3 (High)→ Default_Forward_Renderer (has MK Glow) ← WebGL uses this

The editor was previewing on the PC tier — a different renderer than WebGL’s High tier — so my feature wasn’t even in the active pipeline. Setting the editor to High gave instant preview. Bonus gotchas from the same hole: the Scene view doesn’t render custom renderer-feature passes (only the Game view does), and Volume edits made during Play mode revert on Stop.

Unity ↔ three.js (because the compute wall is universal)

The same wall shows up in three.js — with a different escape hatch.

Concept	Unity	three.js
Shader authoring abstraction	Shader Graph	TSL (Three.js Shading Language)
Raw shader code	HLSL / ShaderLab	GLSL / WGSL
GPU compute	Compute Shaders (HLSL)	WebGPU compute / TSL compute fns
GPU particle sim (compute)	VFX Graph	GPU-compute particles (TSL + WebGPU)
CPU particle sim	Shuriken `ParticleSystem`	CPU-updated `Points`/sprites

Two things people (me included) get backwards:

TSL ≈ Shader Graph, not VFX Graph. It’s an authoring layer — you write shading logic in a JS node API and TSL compiles it to WGSL (WebGPU) or GLSL (WebGL2 fallback). It can also author compute, but that’s one capability, not its identity.
The equivalent of VFX Graph is GPU-compute particles built with TSL compute on the WebGPU renderer — the technique, not the language.

The strategic difference today: three.js is well ahead on WebGPU (its WebGPURenderer + TSL are production-usable, and WebGPU browser support is real and growing), so you can ship GPU-compute particles there if you target WebGPU. Unity’s web export is still WebGL2/GLES3 (its WebGPU backend is experimental), so for a shipping Unity web game you assume no compute → no VFX Graph , and CPU particles + standard shaders are the lane. The “realistic GPU fireworks” I wanted would be on the table in three.js-on-WebGPU; on Unity-on-WebGL2, the boring CPU ParticleSystem was the right — and only — answer.

Takeaways

Test in the actual build — every time. The editor renders through a different backend (Metal/D3D), often a different quality tier, and never strips shaders. Every wrong diagnosis came from trusting the editor or my own reasoning; every correction came from the build.
Invisible particles have several unrelated causes — shader-variant stripping, Soft Particles (no depth texture), and particle-system quirks all produce the same “spawns, on-screen, invisible.” Don’t pattern-match the second case to the first.
Soft Particles need the depth texture the WebGL tier doesn’t provide → silent fade to invisible. Turn them off, or enable Depth Texture (at the cost of a pass).
VFX Graph never ships to WebGL (needs compute). Shader Graph usually does — verify in build; don’t assume it’s “black on GLES3.”
“Supports URP” ≠ “supports WebGL.” Platform, not pipeline, is the constraint.
Know when to stop. I never fully pinned why the CFXR firework burst was invisible here (CFXR otherwise renders fine on WebGL — the chest glow proves it). Once a reliable alternative worked, the forensics weren’t worth it.
Stay humble about confident diagnoses. I had three airtight ones. A 30-second in-build A/B test beat all of them.

The firework glows now — a CPU particle system from decade-old tech, lit by a renderer-feature glow, rendering happily in a browser. Sometimes the boring tool is the right tool. And the fastest debugger is often two objects side by side in the actual build.

The post Unity WebGL Particles Invisible? Causes and How to Fix It appeared first on Richard Fu.

Building MESH: A Civic Resilience Platform With AI Agents

Richard Fu — Sat, 23 May 2026 08:27:29 +0000

A one-day hackathon project at the Claude Impact Lab (Melbourne, May 2026). The brief was open. I built MESH — Melbourne Exchange & Solidarity Hub — a gamified civic platform where residents see their suburb as a node in a network and AI agents read live open data to suggest the most useful thing the community can do next.

1. Why MESH

Every Australian suburb is sitting on quiet abundance. Gardens that produce too much. Retirees who could teach welding. Neighbours who’d happily check on each other in a heatwave if anyone asked. The capacity exists. The wiring doesn’t.

Three observations led me to MESH:

Civic capacity is fragmented. There’s no shared map of who can teach what, who has spare zucchini, who’s ready in a heatwave. The information lives in group chats, in heads, in council PDFs nobody reads.
Open data is inert. data.melbourne.vic.gov.au alone publishes 239 datasets. Almost none of them inform a decision a resident will make this week. The data isn’t missing — the loop is.
The unit of resilience is the suburb. “City-wide” is too coarse to coordinate. “Neighbourhood” is too granular to measure. The 3-km suburb — Carlton, Footscray, Brunswick — is the natural unit. So MESH scores, narrates, and gamifies at that scale.

The vision: each Melbourne suburb gets a resilience index (R-index) derived from five pillars — food security, skill density, resource sharing, social connectivity, emergency preparedness. AI agents read each suburb’s data and suggest the most impactful initiative residents could run this week. Completing it earns XP. The suburb’s score moves. The board updates. Other residents see it. It is meant to feel like a slow-motion multiplayer game.

2. What it does — a five-minute tour

The map

The home page is the centrepiece. A real Google Maps WebGL view of inner Melbourne with five suburb polygons (OSM-sourced) colour-coded by R-index. Clicking a suburb (or a sidebar row) tilts the camera to 2.5D, zooms in, and reveals 3D building extrusion native to the basemap. A top-r_index suburb gets a permanent pulsing golden ring; every selection fires a screen-projected burst animation; flowing dots travel along the inter-suburb lines as a stand-in for potential exchange capacity.

A small (i) provenance icon next to the suburb name expands a panel showing exactly where that suburb’s data came from — real / partial / SEIFA-approximated — with links to each underlying dataset. The detail card also embeds a live advisor chat that streams Claude responses contextualised to the selected suburb.

The quest board

Five hand-curated EXAMPLE quests load on first paint (one per suburb, each targeting that suburb’s weakest pillar). A single click — “Regenerate with Claude →” — replaces the seed with a fresh AI-generated quest, marked AI , that persists to localStorage so it survives a refresh. Quests generated from the advisor chat appear here too — the two surfaces share state.

The pitch + the admin surface

There’s also /pitch (a long-form editorial walkthrough I built for the hackathon judging panel — Fraunces display type, scroll-paced narrative covering vision, pillars, the data → quest → XP loop, the six agents, honest data provenance, the stack, the roadmap) and /admin (gated on profile.is_admin === true, used to bulk-regenerate every quest with Claude in front of a live audience).

/login has demo personas — pick Maya from Carlton, Tom from Brunswick, Sofia from Footscray, the Admin operator, or play yourself.

3. Real data, transparent AI

This is the bit I’m most proud of.

Real open data with honest provenance

The five suburb pillar scores aren’t made up. They’re pulled by scripts/seed-suburbs.ts from three live Melbourne open-data feeds:

social-indicators-for-city-of-melbourne-residents-2023 (City of Melbourne resident survey)
landmarks-and-places-of-interest (community-facility density within 1.5 km of each centroid)
pedestrian-counting-system-monthly-counts-per-hour (foot traffic → social-connectivity proxy)

Plus ABS 2021 SEIFA IRSD deciles as the fallback for any pillar without a direct signal, and OSM via Nominatim for the boundary polygons.

The catch: data.melbourne.vic.gov.au only covers the City of Melbourne LGA. So of my five demo suburbs, only Carlton has full real data. Fitzroy gets partial coverage (sensors and landmarks reach across the LGA border). Brunswick, Footscray, and Richmond — different LGAs — fall back to SEIFA approximations.

Rather than hide that, I made it the brand. Every suburb’s detail card shows a real / partial / seifa chip with links to the exact datasets used. The /pitch page has a full provenance table. The mock-suburbs.ts file has a per-suburb comment header showing the derivation for the most recent seed run. The schema even has a data_source column on the suburbs table to enforce this at the database level.

The “we tell you what’s real” framing is more interesting than any made-up score.

Glass-box AI

There are six agents in the design (see AGENTS.md); three are wired end-to-end today: Quest Generator (returns one structured JSON quest for a suburb), Initiative Advisor (streaming SSE chat grounded in the selected suburb’s context), and Suburb Narrator (weekly plain-English digest).

Every AI quest card surfaces why it exists, in two layers.

Always visible — the signal strip (amber left-border, between badges and description):

SIGNAL · Claude targeted food security because Carlton scored 27/100 — the lowest of its five pillars.

This is the smallest possible “data → AI choice” lineage: one sentence, one number. The audience sees in plain English which pillar was lowest and why the agent picked it.

Expandable — “How this was created”:

The model name (claude-sonnet-4-20250514)
Generation timestamp
The full input the model saw (suburb · SEIFA · population · season)
The weakest pillar + score (what triggered the choice)
All five pillar scores at generation time as F/S/R/C/E chips
A link to /pitch#provenance for the underlying datasets

The agent endpoint at src/routes/api/quests/+server.ts returns the data_snapshot alongside the quest, the snapshot persists with the quest in localStorage, so refreshing keeps the panel populated. The DB schema already has a data_snapshot jsonb column on the quests table — when Supabase comes online the persistence layer is already aligned.

No vibe-based moderation. Every AI decision is auditable in the UI.

The output discipline is strict: all JSON-returning agents end their system prompt with OUTPUT: Return ONLY valid JSON. and route raw output through a parseAgentJSON() helper that strips accidental json fences before JSON.parse. The advisor is streamed without parsing — its SSE response body pipes straight to the browser. Cost guardrails baked in: max one quest generation per suburb per 24h, narratives cached for 7 days, Matchmaker skipped when the radius is too sparse.

4. The stack, briefly

Frontend — SvelteKit 2 + Svelte 5 with runes mode + TypeScript strict. Svelte 5’s $state / $effect / $derived runes made the reactive flow — store hydration from localStorage, runtime feature-state toggles on the map, the XP-burst on level-up — read cleanly. No external state library.
Map — Google Maps Platform’s WebGL vector renderer with a Map ID configured for tilt + rotation. Pitch 67.5° + heading 20° gives cohesive 2.5D with native 3D building extrusion in the CBD. Polygon overlays sit at zIndex 1000 above the fills; flowing dots are google.maps.Polyline icons stepped via RAF. I tried MapLibre first; it works but the basemap stays flat and our 3D extrusions float — Google’s WebGL vector is the only path to coherent tilt-with-buildings without a custom tile pipeline.
AI — Anthropic Claude (claude-sonnet-4-20250514) called directly from SvelteKit endpoints (streaming SSE for the advisor; JSON-mode for everything else). Cost-guarded.
Open data — data.melbourne.vic.gov.au (Opendatasoft v2.1, anonymous reads) + OpenStreetMap via Nominatim. A one-time fetch script (pnpm fetch:suburb-geo) writes polygon boundaries to a committed JSON file.
Database — Supabase Postgres 15 + PostGIS. Schema + RLS policies fully written (13 SQL migrations) and the typed SupabaseClient<Database> is wired into a per-request server client in hooks.server.ts with a typed-Proxy fallback when env is unconfigured. Provisioning a real Supabase project is one user action away; everything else is offline-complete.
Hosting — Vercel via @sveltejs/adapter-vercel, auto-deploy on push to main. Preview deploys per PR.

5. What’s next

MESH is a 10-sprint roadmap; this hackathon got me to roughly sprint 4. The remaining headline pieces:

Sprint 7 — Submission Verifier. The agent that closes the loop: residents submit photo + text evidence of a completed quest, Claude vision verifies, XP is awarded or routed to a moderation queue.
Sprint 8 — Resource Matchmaker. The agent that powers the “Exchange” in the name. Posts of “I have 10 kg of zucchini” get semantically matched to “I need vegetables for a community kitchen” within a 10 km PostGIS <-> radius, and the mesh edges between matched suburbs light up.
Sprint 10 — Anomaly Watcher. Watches each open-data sync for deltas, classifies them as opportunity / risk / info, and spawns reactive quests or alerts.

The architecture is already shaped to land them quickly once the Supabase project is provisioned. The data-snapshot + transparency pattern I built into the Quest Generator transfers directly to each new agent.

Try it

Live demo → https://mesh-pi-topaz.vercel.app/
Source → https://github.com/furic/mesh
Pitch deck-as-a-page → https://mesh-pi-topaz.vercel.app/pitch

A few things worth clicking:

Sign in as Admin · Demo on /login, then hit “Generate all 5 with Claude →” on /admin. Watch the EXAMPLE chips flip to AI in real time.
On /quests, expand any AI quest’s “How this was created” — the full agent lineage is right there.
On /, click the (i) next to any suburb name to see exactly which datasets fed its scores.

Built in a day for the Claude Impact Lab hackathon (Melbourne, 23 May 2026). Coffee was consumed. Polygons were fetched. AI rationales were strict-JSON-fenced. The streets of Carlton tilted on cue.

The post Building MESH: A Civic Resilience Platform With AI Agents appeared first on Richard Fu.

Richfolio, three months in: AI architecture in production

Richard Fu — Fri, 22 May 2026 10:14:46 +0000

From v1.0 to v1.6 — what I rebuilt, what I borrowed, and what’s running in production for $0/month

Three months ago I shipped v1.0 of Richfolio — a zero-maintenance side project that emails me a daily AI-powered portfolio digest. I wrote about the original motivation and v1 architecture in this earlier post if you want the background.

Since then it’s gone through six minor releases. The code roughly tripled in size, the AI architecture got rebuilt from the ground up to handle production use, and I’ve been using it on my own portfolio daily. This post is a project-level update: where Richfolio is, what stack it runs on, the architectural patterns I borrowed (mostly from OpenAlice), and one concrete case study showing how those patterns paid off in v1.6.

At the end I’m looking for alpha testers, so if any of this is interesting and you’ve got a portfolio that doesn’t look like mine, keep reading.

What Richfolio is now

A single Node.js + TypeScript pipeline, no API server, no dashboard. Runs as a GitHub Actions cron job (8am AEST). Four modes:

Daily — full analysis + email + Telegram
Intraday — periodic STRONG BUY change alerts (only fires on real signal changes)
Weekly — rebalancing drift report
Refresh — re-analyze a single ticker with after-hours prices

Output looks like this: a dark-themed HTML email per morning, condensed Telegram message in parallel, and for every STRONG BUY ticker, a “More Details” link to a dedicated analysis page on GitHub Pages with an interactive TradingView chart, AI-generated buy thesis, and risk analysis.

The stack — still $0/month

Everything Richfolio runs on is free-tier:

Component	Service	Free tier
Prices, fundamentals, technicals	Yahoo Finance via `yahoo-finance2` v3	unlimited
News	NewsAPI.org	100 req/day
AI analysis	Google Gemini 2.5 Flash	250 req/day
Email delivery	Resend.com	3,000/month
Push notification	Telegram Bot API	unlimited
Scheduler	GitHub Actions cron	2,000 min/month
Static hosting	GitHub Pages	unlimited
State persistence	`actions/cache`	unlimited

No database. No queue. No server. State is a JSON file in the repo that survives cron runs via actions/cache. The full cost ceiling for a single user is the Resend tier — and Richfolio sends maybe 60 emails a month, so there’s headroom for ~50 users on a single account.

The interesting constraint isn’t the budget — it’s the request budget. Gemini’s 250/day cap means every “let me ask the AI” feature has to be designed around batch calls, not per-ticker calls. That shaped a lot of the architecture below.

Architecture: patterns I borrowed from OpenAlice

The biggest single influence on Richfolio’s post-v1 evolution was OpenAlice — an autonomous AI trading agent from TraderAlice. OpenAlice is much bigger than Richfolio (multi-broker, multi-asset, with a UI) but its cognitive architecture transferred cleanly. Four patterns in particular.

1. Two-stage Think/Plan AI prompting

The v1 pipeline used a single Gemini call: shove everything into one prompt, parse one JSON response. The problem: when the AI conflates data parsing with decision-making, it hallucinates support for whatever conclusion it’s already started writing. STRONG BUY false positives crept in monthly.

The fix was to split the call into two stages, mirroring OpenAlice’s think and plan tools:

Stage 1 (Observe) — Gemini gets raw data and produces structured observations only: which price-level signals are present, which momentum signals, which risk flags, a one-line valuation summary, a one-line technical summary, news sentiment. No actions, no recommendations.
Stage 2 (Decide) — Gemini gets the observations and applies strict decision rules to produce ranked recommendations.

Two API calls instead of one — wasteful in theory, but still 2/250 of the daily quota. The practical win is significant: forcing the AI to commit to what it sees before deciding what to do dropped false-positive STRONG BUYs to near zero.

2. Post-AI guard pipeline

The other half of trustworthy AI output is not trusting the AI. OpenAlice’s guard-pipeline.ts runs sequential validation between the AI’s proposed trades and the broker. Richfolio adapts the same pattern in guards.ts:


export function validateRecommendations(
  recs: AIBuyRecommendation[],
  priceData: Record<string, QuoteData>,
  technicals: Record<string, TechnicalData>,
  report: AllocationReport,
): void {
  guardBondETFCap(recs, report);
  guardEarningsProximity(recs, priceData);
  guardStrongBuyCriteria(recs, report, technicals);
  guardMaxStrongBuy(recs);
  guardConfidenceSanity(recs);
  guardBuyValueSanity(recs, report);
}

Six sequential checks that programmatically enforce the rules I told the AI to follow. Each guard logs when it fires, so I can see which AI mistakes were caught downstream — useful signal when tuning prompts.

The architectural pattern — let the AI propose freely, validate deterministically afterward — is the single most useful idea I borrowed from OpenAlice. It makes prompt experiments low-risk.

3. Seven-day reasoning persistence

OpenAlice has a Brain module that tracks cognitive state across sessions via Git-like commits. Richfolio doesn’t need that level of machinery, but the principle — let the AI see its own past conclusions — adapts cleanly to a 7-day rolling history of AI snapshots.

Every decision prompt now receives a “HISTORICAL CONTEXT” block like:


AAPL: BUY 72% → BUY 68% → HOLD 55% — weakening
NVDA: STRONG BUY 88% → STRONG BUY 91% → STRONG BUY 89% — stable
BSV: BUY 75% → BUY 75% → BUY 75% — flat

(More on that last line in a minute.)

The history forces the AI to acknowledge trend changes. Without it, the model would sometimes flip a ticker from BUY 70% to HOLD 50% on consecutive days with no acknowledgement — which feels wrong even if individually justified.

4. Macro environment context

Yahoo Finance is free, and yahooFinance.quoteSummary('^VIX') works the same as it does for any equity. So every Richfolio run now fetches VIX, the 10-year Treasury yield, S&P 500, oil (WTI), and the USD index (DXY) — five extra calls — and pipes them as a MACRO ENVIRONMENT: preamble into both the observation and decision prompts.

This is OpenAlice’s “equity research” influence translated to a portfolio context. The macro block lets Gemini write things like “elevated VIX + high yields suggest defensive positioning” instead of generic boilerplate, and gates STRONG BUYs more conservatively in high-volatility environments.

Case study: fixing the BSV “75% BUY every day” problem

The patterns above sound abstract. v1.6 was a concrete test of whether they paid off.

Since v1.4 (which introduced the bond ETF framework back in early April), my morning email had this same line every single day:

BSV — 75% BUY — Systematic accumulation to fill 5% allocation gap.

The reason was an over-rigid prompt rule. BSV is a short-duration bond ETF — it has a ~2% annual price range, and equity-style signals like RSI and MACD are noise on a security that barely moves. So I’d hard-coded a confidence formula by allocation gap:


Gap ≥ 5%: confidence 70-75%
Gap 3-5%: confidence 60-70%
Gap 1-3%: confidence 45-55%
Gap &lt; 1%: HOLD

That removed false momentum signals but flatlined the output. With a steady ~5% gap, the answer was 75% every day forever.

The fix needed some timing signal. Just not equity timing signals. After thinking about what actually matters when buying bond ETFs, three orthogonal signals fell out.

1. Price percentile in a rolling 90-day window. Where today’s price sits in BSV’s recent range. Computed from existing chart data:


let pricePercentile90d: number | null = null;
if (closes.length >= 90) {
  const last90 = closes.slice(-90);
  const min90 = Math.min(...last90);
  const max90 = Math.max(...last90);
  if (max90 > min90) {
    pricePercentile90d =
      Math.round(((currentPrice - min90) / (max90 - min90)) * 1000) / 10;
  }
}

2. 10-year Treasury yield direction. Bonds get cheaper when rates rise. I added a 20-trading-day delta on the existing macro fetch:


case "treasury10y": {
  indicators.treasury10y = Math.round(price * 100) / 100;
  const period1 = new Date();
  period1.setDate(period1.getDate() - 35);
  const chart = await yahooFinance.chart(ticker, {
    period1, period2: new Date(), interval: "1d",
  });
  const closes = (chart.quotes ?? [])
    .map(q => q.close)
    .filter((c): c is number => c != null);
  if (closes.length >= 21) {
    indicators.treasury10yChange20d =
      Math.round((closes.at(-1)! - closes.at(-21)!) * 1000) / 1000;
  }
  break;
}

3. Distribution yield level. Yahoo’s summaryDetail.yield returns the SEC / 12-month yield for funds. High yield = high income premium.

Then a new prompt framework that scores via base + timing modifiers :


12a. SHORT-DURATION BOND ETFs:
  BASE (from gap): 5%→55, 3-5%→45, 1-3%→35, &lt;1%→HOLD
  + 90d percentile: ≤20% +12, ≥80% -15
  + 10Y 20d change: >+0.15% +6, &lt;-0.15% -12
  + Yield: >4.5% +3, &lt;3% -2

On a great day for BSV — near 90-day low, rates spiking, high yield, big gap — confidence reaches ~90. On a bad day — top of range, rates falling — it drops to ~25. Real day-to-day variance.

This is where the architectural patterns paid off. The bond ETF rewrite is exactly the kind of change I’d previously been nervous to ship — the AI could ignore the new modifiers and hallucinate a STRONG BUY on BSV, which I never want. But the guard pipeline catches it:


for (const rec of recs) {
  if (!SHORT_DURATION_BOND_ETFS.has(rec.ticker.toUpperCase())) continue;

  if (rec.action === "STRONG BUY") rec.action = "BUY";
  if (rec.suggestedLimitPrice && rec.suggestedLimitPrice > 0) {
    rec.suggestedLimitPrice = 0;
    rec.limitPriceReason = "";
  }
  if (rec.confidence > 95) rec.confidence = 95;
}

And the action-tier sort (new in v1.6) means even if BSV’s confidence reaches 90 on a great day, equity STRONG BUYs still rank above it visually:


const ACTION_PRIORITY: Record<string, number> = {
  "STRONG BUY": 0, BUY: 1, HOLD: 2, WAIT: 3,
};
recommendations.sort((a, b) => {
  const pa = ACTION_PRIORITY[a.action] ?? 99;
  const pb = ACTION_PRIORITY[b.action] ?? 99;
  if (pa !== pb) return pa - pb;
  return b.confidence - a.confidence;
});

The whole BSV fix was about 200 lines of code across four files. The reason it was easy: the guards layer meant I could trust prompt changes to fail safe.

Other things shipped since v1.0

Beyond the architecture and the bond ETF case study, a lot of smaller features landed across v1.1 through v1.6:

Earnings calendar guard — Yahoo’s calendarEvents module ships next-earnings date inside the existing quoteSummary call. Hard HOLD ≤3 days to earnings, no STRONG BUY ≤7.
News sentiment scoring — every headline tagged bullish/bearish/neutral with high/medium/low impact, in the same Gemini call that was already filtering relevance.
Technical indicators expanded — beyond SMA/RSI from v1: MACD with crossover detection, Bollinger Bands with squeeze detection, ATR, Stochastic, OBV trend. All from existing chart data.
Value investing framework — A–D fundamental ratings for individual stocks based on ROE, debt/equity, FCF, growth, analyst target.
Crypto bottom-fishing model — RSI + volume contraction + 200MA + death cross confluence detection for BTC/ETH.
STRONG BUY analysis pages — interactive TradingView chart + buy thesis + risk analysis per STRONG BUY ticker, all encoded in the URL hash (no server).
Refresh mode — re-analyze a single ticker with after-hours / pre-market price for late-night decisions.
Intraday alerts — only fire on STRONG BUY changes (upgrade, downgrade, or ≥10pt confidence shift). No noise.
International currency support — non-USD portfolios fully supported with live FX from Yahoo. Sub-unit handling for exchanges quoting in pence/agorot/cents (LSE GBp → GBP ÷100).
CI + tests — 63 unit tests via node:test, zero dependencies, runs on every PR.
i18n docs — full English / Simplified Chinese / Traditional Chinese site via Jekyll polyglot.

Full release notes are on GitHub Releases.

The honest results so far

I’ve been running Richfolio against my own portfolio for the past few months. Across that window I’m up roughly 6% from acting on the AI’s STRONG BUY suggestions.

The caveat I have to put in writing: US markets have been strong over the same window. A meaningful chunk of that 6% is probably tailwind. I can’t say “the AI added 6%” — I can only say “following the AI’s suggestions during a strong market gave me 6% on those entries.”

To know whether Richfolio actually adds value vs riding the tape, I need to see it run against portfolios that look nothing like mine.

Alpha testers wanted

If you’d like to point Richfolio at your portfolio for a few weeks and tell me where it’s wrong, I’d love to hear from you.

What I’d love testers to bring:

A portfolio that looks different from mine — heavy crypto, sector-concentrated, dividend-focused, international, REIT-heavy, small-cap heavy
Honesty about whether the STRONG BUY signal actually matches what you’d buy yourself
Bug reports — weird tickers, exchanges I don’t trade on, edge cases in the FX layer

What you get:

A working free-tier portfolio monitor
A 1-on-1 setup walkthrough
Direct line to me for feedback and feature requests
First look at upcoming versions

Setup is a GitHub fork plus a few environment variables — full docs at furic.github.io/richfolio.

DM me or open an issue on the repo if you’re interested.

The post Richfolio, three months in: AI architecture in production appeared first on Richard Fu.

Unity WebGL Safari Hang: The First-Draw Shader Stall

Richard Fu — Sat, 16 May 2026 07:55:26 +0000

TL;DR — This is a war story about a Unity WebGL Safari hang : a game that ran beautifully on Chrome but froze for ~3 seconds on the first major animation event in iOS Safari. After a long detour through material instancing, shader keywords, animator transitions, and post-FX, the culprit was a single prefab nobody thought to warm up: an overlay spawned by an obscure event handler one frame before the animation started. Mid-game Instantiate of a prefab with a custom shader triggers Safari’s webglPrepareUniformLocationsBeforeFirstDraw on first render — synchronous, main-thread, ~3ms per uniform lookup, ~200 uniforms across a complex prefab = 2.8s stall. The fix is to render the prefab once during the splash so the cache is warm before gameplay needs it.

Reproducing the Unity WebGL Safari Hang

I’m creating a Unity WebGL game with the Universal Render Pipeline (URP) and a lot of custom shaders — particle bursts, dissolve effects, glow overlays, 3D character animations, the works. The target audience is mobile; the majority of players are on iOS Safari, which is exactly where the Unity WebGL Safari hang showed up.

Everything tested fine on desktop Chrome — silky 60fps, fast first interaction, no hitches.

Then we tried Safari on a Mac (and later an iPhone 12). The first major animation event of every session froze the entire game for ~3 seconds. The freeze happened after the build-up animation completed but before the payoff sequence visually started. Every subsequent occurrence of the same event was perfectly smooth.

The pattern was textbook “first-use compile stall”:

Browser	Hang on first event
Chrome (normal)	~0.1s (barely perceptible)
Chrome (incognito, no GPU cache)	~0.2s
Firefox	~2s
Safari (macOS)	~3s
iPhone 12 Safari	~3s

The 25× delta between Chrome and Safari is the smoking gun. Both browsers run Metal under the hood on macOS/iOS — Chrome via ANGLE, Safari directly — but ANGLE aggressively caches shader compilation work that Safari’s WebGL→Metal translator does over and over.

The wrong rabbit holes

Before finding the real cause, we eliminated a long list of suspects through targeted A/B tests. Each took a rebuild + Safari test cycle. Documenting them here in case anyone hits a similar pattern:

A shader keyword toggle. Our main mesh shader uses a [Toggle(_USE_DISSOLVE)] property that activates a fragment-shader branch. Disabling the keyword → hang persisted.
The renderer.material = newInstance assignment. Skipped it on 13 simultaneous objects → hang persisted.
An animator state transition. Commented out the state change that occurred on the same frame → hang persisted.
The entire state handler for the suspect state. Stubbed out the whole switch case → hang persisted.
MMFeedbacks / Feel post-FX (camera shake, vignette). Unsubscribed the handler → hang persisted.
A separate fade-out coroutine on UI overlays. Unsubscribed it → hang persisted.

After all six A/Bs, we’d conclusively ruled out everything on the visible event path. The hang persisted even when the event handler did effectively nothing.

The diagnostic that cracked it

Stopping the guess-and-check loop and capturing a Safari Web Inspector → Timelines profile of the hang was the turning point.

Inside the 3.1-second Animation Frame Fired event, the breakdown was:


wasm-stub 1.94s
  _glGetUniformLocation 906ms (261 calls)
    webglPrepareUniformLocationsBeforeFi… 671ms (194 calls)
      getActiveUniform 444ms (128 calls)
      getProgramParameter 211ms (61 calls)
      getUniformLocation 201ms (58 calls)
  _glGetActiveUniform 423ms (122 calls)
  _glGetActiveUniformsiv 409ms (118 calls)
  _glGetActiveUniformBlockiv 191ms (55 calls)

The 1.94s is Unity’s WebGL runtime asking the browser to look up uniform locations for shader programs it had never drawn before. The remaining ~1.2s of the frame is the actual Metal pipeline-state-object (PSO) compile triggered by the first draw call.

Most importantly: 194 distinct shader programs went through webglPrepareUniformLocationsBeforeFirstDraw in a single frame. That’s not “one or two new variants” — that’s almost the entire scene’s shader inventory being prepared at once.

webglPrepareUniformLocationsBeforeFirstDraw is WebKit-specific. On first draw of a program, it iterates every active uniform, queries the location for each, and caches the mapping. Each call into the WebGL JavaScript API costs ~3ms on Safari (vs ~0.1ms on Chrome’s ANGLE). 200 programs × ~10 calls each at 3ms ≈ 6 seconds of synchronous main-thread work. Spread that across however many programs need preparing on a given frame.

The actual root cause

Once we knew it was first-draw uniform reflection, the question became which prefab is first-drawn on that specific frame. The visible event handler had been stubbed out. Material instancing had been skipped. So what spawned at exactly the right moment?

The game has a server-driven event sequence with several intermediate steps between the trigger and the visible animation. One of those intermediate steps was an “overlay reveal” — a manager that handles a separate server event:


GameObject instance = Instantiate(overlayPrefab, transform);
instance.transform.localPosition = pos;
var overlay = instance.GetComponent&lt;OverlayComponent>();
overlay.SetLevel(level);

A fresh Instantiate, no pool. The overlay’s first draw call happens on the very next render frame after spawn — which on this code path is frame #2 of the next animation’s wait window. The hang at frame #2 matched perfectly. The overlay prefab uses a custom TMP text shader plus a particle/glow combo, with about 200 uniforms across its passes.

Our shader warmup at boot covered the major VFX prefabs we knew about — the burst particles, the highlight glow, the popup labels, the dissolve variant of the main mesh shader. It did not cover this overlay because the manager was an “old” engine system that pre-dated the warmup pattern. Nobody connected the dots: the overlay is spawned by a different event than the animation that hangs, so its first draw appears to be unrelated to the hang location.

Fixing the Unity WebGL Safari Hang

A single line in the overlay manager’s Awake resolved the Unity WebGL Safari hang completely:


using MyGame.Rendering;

protected virtual void Awake()
{
    // ...existing setup...

    if (overlayPrefab != null)
        ShaderWarmup.WarmupPrefab(overlayPrefab);
}

ShaderWarmup.WarmupPrefab does the bare minimum needed to make WebKit compile the program and cache its uniform locations:

Instantiates one copy of the prefab as a child of a WarmupParent transform (parked at the gameplay anchor — wherever the real prefab will spawn in-game, so lighting matches)
Plays any ParticleSystem components so their geometry actually emits this frame
Lets the main camera render the warmup parent for 3 frames during the splash screen — same camera, same lighting state, same render-pass configuration as gameplay, so the PSO key matches
Destroys the throwaway instance

The web front-end’s splash screen waits for both loadProgress >= 1 AND a Unity-side gameReady signal that only fires after every warmup pass has flushed. So the 1-3 seconds of pre-compile work happens behind the loading bar where players already expect to wait, instead of during a critical animation later.

Result on Safari: first event dropped from 3.1s to ~500ms — identical to every subsequent occurrence.

When you need this — and when you don’t

The combination of all three must be true:

Criterion	Need warmup if…
Lifecycle	Prefab is `Instantiate`d at runtime (not present from scene load)
Shader complexity	Uses non-trivial shader: custom `*.shader`, `[Toggle(_KEYWORD)]` properties, `multi_compile` keywords, multi-pass shaders, particle shaders, or TMP shaders with `OUTLINE_ON` / `UNDERLAY_ON` / `BEVEL_ON` variants
Timing	First draw happens during gameplay, not during the loading splash

You don’t need warmup for:

Objects visible from scene load (Unity compiles their shaders during the splash render)
Stock URP Lit/Unlit shaders with no keyword toggles
UI Image components with the default UI shader
Anything that doesn’t render (audio sources, logic GameObjects)

The diagnostic loop

If you suspect this is happening in your game:

Reproduce on Safari , ideally on real hardware. macOS Safari is usually enough — the WebGL-via-Metal path is the same.
Open Web Inspector → Timelines tab. Hit record, trigger the event that hangs, stop recording.
Find the long frame in the JavaScript & Events row.
Look under wasm-stub for high counts of _glGetUniformLocation, _glGetActiveUniform, webglPrepareUniformLocationsBeforeFirstDraw. If you see dozens or hundreds of these on one frame, you’ve found a first-use shader event.
Identify what’s first-rendered. What prefab spawned recently? What keyword was toggled? What material was instanced?
Add a ShaderWarmup.WarmupPrefab call in that subsystem’s Awake.

A subtle gotcha: the prefab that causes the hang may not be the one whose animation is running when the hang happens. In our case the overlay was spawned by a completely separate event handler one frame before the visible animation started, so the hang appeared to be inside the animation. Trace recent Instantiate calls backward from the slow frame, not just what’s animating during it.

Related prior art

The general “WebGL on Safari is slow at things ANGLE handles fast” story is well-documented:

WebGL Performance on Safari and Apple Vision Pro — Wonderland Engine describes a ~150ms hitch from Safari’s Metal-emulated uniform buffer uploads. Same family of issues at a smaller scale.
WebKit Bug 218949 — WebGL instanced draw calls slow on iPhone 12 Pro
WebKit Bug 230749 — WebGL performance regression on particles in Safari 15
WebKit Bug 239015 — Performance regression after uploading WebGL buffers (Safari 15.4)
Unity Manual: Prewarm shaders — official docs explicitly note that Shader.WarmupAllShaders may not warm correctly on Metal/Vulkan because vertex layout differs from the actual draw call, which is exactly why we render through the main camera rather than calling WarmupAllShaders.
Unity Forum: Shader Compile Frame Hitches even with Shader.WarmupAllShaders — confirms the official API doesn’t fully solve the problem
Unity WebGL tips / advice in 2023 — Radiator Blog — general WebGL gotchas

The specific case that bit us — a prefab Instantiated mid-game by an obscure event handler, whose first draw lands inside an unrelated critical animation one frame later — isn’t covered in the existing material. The Safari Web Inspector webglPrepareUniformLocations* markers as a diagnostic tool also seem underused; I didn’t find any reference to using them for Unity WebGL debugging.

Takeaways

Shader.WarmupAllShaders is not enough on Metal/Vulkan. You have to actually render the geometry through the same camera pipeline that gameplay will use.
The first draw call of any custom-shader prefab is expensive on Safari. Plan for it. Render once during the splash. Engineering effort: one line per missed prefab.
Self-registering warmup is the right pattern. Each subsystem that spawns prefabs at runtime should warm its own prefab in Awake instead of relying on a central registry. New systems get coverage automatically without anyone remembering to wire them up.
Diagnose with the Safari profiler, not by guessing. We burned a full day on A/B isolation before realizing the answer was sitting in the Web Inspector timeline the whole time. The webglPrepareUniformLocations* markers tell you exactly when first-use uniform discovery is happening — search for them.
Pool spawned prefabs aren’t a substitute for warmup. Pooling avoids Instantiate allocation cost (microseconds). Warmup avoids first-draw shader compile cost (seconds). They solve different problems and you typically want both.

If your Unity WebGL game has a “first time something happens” hitch on Safari that doesn’t repeat, you’re almost certainly looking at a Unity WebGL Safari hang of the same family. The Safari profile + webglPrepareUniformLocationsBeforeFirstDraw markers are the fastest path to the answer. Hope this saves someone a long debugging session.

The post Unity WebGL Safari Hang: The First-Draw Shader Stall appeared first on Richard Fu.

Re-skinning a 3D Character with AI Image Tools (Without Touching Blender)

Richard Fu — Sat, 02 May 2026 15:58:20 +0000

TL;DR: I bought a well-made chibi farmer model and wanted to reuse it as a zookeeper character — same mesh, same rig, same animations. Meshy.ai’s Retexture didn’t work for me, and naive cropping of the UV atlas pulled in neighbor pieces. The fix turned out to be embarrassingly simple: connected-component labeling to extract one UV island at a time, send each piece to ChatGPT with a tight prompt, then composite the AI result back with an intersection-of-silhouettes mask. I packaged the workflow as a Claude Code skill — furic/texture-atlas-roundtrip — and ended up with a wildlife keeper that took a couple of evenings instead of a couple of weeks.

The problem

I’m a developer with no artist skills. For my causal game prototype, I needed a wildlife keeper character. I’d already paid for a beautifully animated chibi farmer (Suriyun’s Farmer SD pack), and the rig + animations were exactly what I wanted. The catch: the outfit was a plaid shirt + denim jeans + straw hat with a red band. Pure farmer.

What I needed:

A khaki keeper shirt with chest pockets
Khaki cargo pants/shorts
A pith helmet instead of a straw hat
Brown leather boots

What I wanted to not do:

Touch the FBX, the rig, or any animation
Open Blender to re-UV anything
Hand-paint a 2048×2048 texture from scratch

The character has one big packed texture atlas — Famer.png — with the shirt front, shirt back, sleeves, pants, belt, hat, leather accessories, and a few small bits all unwrapped onto a single image. That single PNG is what I needed to modify.

What didn’t work

Meshy.ai’s retexture function. I uploaded the FBX and tried both “text input” and “image input” prompts. The results were unrecognizable — colors smeared in the wrong places, details bleeding across UV seams. It felt like the model wasn’t understanding the UV mapping of the imported asset. Maybe there’s a config I missed, but I didn’t dig in: a one-click solution will probably exist in 12 months, but right now it doesn’t.

Asking ChatGPT to redraw the whole atlas. DALL-E doesn’t preserve UV island shapes pixel-precisely. Even with a strict “keep dimensions, keep silhouette” prompt, you get back a texture that looks roughly right but seams shift, the hat brim rotates 5°, the collar moves. UV-bound textures are unforgiving — even a few-pixel shift causes visible artifacts on the 3D mesh.

Cropping a single piece out as a rectangle. The atlas packs UV islands tightly to save memory, so the shirt-front bbox always includes slivers of the belt above and the suspender stripes that are technically in the same connected pixel region. Sending that to AI and pasting back contaminated the neighbor pieces.

So the path forward needed to be: edit one piece at a time, keep its silhouette pixel-perfect, and protect everything else from collateral damage.

The solution: split → edit → composite

The technique has three parts, and only the splitting bit is non-obvious:

Split the atlas into per-UV-island PNGs. Each piece is a 1024×1024 canvas with one island centered and everything else (including neighbor islands that share its bbox) masked to pure black.
Edit each piece independently in any AI image tool. Because the background is solid black, the AI has a clean canvas and won’t draw beyond the island silhouette.
Composite the AI’s result back into the atlas at the exact original pixel coordinates, using a mask that protects neighbor islands from accidental overwrites.

Why naive cropping fails — and what to do instead

The atlas has roughly nine clearly visible UV islands, but they sit close together in the 2D image:

+-------------------------------+
|                               |
|   [BELT — wide horizontal]    |
|                               |
|  [SHIRT FRONT]   [SHIRT BACK] |
|                               |
|                  [SLEEVES][..]|
|                               |
|  [PANTS]        [STRAW HAT]   |
|                               |
+-------------------------------+

If I rectangle-crop “shirt front”, I’m guaranteed to also catch a slice of the belt above it or the leather puffs on its right edge. Send that to AI, and the AI either repaints those slivers (corrupting the belt) or, more often, fills them with black — and “fills with black” is exactly what destroys the belt when I paste back.

The fix is to extract the connected component rather than a rectangle. scipy.ndimage.label walks the image, assigns each contiguous non-black region its own integer ID, and gives you a per-pixel labels array. Then I crop the bbox AND zero every pixel whose label isn’t the one I want:

import numpy as np
from PIL import Image
from scipy import ndimage

img = np.array(Image.open("atlas.png").convert("RGBA"))
non_black = img[..., :3].sum(-1) > 30   # tolerate near-black gradients

labels, n = ndimage.label(non_black)
sizes = ndimage.sum(non_black, labels, range(1, n + 1))
slices = ndimage.find_objects(labels)

# Pick the island we want (e.g. by bbox heuristic or label_id)
target_label = 5
y0, y1 = slices[target_label - 1][0].start, slices[target_label - 1][0].stop
x0, x1 = slices[target_label - 1][1].start, slices[target_label - 1][1].stop

# Extract just this island — neighbors masked to black
piece = img[y0:y1, x0:x1].copy()
mask = labels[y0:y1, x0:x1] == target_label
piece[~mask] = [0, 0, 0, 255]

Now I have a piece I can drop onto a 1024×1024 black canvas, save out as shirt_front.png, and hand to any AI tool with a clean conscience.

I also save a manifest.json recording each piece’s original src_bbox, canvas_offset, label_id, and (we’ll come back to this) flip_y. The manifest is what makes the round trip work — without it, pasting back at the exact pixel position is guesswork.

The intersection-of-silhouettes paste-back

When the AI returns its result, the obvious composite is “paste the whole AI image into the original bbox.” But there are two failure modes hiding in there:

Failure 1: AI’s pure-black background covers neighbor islands that happen to fall inside the bbox. Belt fragment that lived in the corner of the shirt-front bbox? Now black.
Failure 2: AI drew slightly outside the original silhouette (e.g. extended the shirt by 5px on the left). Those extra pixels land on parts of the texture that map to invisible mesh — but worse, they can land on a different UV island in the same bbox.

The fix is the intersection of two silhouettes:

# AI silhouette: where the AI actually drew content
ai_silhouette = ai_result.sum(-1) > 30

# Original silhouette: where the target UV island lives in the atlas
src_labels, _ = ndimage.label(original_atlas.sum(-1) > 30)
orig_silhouette = src_labels[y0:y1, x0:x1] == target_label

# Paste only where both agree
mask = ai_silhouette & orig_silhouette
target[y0:y1, x0:x1][mask] = ai_resized[mask]

Original-silhouette-only would let AI black overwrite neighbors. AI-silhouette-only would let AI bleed onto invisible mesh. The intersection covers both directions in one line.

I add a tiny erosion + Gaussian blur on the mask to avoid hard edges where AI’s stroke meets the existing texture. That single trick is what makes the round trip clean enough to ship.

The Y-flip gotcha

I sent shirt_front.png to ChatGPT with a careful prompt — “khaki shirt, two chest pockets, keep dimensions and silhouette” — and got back an excellent result. Pasted it back, opened Unity, and the pockets were on the keeper’s waist. Upside down.

Took me a minute to figure out why: the chibi character’s UV unwrap stores the shirt vertically flipped relative to mesh space. The V-notch at the bottom of the texture? That’s the collar in 3D. When the AI looked at the piece, it saw a normal shirt right-way-up (because the collar happens to point down in the texture) and drew pockets in the upper half. Those pockets, mapped back to mesh, landed on the lower torso.

The fix has two flavors:

Flavor A — don’t pre-flip; flip the AI result during composite.
Pockets will still be in the wrong half of the canvas, but the second flip puts them on the chest. Works for symmetric content.

Flavor B — pre-flip the input so AI works in natural orientation.
Send a Y-flipped piece to AI, AI draws on a “right-side-up” shirt, then composite flips the result back. Two flips total. Better for asymmetric content (name tags, logos).

I went with Flavor B and added a flip_y: true field to the manifest entry for each Y-flipped piece. The composite step honors it automatically:

if effective_flip_y:
    edited_pil = edited_pil.transpose(Image.FLIP_TOP_BOTTOM)

Discovery flow: composite once, see that pockets are upside-down, set flip_y: true in the manifest, re-composite. No re-prompting needed.

The workflow in practice

Here’s the actual loop I ran for the keeper conversion:

SKILL=~/.claude/skills/texture-atlas-roundtrip

# 1. Split the farmer atlas into per-UV-island PNGs
python3 $SKILL/split.py Famer.png ./pieces/

# 2. Rename pieces in manifest.json (island_2 → shirt_front, etc.)
#    Mark Y-flipped pieces: "flip_y": true

# 3. (For Y-flipped pieces) pre-flip so AI sees natural orientation
python3 $SKILL/flip_piece.py shirt_front.png  # → shirt_front_flipped.png

# 4. Send each piece to ChatGPT with a prompt like:
#    "Redraw this UV texture as a khaki keeper shirt with two chest pockets,
#     keep 1024×1024 dimensions, pure black background, exact silhouette..."
#    Save the result back to the same filename.

# 5. Composite each edited piece into the keeper atlas
python3 $SKILL/composite.py M07_Keeper.png shirt_front shirt_front_edited.png ./pieces/manifest.json

For the hat I used a slightly different sub-flow: extract the hat region with the connected-component mask, send to ChatGPT with a pith-helmet reference photo and a “top-down circular UV” prompt, composite back. Since the existing straw hat already had the right round silhouette for a top-down dome+brim view, AI just had to repaint the texture inside that silhouette — no UV alignment risk.

Pants had one extra wrinkle: the “pants” UV island is actually pants AND boots in one piece, with a visible curve dividing them. After the first AI pass turned the whole island into khaki, the boots came out as khaki socks. Second pass with a “modify only below the curve” prompt added brown leather boots without disturbing the pants area.

Results

Before:

After:

The model, rig, animations, and FBX are completely untouched. The keeper texture is a single recolored + AI-edited variant of Famer.png, drop-in compatible with the original material.

For comparison, here’s Meshy.ai’s attempt — which is what pushed me to build this in the first place:

Get the skill

I packaged the workflow as a Claude Code skill: furic/texture-atlas-roundtrip.

git clone https://github.com/furic/texture-atlas-roundtrip ~/.claude/skills/texture-atlas-roundtrip
pip install numpy Pillow scipy

The repo includes:

SKILL.md — when to use, common mistakes, paste-back masking logic
split.py — atlas → per-island PNGs + manifest
composite.py — paste-back with intersection mask + Y-flip support
flip_piece.py — vertical flip helper for Y-flipped UVs
examples/ — optional /split-texture and /merge-texture slash command shortcuts

Roughly 200 lines of Python total. The whole thing exists because connected-component labeling solves an entire class of UV editing problems if you let it.

What I’d want next

A model-aware AI image tool that understands the UV → mesh mapping would make all of this obsolete. Meshy.ai’s retexture is the closest thing today and it didn’t work for my chibi character; presumably it’ll be solved in the next round. Until then, splitting an atlas and round-tripping pieces through ChatGPT is the most reliable workflow I’ve found, and it’s good enough that I’m planning to use it for the next four characters in this series.

If you’ve been blocked on reskinning a 3D asset because you’re not an artist, give the skill a try and tell me where it falls down — issues and PRs welcome at the repo.

The post Re-skinning a 3D Character with AI Image Tools (Without Touching Blender) appeared first on Richard Fu.

The FTX Collapse Had Warnings. An LLM Could Have Caught Them.

Richard Fu — Thu, 05 Mar 2026 12:58:41 +0000

Turning RSS feeds, Google Gemini, and a GitHub cron job into an early warning system for crypto exchange risk.

In November 2022, a cascade of news headlines told the story of FTX’s collapse in slow motion. Alameda’s balance sheet leaked on November 2nd. Binance announced it was dumping FTT on the 6th. By the 8th, withdrawal delays were making headlines. On the 11th, FTX filed for bankruptcy.

Nine days. The signals were public, scattered across CoinTelegraph, Decrypt, The Block, and Google News. But most people — myself included — weren’t synthesizing that information fast enough. The problem wasn’t access. It was attention.

That observation sat with me for a while. Not as a regret, but as an engineering question: what would it take to automate the “paying attention” part?

The answer turned out to be surprisingly small. About 450 lines of TypeScript, three npm dependencies, and an LLM that’s good at reading headlines.

The Bet: LLMs as Risk Filters, Not Risk Analyzers

There’s a temptation to over-scope AI in financial applications — building trading bots, predicting prices, replacing analysts. Most of those projects fail because they ask the AI to be right about uncertain things.

Crypto Sentinel takes a different bet: use the LLM as a filter , not an oracle. It doesn’t predict what will happen. It reads a batch of headlines and answers one narrow question: does this collection of news suggest elevated risk for the exchanges I hold funds on?

That’s a classification task, not a prediction task. And classification is something current LLMs do reliably.

The system defines five risk tiers with explicit criteria:

Level	Trigger Examples
Critical	Insolvency, confirmed hack, withdrawal freeze, regulatory shutdown
High	Major security breach, regulatory enforcement, suspected bank run
Medium	Regulatory investigation, partnership failure, leadership departure
Low	Minor negative press, market downturn, routine operational changes
None	Neutral or positive coverage

Only medium and above triggers an alert. This single design choice — an aggressive threshold — is what prevents the system from becoming noise. Every notification that reaches my phone is worth reading.

Architecture: Six Stages, No Server

The entire pipeline runs as a scheduled GitHub Actions job, four times a day. There’s no always-on server, no database, no container orchestration. Here’s the flow:


RSS Feeds ──> Keyword Filter ──> Dedup Cache ──> Gemini Analysis ──> Alerts
 (5 sources (configurable (MD5 of URL, (structured (email via
 + Google watchlist) last 500) JSON output) Resend +
   News) Telegram)

Each stage is a single TypeScript module. The orchestrator in index.ts is 59 lines — a for loop with error handling. Let’s walk through the interesting parts.

Aggregation: RSS + Google News with a Redirect Trap

Four crypto-focused RSS feeds provide the baseline coverage:


const RSS_FEEDS = [
  { source: "CoinTelegraph", url: "https://cointelegraph.com/rss" },
  { source: "Decrypt", url: "https://decrypt.co/feed" },
  { source: "The Block", url: "https://www.theblock.co/rss.xml" },
  { source: "CryptoSlate", url: "https://cryptoslate.com/feed/" },
];

Google News adds broader coverage, dynamically querying for each watched keyword (“bybit crypto”, “youhodler crypto”, etc.). But there’s a trap here that took some debugging.

Google News RSS doesn’t serve direct article URLs. Every link is a redirect wrapper: news.google.com/rss/articles/CBMi.... In a browser, this transparently redirects to the real article. But email services like Resend wrap outbound links in their own click-tracking redirect. So clicking a link in the email creates a double redirect : Resend → Google News → actual article. Google interprets that chain as bot traffic and blocks it with a CAPTCHA page.

The fix resolves Google News URLs at ingestion time, before they ever reach the email:


const resolveGoogleNewsUrl = async (url: string): Promise<string> => {
  try {
    const res = await fetch(url, { method: "HEAD", redirect: "follow" });
    if (res.url && res.url !== url) return res.url;
  } catch {
    try {
      const res = await fetch(url, { redirect: "manual" });
      const location = res.headers.get("location");
      if (location) return location;
    } catch { /* fall through */ }
  }
  return url;
};

The HEAD-first approach minimizes bandwidth. If the server doesn’t support HEAD (some don’t), it falls back to a manual redirect extraction. Worst case, the original Google News URL passes through unchanged.

All resolutions happen in parallel via Promise.all, so this doesn’t meaningfully slow down the pipeline.

Deduplication: MD5 Hashing with a Rolling Window

Each article is identified by the MD5 hash of its resolved URL. A JSON file caches the last 500 seen hashes — roughly a week of coverage at current volume. The cache is persisted between GitHub Actions runs using actions/cache@v4 with a rolling key strategy:


- uses: actions/cache@v4
  with:
    path: cache.json
    key: sentinel-cache-${{ github.run_id }}
    restore-keys: sentinel-cache-

Every run creates a new cache key (by run ID), but restores from the most recent one. This means the cache auto-updates without manual pruning of stale keys.

Why not a database? Because a 16 KB JSON file with 500 hex strings doesn’t need one. The entire state model fits in a single fs.readFileSync call.

The Gemini Prompt: Structured Output via Role-Playing

The prompt engineering is deliberate. Rather than asking Gemini to “analyze these headlines,” it’s given an explicit role and output contract:


const prompt = `You are a crypto-exchange risk analyst. Given these headlines
about crypto exchanges, assess the overall risk level.

Risk levels:
- CRITICAL: insolvency, confirmed hack, withdrawal freeze, regulatory shutdown
- HIGH: major security breach, regulatory enforcement, suspected bank run
- MEDIUM: regulatory warning, partnership failure, major leadership departure
- LOW: minor negative press, market downturn, routine changes
- NONE: neutral news, positive coverage

Headlines:
${headlines.map((h, i) => `${i + 1}. ${h}`).join("\n")}

Return ONLY valid JSON:
{ "risk_level": "...", "summary": "1-2 sentence summary", "alerts": ["concern 1", ...] }`;

Three things matter here:

Enumerated risk levels with examples — removes ambiguity about what “high” means
Numbered headlines — helps the model reference specific items in its summary
“Return ONLY valid JSON” — reduces the chance of markdown wrappers or preamble text

When JSON parsing fails (it happens ~2% of the time with Flash models), the system falls back to low risk with a manual review flag rather than crashing.

Alert Formatting: Color-Coded HTML for Fast Scanning

The email alert is designed to be scannable in under 10 seconds. A color-coded header immediately communicates severity:


const riskColors: Record<RiskLevel, string> = {
  critical: "#dc2626", // Red — immediate action
  high: "#ea580c", // Orange — urgent attention
  medium: "#d97706", // Amber — worth investigating
  low: "#65a30d", // Green — low concern
  none: "#6b7280", // Gray — informational
};

Below the header: AI summary, specific concerns as bullets, and a table of source articles with direct links. Telegram gets a condensed version — same information hierarchy, fewer articles (10 vs 20), plain text formatting.

Telegram is entirely optional and implemented with raw fetch() against the Bot API. No SDK, no npm dependency. If the env vars aren’t configured, it silently skips. If the API call fails, the error is logged but doesn’t block the email alert.

Resilience as a Feature

A monitoring system that crashes is worse than no monitoring system — it gives false confidence. Every stage in the pipeline is designed to degrade rather than fail:

Failure	Behavior
One RSS feed times out	Other feeds still process; warning logged
Google News returns 403	Skipped; dedicated feeds provide baseline coverage
Gemini returns invalid JSON	Falls back to `low` risk + manual review flag
Resend API error	Hard fail (email is the primary channel — this should be loud)
Telegram API error	Logged, not propagated; email already sent
Cache file missing/corrupt	Starts fresh; may re-alert on seen articles (acceptable)

The only intentional hard failures are missing API keys for Gemini and Resend. Everything else bends rather than breaks.

The Stack, and Why Each Piece

Component	Choice	Alternative Considered	Why This One
Language	TypeScript (strict)	Python	Type safety for AI response parsing; catches schema mismatches at compile time
AI model	Gemini 2.5 Flash	GPT-4o-mini, Claude Haiku	Generous rate limits on the free tier (250 req/day); sub-second for classification
Email	Resend	SendGrid, AWS SES	Simplest API surface; works without domain verification via shared sender
Messaging	Telegram Bot API	Slack, Discord	Native mobile push; no OAuth dance; direct `fetch()` with zero dependencies
RSS parsing	rss-parser	feedparser, custom	Handles RSS 2.0 and Atom; tolerant of malformed feeds; 10s timeout built in
Scheduling	GitHub Actions cron	AWS Lambda, Vercel cron	Secrets management built in; cache persistence built in; already where the code lives
Persistence	JSON file	SQLite, Redis	16 KB of data doesn’t justify a database; human-readable for debugging

Total production dependencies: @google/generative-ai, resend, rss-parser. That’s it. Everything else is native Node.js 22 (including fetch).

Gotchas Worth Knowing

A few things that weren’t obvious upfront:

Google News RSS is region-locked. The ceid and gl parameters control which regional edition you get. AU:en returns Australian English results. If you’re watching for news about a Southeast Asian exchange, you might want SG:en or multiple regional queries.

Resend’s click tracking creates double redirects. Any URL in a Resend email gets wrapped in a resend-clicks.com tracking redirect. If the original URL is also a redirect (like Google News), the target server may block the chained request. Always resolve redirects before including URLs in emails.

LLM JSON output isn’t guaranteed. Even with explicit “return ONLY valid JSON” instructions, Gemini occasionally wraps the response in markdown code fences or adds a preamble. The JSON.parse call needs a try/catch with a sensible fallback — not just for robustness, but because the failure mode (crashing at 3 AM with no alert) is worse than the degraded mode (a slightly less precise risk assessment).

GitHub Actions cron is approximate. The schedule trigger doesn’t guarantee exact timing — GitHub queues jobs, and during high load, runs can be delayed by 15-30 minutes. For a monitoring system that runs 4x daily, this is fine. For anything requiring precise timing, it’s not.

actions/cache has a 10 GB limit per repo. With a rolling key strategy, old cache entries accumulate. For a 16 KB file this is irrelevant, but worth knowing if you extend the pattern to larger datasets.

The Broader Pattern

Strip away the crypto-specific parts and what remains is a general-purpose architecture for AI-augmented monitoring of public information :

Aggregate from multiple public data sources (RSS, APIs, web scraping)
Filter by relevance criteria (keywords, rules, heuristics)
Deduplicate against a rolling history to avoid re-processing
Classify using an LLM with structured output and explicit criteria
Route alerts conditionally based on severity thresholds
Deliver through multiple channels with graceful degradation

This same pipeline could monitor:

Competitor news for a product team
Regulatory filings in a specific industry
Security advisories for your dependency stack
Brand mentions across news outlets
Supply chain disruptions for logistics operations

The LLM is the key differentiator from traditional keyword alerts. It can distinguish between “Exchange X partners with major bank” (positive) and “Exchange X under investigation by major bank regulator” (concerning) — something a keyword filter fundamentally cannot do.

Try It

The project is open source and designed to be forked. Three API keys (all free-tier, no credit card), a few GitHub secrets, and you have a running monitor.

Repository: github.com/furic/crypto-sentinel

Docs: furic.github.io/crypto-sentinel


# Local development
git clone https://github.com/furic/crypto-sentinel.git
cd crypto-sentinel &amp;&amp; npm install
cp .env.example .env # Add your API keys
npm run dev

The whole thing is ~450 lines of TypeScript. Read it in an afternoon, fork it, make it yours.

The next exchange collapse will have warning signs. The question is whether you’ll be reading headlines fast enough to notice them.

The post The FTX Collapse Had Warnings. An LLM Could Have Caught Them. appeared first on Richard Fu.