DEV Community: Yuiko Koyanagi

Best AI Gateways with Built-In Observability & Governance (2026)

Yuiko Koyanagi — Wed, 02 Sep 2026 06:00:00 +0000

An LLM feature usually starts with one OPENAI_API_KEY in a .env file. It stops being that once a second provider shows up, then a second team, and then someone asks why inference spend doubled last month and nobody can break the number down.

What an AI gateway is

An AI gateway is a proxy between your applications and the model providers you call. Instead of every service holding its own provider keys and its own retry logic, they all talk to one endpoint.

Without a gateway, every service is on its own:

┌──────────────┐
│  chat-api    │──── OPENAI_API_KEY ──────────▶ OpenAI
├──────────────┤
│  summarizer  │──── ANTHROPIC_API_KEY ───────▶ Anthropic
├──────────────┤
│  batch-job   │──── OPENAI_API_KEY (copy) ───▶ OpenAI
└──────────────┘

Keys copied into every service. No shared view of cost.
A provider outage is handled — or not — three separate times.

With one in place:

┌──────────────┐
│  chat-api    │──┐
├──────────────┤  │   ┌─────────────────────────┐      ┌───▶ OpenAI
│  summarizer  │──┼──▶│      AI GATEWAY         │──────┼───▶ Anthropic
├──────────────┤  │   │                         │      └───▶ Bedrock
│  batch-job   │──┘   │  • routing & failover   │
└──────────────┘      │  • virtual keys         │
   one base URL       │  • budgets, rate limits │
   one credential     │  • cost per request     │
                      │  • traces & metrics     │
                      └───────────┬─────────────┘
                                  │
                                  ▼
                     Prometheus / OpenTelemetry
                     → your existing dashboards

The gateway can decide which provider serves each call. That gives you failover when one goes down, cost attributed per team, budgets that stop runaway spend, and traces in the dashboards you already use.

Proxying is the easy part; every product does it. The differences are in that second list — and in how much of it you get before hitting a paywall.

In this article, we’ll explore four AI gateways: Bifrost, LiteLLM, Cloudflare AI Gateway, and Vercel AI Gateway.

The two families

These four gateways split cleanly into two distinct categories, and this split matters more than any individual feature:

Self-hosted (Bifrost, LiteLLM) — you run the gateway and keep its configuration, provider credentials, governance state, and logs on infrastructure you control. Prompts remain inside your network only when the upstream model endpoint does too. You also own the database, upgrades, backups, and on-call.

Managed (Cloudflare, Vercel) — the vendor runs it. Setup takes minutes, there is no infrastructure to manage, and both integrate tightly with their native platforms. You cannot self-host, and your prompts transit their network.

That choice constrains everything that follows. Within each pair, the differences come down to emphasis:

	Strongest at	Main limitation
Bifrost	Governance on a bare container; MCP gateway; low overhead	Fewer providers than LiteLLM; HA, SSO, audit logs, and guardrails are Enterprise-only
LiteLLM	Provider coverage; routing flexibility; external observability integrations	Production topology is genuinely complex
Cloudflare	DLP and guardrails; visual dynamic routing; no infrastructure	Account-scoped tokens; Response-side DLP buffers streaming responses
Vercel	Developer experience; modality breadth; provider-level routing	Advanced governance is metered; no self-hosting

Self-hosted: Bifrost

Apache 2.0, Go, in front of 1,000+ models across 23+ providers, with 7.7k stars on GitHub.

What stands out: governance is running before you configure anything.

Telemetry, logging, and governance are auto-loaded built-ins — in the maximhq/bifrost:latest image I pulled on 30 August 2026, seven internal plugins registered at startup, those three among them. What that means in practice: /metrics serves Prometheus without adding an exporter, and the virtual key, team, budget, and customer endpoints answer immediately against the default SQLite store. Creating a key with a daily spend cap and a token rate limit is one call, no external database:

curl -X POST localhost:8080/api/governance/virtual-keys \
  -H 'Content-Type: application/json' -d '{
    "name": "team-search",
    "budget": {"max_limit": 10.0, "reset_duration": "1d"},
    "rate_limit": {"token_max_limit": 1000, "token_reset_duration": "1m"}
  }'

The virtual key is the organising primitive: model access, budgets nested across key/team/customer, rate limits, routing, and which MCP tools the key may reach all hang off it. That single point of control is the design's real argument.

Observability is built in rather than bolted on. Inputs, outputs, model, provider, token counts, cost, latency, and errors are recorded automatically, stored in SQLite or PostgreSQL, and exportable to OTel, Prometheus, Datadog, Kafka, Splunk, BigQuery, and Pub/Sub. Content logging can be disabled for the internal log store, per request, and separately for each observability connector, so metadata such as cost and latency can be retained without exporting prompt bodies.

Fallbacks are per-request. I pointed a provider at a dead address and the request completed through the fallback, with the substitute model named in the response.

It is also an MCP gateway: MCP servers and tools are centrally managed, and each virtual key can be restricted to a subset of tools. For agent workloads that is the same governance model extended one layer up.

Limitations. Provider coverage is roughly a quarter of LiteLLM's, and the community is the smallest here — fewer existing answers when something breaks. Clustering, RBAC, OIDC provisioning, audit logs, and guardrails are Enterprise, as are vendor-supported private-network, on-premise, and air-gapped deployments — the OSS container itself runs anywhere you can run a container. The zero-config SQLite is also a single-instance story: the migration docs call it "single-writer and single-host by design, which is incompatible with HA clustering, cross-region replicas, and the connection-pool patterns Enterprise relies on," so scaling out means moving the config and log stores to PostgreSQL. Semantic caching needs a vector store attached before it does anything.

Self-hosted: LiteLLM

Python SDK plus proxy, 100+ providers — the widest coverage here — and the larger open-source project by a wide margin at 57.6k GitHub stars against Bifrost's 7.7k.

What stands out: the widest provider catalogue by a large margin.

OpenAI, Anthropic, Azure OpenAI, Bedrock, Vertex AI, Cohere, Mistral, Groq, Ollama, vLLM — cloud and self-hosted, across chat, embedding, image, audio, and rerank endpoints. If you evaluate new models as they land, or run your own inference alongside hosted APIs, this is the catalogue most likely to already cover it.

Routing and multi-tenancy are correspondingly flexible: virtual key auth, user/team/organization hierarchy, budgets at key, user and team level, RPM and TPM limits, model groups, load balancing across deployments, retries, in-model failover, cross-model fallback, A/B testing, and traffic mirroring.

The free tier is not a teaser. Per the OSS page and enterprise docs: virtual keys, spend tracking, budgets, rate limits, global guardrails, request/response logging, fallbacks, load balancing, and Prometheus metrics. That last one is worth pinning down, since third-party comparisons list it as Enterprise. It isn't — enabling the callback on the OSS container (main-latest, pulled 30 Aug 2026) exposed around 150 litellm_* series covering request counts, latency histograms, and spend, labelled by model, team, and key, with no license gate:

litellm_settings:
  callbacks: ["prometheus"]     # OSS; served at /metrics/

If you already run an observability stack, this is the gateway that fits it: Langfuse, OpenTelemetry, LangSmith, Datadog, Arize, MLflow, S3, GCS, Azure Blob, Azure Sentinel, and custom callbacks are all supported destinations.

Limitations. Production topology is the real cost. Virtual keys need PostgreSQL (the docs are specific it is not SQLite), Redis is required "as soon as you run more than one proxy instance," and past "roughly 1000+ requests per second" the production guide recommends a Redis transaction buffer. That's sound engineering — contended budget counters across replicas need a shared transactional store — but it is more to stand up than Bifrost asks for, and the guide is required reading rather than optional.

SSO is free for up to five users. Larger SSO deployments, SCIM, audit logs, secret-manager integrations, key rotation, and advanced RBAC require Enterprise.

Managed: Cloudflare AI Gateway

23+ providers, with analytics, logging, caching, rate limiting, retries, dynamic routing, guardrails, and DLP. Nothing to self-host, so everything here is from Cloudflare's docs rather than something I ran.

What stands out: security controls that live in the gateway.

DLP applies to prompts and responses passing through, with built-in profiles for financial and identifier data and custom profiles available under Cloudflare One. Guardrails detect harmful content and can flag or block it. If your reason for wanting a gateway is that prompts might contain data that should not reach an upstream model provider uninspected, this is the one that treats that as a first-class problem.

Dynamic Routing is configured in a visual editor or as JSON: conditional branches on request body, headers, or metadata; per-user, per-project, per-team rate limits; budget limits; model fallback; retries and timeouts; A/B tests; percentage rollouts; route versioning; and instant rollback. Changing which model serves traffic doesn't require an application deploy — and someone who doesn't write code can read the routing graph.

Spend limits put dollar budgets in the request path, and Dynamic Routing can step down to a cheaper model when the primary model’s budget is exhausted. LiteLLM and Bifrost also support budget-triggered fallback paths; Cloudflare’s distinction is that the policy is expressed directly in the same visual routing graph.

Telemetry isn't trapped in the dashboard. The OpenTelemetry integration exports spans in OTLP JSON or protobuf to any compatible backend, carrying model, provider, token counts, prompts, completions, cost estimates, and custom metadata. A GraphQL analytics API and Workers Logpush cover raw logs.

Limitations. Two are worth knowing before you commit. Tokens are account-scoped: per the authentication docs, AI Gateway Run permission "cannot be restricted to a single gateway," so isolating tenants means separate accounts or Worker-side bindings. And DLP on streaming responses removes the streaming — it "buffers the full streamed response before scanning," so time-to-first-token grows to the full generation time. Request-only scanning avoids that.

Managed: Vercel AI Gateway

Hundreds of models across many providers behind one endpoint, with BYOK on the paid tier.

What stands out: the shortest distance from idea to working feature.

Integration with the Vercel AI SDK is seamless — provider/model strings, one endpoint, many models — and it also speaks OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages, so it isn't Next.js-only. Modality coverage is the broadest here: text, image, video, speech, speech-to-text, and realtime voice through one gateway, which makes it closer to a multimodal API hub than an LLM proxy.

Provider routing is unusually granular. By default the gateway "dynamically chooses the default providers based on a combination of recent uptime and latency," and you can override with provider options: order to set preference, only to restrict, and sort by cost, ttft, or tps. Per-provider timeouts for BYOK credentials trigger fast failover; model fallbacks handle the case where the entire model is unavailable. Controlling which provider serves a given model is something the others expose far less directly.

Telemetry has a property none of the others match by default: trace drains emit an OpenTelemetry trace per request, and "traces contain request metadata but not prompt or completion content." The others can be configured to exclude prompt bodies; here it is not configurable, which is a shorter conversation with a compliance reviewer.

Budgets can be set at team, project, API-key, and team-member level. Member budgets are enforced through spend attribution: API keys assigned to a user count against both that member’s budget and the team budget. Zero Data Retention routing restricts traffic to providers with ZDR agreements. Audit Log Drains forward team activity to S3, Splunk, Datadog, or Panther.

Limitations. Tokens carry no markup, but several governance and observability features are metered separately, per the pricing page. Team-wide provider allowlisting and team-wide ZDR each cost $0.10 per 1,000 requests. Custom reporting costs $0.075 per 1,000 tag, user-ID, or quota-entity writes, plus $5 per 1,000 reporting queries. Trace drains cost $0.05 per 1,000 traces plus egress. Per-request provider filtering and per-request ZDR do not carry these team-wide surcharges.

DLP and content guardrails aren't the focus they are at Cloudflare; PII masking and prompt injection detection stay in your application.

Cost structure

	How you pay
Bifrost	OSS free; you pay for infrastructure. Enterprise quoted individually
LiteLLM	OSS free; you pay for infrastructure. Enterprise quoted on annual request capacity
Cloudflare	Analytics, caching, rate limiting free. Unified Billing adds 5% on credit purchases; BYOK avoids it
Vercel	Provider list price, no token markup. Governance add-ons metered per request; BYOK needs paid tier

The OSS licenses are free, but production deployments can still add infrastructure and operational costs: PostgreSQL, Redis, vector storage, backups, monitoring, and the people to run them, depending on the topology and features you enable.

How to choose

Bifrost — you want to self-host, want observability and governance included rather than assembled, need virtual keys tying together budgets, routing and model access, and want an MCP gateway in the same product. Fewer moving parts to stand up than LiteLLM: no Postgres or Redis until you run replicas. Start with the quickstart; the product page covers where the Enterprise line falls.

LiteLLM — provider coverage is the deciding factor, you use niche or self-hosted models, you already run Langfuse/Datadog/OpenTelemetry and want the gateway to feed them, or you need complex routing and multi-tenancy. Assumes you have a platform team.

Cloudflare — you already use Cloudflare Workers or Cloudflare One, you don't want to manage gateway infrastructure, DLP and content guardrails matter, or you want visual routing with A/B tests and staged rollouts.

Vercel — you're on Next.js or the Vercel AI SDK, you want the fastest path to a working feature, you need image/video/voice alongside text, or you want automatic provider selection with a clear dashboard.

Bottom lines

Pick the family first — self-hosted or managed — because that decision constrains everything downstream. Then pick on the constraint that actually binds you: provider coverage, data residency, DLP, or developer velocity.

The alternative to picking one is the arrangement at the top of this post: provider keys copied across services, and spend that only becomes visible when the invoice lands.

Disclosure: this post was made in collaboration with the Bifrost team; the testing, the comparisons, and the conclusions are mine.

Stop asking your AI agent to follow rules. Enforce them.

Yuiko Koyanagi — Tue, 25 Aug 2026 15:25:37 +0000

You've written it a hundred times. In your CLAUDE.md, in your system prompt, in ALL CAPS:

NEVER put "use client" at the page level. NEVER commit @ts-ignore without a reason.

And your agent does it anyway. Not always — that would almost be easier to deal with. It follows the rule for the first 50k tokens, then quietly stops. Or Sonnet follows it and Haiku doesn't. Or it follows nine rules and forgets the tenth.

Here's the thing I finally accepted: a rule in a prompt is a request. The model can decline it. So I stopped asking, and started enforcing.

TL;DR

Prompt adherence is probabilistic. It degrades with context length and with model size.
But half of my coding rules never needed a model at all — they're grep-able.
Claude Code hooks + exit 2 turn those rules into a deterministic reviewer that runs after every single edit, costs zero tokens when nothing is wrong, and fires at 100% regardless of which model wrote the code.
Once the mechanical rules are enforced from below, you can safely downgrade the model doing the typing. That's the real payoff.
Everything below ships in ccteams v0.3.0, but the pattern takes 30 minutes to build yourself.

Two kinds of rules

Some background in three lines: I run Claude Code with orchestrated agent teams — a builder writes code, a reviewer verifies it, and both get a stack-specific "playbook" of rules distilled from the mistakes mid-tier models actually make. It works well. I wrote about the prompt-engineering side of it before.

But rereading my playbooks, I noticed the rules split cleanly into two categories.

Rules that need judgment:

Trace the Server/Client boundary by hand.
Don't write a fix until you can state the root cause.

These need a model. Prompts are the right place for them.

Rules that are just string matching:

"use client" at the top of app/**/page.tsx → wrong.
process.env.SECRET in a client file → wrong.
@ts-ignore with no justification → wrong.

Why was I asking a language model to remember these? A regex doesn't get tired at 200k tokens. A regex doesn't perform worse on a smaller model. I was running deterministic checks on the most expensive, least reliable runtime available.

The mechanism: exit code 2

Claude Code has hooks — commands that run on lifecycle events. The one you want is PostToolUse: it fires every time the agent runs Edit or Write, and it receives a JSON payload on stdin telling you which file was touched.

The magic is in the exit-code contract:

exit 0 → nothing happens, the agent keeps working
exit 2 → whatever your script wrote to stderr gets injected back into the agent's context as feedback on that tool call

No human in the loop. No approval dialog. The agent edits a file, and — from its point of view — the edit "responds" with a code review. It reads the feedback and fixes the problem in the same turn, before a human or a reviewer agent ever sees the mistake.

A minimal version is embarrassingly simple:

#!/usr/bin/env node
// .claude/hooks/check.mjs — wired to PostToolUse in .claude/settings.json
const input = JSON.parse(await readStdin());
const file = input.tool_input?.file_path;
if (!file?.endsWith(".tsx")) process.exit(0);

const src = fs.readFileSync(file, "utf8");
if (/^\s*['"]use client['"]/.test(src) && /\/app\/.*page\.tsx$/.test(file)) {
  process.stderr.write(
    "route-level \"use client\": this makes the whole page render client-side. " +
    "Push it down to the smallest interactive leaf component."
  );
  process.exit(2); // ← this line is the entire trick
}

That's a code reviewer that never sleeps, never gets context-drunk, and works for free.

What I shipped

In ccteams v0.3.0, every stack-specific team now bundles a check script built from its playbook's known failure patterns:

Team	Checks (excerpt)
`next-ts`	route-level `"use client"`, non-`NEXT_PUBLIC_` env in client files, `useEffect`+`fetch` for initial data, `fetch()` without explicit cache intent, `@ts-ignore`/`as any`
`go-api`	`http.Error` not followed by `return`, wrapping errors with `%v` instead of `%w`, errors discarded with `_`, `context.Background()` mid-request
`python-fastapi`	bare `except:`, Pydantic v1 API, mutable default args, `time.sleep`/`requests.*` inside async code
`rails`	SQL interpolation in `where`, `update_column`/`save(validate: false)`, `default_scope`, params mass-assignment, `Time.now`
`django`	naive `datetime.now()`, `fields = '__all__'`, injection-prone `.raw()`/`.extra()`, `post_save` signals
`react-native`	`.map` inside `ScrollView`, index as key, DOM APIs like `localStorage`, unconditional `behavior="padding"`
`frontend`	`onClick` on a `<div>`, `<img>` without `alt`, `outline: none` with no `:focus-visible`, z-index escalation

When an agent writes a violation, it gets this back instantly:

ccteams next-ts check — app/dashboard/page.tsx:
  - route-level "use client": this page and its entire import tree now render
    client-side. Push "use client" down to the smallest interactive leaf component.
  - client file reads process.env.API_SECRET: non-NEXT_PUBLIC_ env vars are
    undefined in the browser (or a secret leak if inlined).
Fix these now, or state in your report why each is intentional.

Note the escape hatch in the last line. These are nudges, not walls — the edit already happened, and sometimes useEffect + fetch is legitimate. The agent can push back with a reason, and the reviewer checks that it did one or the other.

Why this beats prompt rules

1. It fires at 100%. A prompt rule needs to be read, retained, and recalled at the right moment. A hook is a grep. Token 500k? Fires. Haiku wrote the code? Fires.

2. You pay per violation, not per instruction. Prompt rules cost tokens on every delegation even when they're followed. A hook costs zero tokens until something is actually wrong — then it costs three lines.

3. Mistakes die before the review round-trip. Builder writes bug → reviewer catches it → sends it back → builder fixes it: that loop is the expensive part of multi-agent setups. Hooks kill the mistake at write time, so your reviewer spends its (expensive) tokens on things that actually need judgment.

The payoff: you can downgrade the model

This is the part I didn't expect to matter so much.

ccteams agents ship in two tiers — builders on Sonnet, reviewers on Opus. v0.3.0 adds model profiles:

ccteams use next-ts --profile budget    # builder: haiku / reviewer: sonnet
ccteams use next-ts                     # builder: sonnet / reviewer: opus
ccteams use next-ts --profile max       # everyone: opus

Getting Haiku to remember a playbook through prompts alone is a losing game. But hooks fire on Haiku's code with exactly the same precision as on Opus's. With deterministic checks backing it from below, --profile budget stops being "cheap and broken" and becomes a legitimate configuration for routine work.

The more discipline you mechanize, the less intelligence you need to rent.

The boundary (don't hook everything)

Hooks only cover rules that are mechanically checkable without false positives. "Trace the data flow," "run the actual build and quote its output," "state the root cause before fixing" — those stay in prompts and reviewer gates, and I have no intention of moving them.

The rule of thumb I've landed on:

If a violation can be detected with grep, enforce it with a hook. If it needs judgment, put it in the prompt.

One design note if you build this yourself: make your hook scripts fail silent (catch → exit 0). A buggy check that crashes loudly will poison every editing session. And namespace your hook entries (ours all live at .claude/hooks/ccteams-*) so that installing/removing them never touches hooks the user wrote themselves.

Try it

npm install -g ccteams
ccteams use next-ts --profile budget   # or go-api, rails, django, python-fastapi...
# restart Claude Code — hooks and agents load at session start

One command gets you the agent team, the playbook, the hooks, and the cost profile. Switching teams swaps the hooks cleanly.

If this saves you a round-trip or two, a star on the repo genuinely helps. And I'd love to hear what checks you'd add for your stack — the whole point of this design is that a new rule is one regex away.

Apple quietly shipped everything you need to build a real-time translator — so I built one

Yuiko Koyanagi — Tue, 11 Aug 2026 20:25:27 +0000

I work at a German company. Meetings are in German, sometimes English — and even though I speak both, there are moments in fast meetings where I zone out for two seconds and think: wait, what did they just say?

I couldn't use any of the existing captioning tools, because they all pipe your meeting audio to a cloud server. Sending confidential work calls to a third party was a non-starter.

Then I realized something: macOS 26 quietly shipped every building block you need for a real-time translator. On-device speech recognition (SpeechAnalyzer), on-device machine translation (Translation framework), and an on-device LLM (FoundationModels / Apple Intelligence). No servers, no API keys, no per-minute fees.

So I built Wakaru — a menu bar app that turns any audio playing on your Mac into movie-style translated subtitles, in real time.

TL;DR

🎬 Live translated subtitles for anything your Mac plays — Teams, Zoom, YouTube, webinars, podcasts
🔒 100% on-device. Your audio never leaves your Mac. No account, no API keys, no cloud
🌍 Recognizes 10 spoken languages, subtitles in 22
🧠 Optional high-accuracy mode using the on-device Apple Intelligence LLM
⚡ Built entirely with Apple's native frameworks — zero external dependencies, ~3,000 lines of Swift

This post covers how it works and the four gotchas that cost me the most time. If you're planning to build anything on macOS 26's new speech or translation APIs, this might save you a few days.

First attempt: Electron (and why I threw it away)

My first prototype was Electron. It worked — but transcription + translation took about 2 seconds per sentence. For subtitles, 2 seconds might not sound like a lot, but it is: by the time the caption showed up, the conversation had moved on.

When I saw that macOS 26 had the entire pipeline available natively and on-device, I rebuilt it in Swift. The difference was dramatic — captions now appear while the sentence is still being spoken.

(The Electron version wasn't wasted, though. After a lot of tuning it got reasonably fast, and I'm planning to release it for Windows soon.)

Architecture: four stages, zero dependencies

ScreenCaptureKit ──▶ SpeechAnalyzer ──▶ Translation framework ──▶ Subtitle overlay
 (system audio)      (speech-to-text)    or FoundationModels        (NSPanel)
                                          (translation)

The key decision: capture system audio (what the Mac is playing) instead of the microphone. That's what makes Wakaru app-agnostic — it doesn't integrate with Zoom or Teams; it doesn't need to know they exist.

The subtitles are drawn on a borderless, transparent, click-through NSPanel, so you can click straight through the captions to whatever is underneath.

Making it feel like movie subtitles (not a log viewer)

The naive version of this app is a window where original text and translations pile up like a chat log. That's easy to build — and unusable as subtitles.

What I ended up with:

Don't translate while a sentence is still forming. I initially translated the live transcription in real time. For a verb-final language like German, the translation reshuffled itself on every update — completely unreadable. Now Wakaru waits until a sentence (or a long clause) is complete, then translates it exactly once.
Caption lifetime scales with reading speed. Each caption stays on screen for text.count / 7 + 2 seconds (clamped to 4–12s). Short interjections vanish quickly; long sentences stay until you can actually finish them.
Every caption gets a minimum of 2.5 seconds, even when someone is talking fast — new captions queue up instead of instantly evicting the old ones.

let lifetime = min(max(4, Double(text.count) / 7 + 2), 12)

Gotcha #1: Set the sample rate at capture time

SpeechAnalyzer prefers 16 kHz audio. My first version captured at 48 kHz and resampled with AVAudioConverter — and the first caption took seconds to appear. The converter buffers audio internally before it emits anything.

The fix: ScreenCaptureKit lets you pick the sample rate at capture time.

let cfg = SCStreamConfiguration()
cfg.capturesAudio = true
cfg.sampleRate = 16_000   // match SpeechAnalyzer's preferred format
cfg.channelCount = 1

Capture at 16 kHz mono from the start and the only conversion left is Float32 → Int16, sample by sample. The latency disappeared.

Gotcha #2: SpeechAnalyzer is slow by default — in three different ways

Even after fixing the sample rate, captions were still sluggish. It turned out to be three separate problems:

Reporting cadence. By default, SpeechAnalyzer batches up partial results and delivers them in bursts, seconds late. Pass .fastResults in reportingOptions to get them as they happen. For live captions this is non-negotiable.
Lazy model loading. The recognition model is big, and by default it loads when the first audio arrives — so your first caption is seconds late. Call prepareToAnalyze when the user hits start, and recognition is instant from the first word.
Slow shutdown. Stopping with finalizeAndFinishThroughEndOfInput() drains the entire audio backlog before returning — a stop/restart (e.g. switching languages) took seconds. For subtitles you don't care about queued audio, so use cancelAndFinishNow().

Gotcha #3: Recognition results rewrite the past

This was the biggest trap of all.

SpeechAnalyzer's partial results don't just grow at the end. Text you already displayed gets rewritten retroactively — filler words ("uh, uh") get collapsed, words get swapped, punctuation appears late.

Wakaru cuts completed sentences out of the growing transcript and translates each one. That means it has to remember where the already-translated part ends. If you store that boundary as a character offset, it silently drifts every time the recognizer rewrites history. The symptoms: the same sentence gets translated twice, or fragments go missing.

The fix: stop trusting positions, and use content as a bookmark. Wakaru remembers the last few words of the most recently committed sentence, and on every update, searches for that anchor in the rewritten text to re-derive the boundary.

One wrinkle remains: if the speaker literally says the same thing twice ("Thank you. Thank you."), the anchor appears in two places. So the rule is "pick the occurrence closest to the previous boundary estimate" — the character offset survives, demoted from source-of-truth to tie-breaker.

Gotcha #4: The Translation framework only works inside SwiftUI

This one surprised me the most. TranslationSession can only be obtained inside SwiftUI's .translationTask view modifier. There is no "just give me a session" API. Wakaru is a menu bar app — there was nowhere natural to put it.

The workaround: the subtitle overlay is a SwiftUI view anyway, so I attached an invisible .translationTask to it. It receives the session and hands it to a hub object that the rest of the app calls into.

.translationTask(hub.configuration) { session in
    await hub.serve(session)   // publish the session to the pipeline
}

Bonus trap: if you stop and restart with the same language pair, the new configuration compares equal to the old one and the task never restarts — you have to call invalidate() explicitly.

Bonus: taming the on-device LLM

On Apple Intelligence Macs, Wakaru has a high-accuracy mode that translates with the on-device LLM instead of the NMT model, passing the previous 3 sentences as context — pronouns, idioms, and short replies come out much more natural.

But a ~3B on-device model in a real-time loop needs guardrails:

2.5s deadline — if the LLM is slower, that sentence silently falls back to the standard engine
Rebuild the session every 10 sentences — as the session transcript grows, the model starts echoing source-language fragments into translations (measured: around sentence 27)
Quarantine degenerate output — greedy decoding occasionally locks into repetition loops (a normal German sentence once became the same Japanese word ×25). There's no repetition penalty setting, so I detect and reject it at the output

The rule that matters: the LLM is never allowed to stall the captions. Every failure mode falls back per-sentence to the standard engine.

Try it / tell me what you think

Wakaru runs on macOS 26+ (Apple silicon). It's free for 14 days (and stays free for 1 hour/day after that), with a one-time purchase for unlimited time — no subscription:

📱 Wakaru on the Mac App Store

Happy to answer any questions about the implementation in the comments! 👇

How I export 1.2-gigapixel images on an iPhone without running out of memory

Yuiko Koyanagi — Mon, 13 Jul 2026 21:38:34 +0000

Rendering a big image on iOS is one of those things that looks trivial until your app gets killed by the OS mid-export. CGContext, draw, makeImage(), done — except the moment the output gets large, that innocent-looking pipeline quietly asks for gigabytes of RAM and iOS terminates you.

I hit this wall building Mozary, an iOS app that packs 100+ photos into a single giant picture (a photo mosaic). In v1.1.0 I finally killed the "high-resolution export crashes with out-of-memory" bug for good.

The fix: stop putting the canvas in RAM at all. Put it in a memory-mapped file and let the OS page it to disk. RAM usage dropped from "4.8 GB, please die" to a few dozen MB, flat, regardless of output size.

This post is the walkthrough — with the actual Swift. If you've ever seen Core Graphics blow up on a big image (mosaics, collages, stitched panoramas, high-res rendering — same trap), this is for you.

TL;DR

A non-compressed bitmap costs 4 bytes/pixel. A 1.2-gigapixel image = ~4.8 GB of RAM just for the canvas.
CGContext(data: nil, ...) allocates that in RAM. context.makeImage() then copies it again. Double death.
Back the canvas with a memory-mapped file (mmap). Writes transparently page out to disk and don't count against your app's memory footprint.
Wrap that same mapping in a CGImage via CGDataProvider — zero copy — and stream it straight to a JPEG on disk. Never call makeImage().
Decode source tiles at their draw size, not full size.
Because you now spend disk instead of RAM: add a free-space pre-flight check and clean up temp files after a crash.

Let's dig in.

The problem: "compressed file size" is a lie about memory

Mozary lays photos out on a grid. A typical high-res export is a 200 × 267 grid with each tile drawn at 150px:

width:  200 × 150 = 30,000 px
height: 267 × 150 = 40,050 px

That's ~1.2 gigapixels.

Here's the part people underestimate: the final JPEG is only a few hundred MB to ~2 GB because JPEG is compressed. But while you're drawing, the canvas is uncompressed — 4 bytes per pixel (RGBA):

30,000 × 40,050 × 4 bytes ≈ 4.8 GB

4.8 GB of RAM for the canvas alone.

iOS caps how much memory an app may use (varies by device, but you'll get jetsammed somewhere in the few-hundred-MB-to-~2-GB range). 4.8 GB is never happening. That's the crash.

The naive way (what I had before)

My original export looked like this — and honestly, it was brute force:

// ❌ OLD: allocate the giant bitmap in RAM

// "Pre-flight": compute how many bytes the bitmap needs
let bitmapBytes = UInt64(imgWidth) * UInt64(imgHeight) * 4
let availableMemory = os_proc_available_memory()
if UInt64(Double(bitmapBytes) * 1.3) > availableMemory {
    // Not enough → just give up on high-res
    throw NSError(domain: "MediaExporter", code: -10, ...)
}

// data: nil → CGContext allocates the bitmap in RAM
let context = CGContext(
    data: nil,
    width: imgWidth,
    height: imgHeight,
    bitsPerComponent: 8,
    bytesPerRow: imgWidth * 4,
    space: colorSpace,
    bitmapInfo: CGImageAlphaInfo.premultipliedLast.rawValue
)!

// ... draw all the tiles ...

// makeImage() duplicates the whole bitmap (another +4.8 GB)
let cgImage = context.makeImage()!

Two problems:

CGContext(data: nil, ...) allocates the canvas in RAM → asks for 4.8 GB.
context.makeImage() copies the canvas again → +4.8 GB at peak.

The os_proc_available_memory() check wasn't a fix — it was a polite "sorry, give up." High-res export only worked on the beefiest devices, and mid-tier sizes could sneak past the check and then crash on the makeImage() copy anyway.

I needed to render the same pixels without ever holding them all in RAM.

The fix: put the canvas on disk, not in RAM

The reframe that unlocked everything:

If 4.8 GB won't fit in RAM, don't put it in RAM.

Enter the memory-mapped file (mmap).

What `mmap` actually buys you

mmap maps a file into your address space. You get a pointer you read and write like normal memory — but the backing store is a file on disk.

The magic is that the OS manages that region in pages:

Pages you write become "dirty" and the OS writes them back to disk as needed.
Once written back (clean), those pages no longer count against your app's memory footprint (the thing that gets you jetsammed).

So even if the canvas is 4.8 GB, the only thing resident in RAM is the handful of pages you're touching right now. Everything else lives on disk. You never trip the memory limit.

In one sentence: I stopped trying to fit the work in the app's own memory, and the crash disappeared.

Step 1 — create the file and map it

let ppc = size.effectivePixelsPerCell(columns: columns, rows: rows)
let imgWidth  = columns * ppc
let imgHeight = rows * ppc
let bytesPerRow = imgWidth * 4
let totalBytes  = bytesPerRow * imgHeight   // ← can be ~4.8 GB

// 1. Create a temp file
let canvasURL = FileManager.default.temporaryDirectory
    .appendingPathComponent("mozary_canvas_\(UUID().uuidString).raw")
FileManager.default.createFile(atPath: canvasURL.path, contents: nil)

// 2. Open it and grow it to the needed size (ftruncate)
let fd = open(canvasURL.path, O_RDWR)
guard fd >= 0, ftruncate(fd, off_t(totalBytes)) == 0 else {
    if fd >= 0 { close(fd) }
    try? FileManager.default.removeItem(at: canvasURL)
    throw NSError(domain: "MediaExporter", code: -11, ...)
}

// 3. Map the file into memory
let mapped = mmap(nil, totalBytes, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0)
close(fd) // The mapping keeps the file alive, so we can close the fd
guard let canvas = mapped, canvas != MAP_FAILED else {
    try? FileManager.default.removeItem(at: canvasURL)
    throw NSError(domain: "MediaExporter", code: -12, ...)
}

// 4. ALWAYS release the mapping, on every exit path
defer {
    munmap(canvas, totalBytes)
    try? FileManager.default.removeItem(at: canvasURL)
}

ftruncate grows the file to totalBytes, but it creates a sparse file — disk is only actually consumed for the bytes you write.

Step 2 — hand the mapping to `CGContext`

CGContext lets you pass your own buffer pointer as data:. Just give it the mmap pointer:

guard let context = CGContext(
    data: canvas,   // ← the mmap'd file, not RAM
    width: imgWidth,
    height: imgHeight,
    bitsPerComponent: 8,
    bytesPerRow: bytesPerRow,
    space: CGColorSpaceCreateDeviceRGB(),
    bitmapInfo: CGImageAlphaInfo.premultipliedLast.rawValue
) else {
    throw NSError(...)
}

// Then just... draw. The destination is transparently disk-backed;
// the Core Graphics code doesn't change at all.
for row in 0..<rows {
    try Task.checkCancellation()
    for col in 0..<columns {
        // ... context.draw(tileCGImage, in: rect) ...
    }
}

This is the beautiful part: from Core Graphics' point of view, nothing changed. It thinks it's drawing into a plain memory buffer. The writes just quietly spill to disk.

Step 3 — nudge finished rows out to disk

The OS will page dirty pages out on its own, but you can help it: tell it explicitly "I'm done with this region, feel free to flush it." That keeps the set of dirty (not-yet-written-back) pages small. The tool is msync:

if row % 10 == 0 {
    progress(0.2 + cellProgress * 0.65)

    // Every 40 rows, async-flush the scanlines we've already finished.
    if row % 40 == 0, row > 0 {
        let flushedBytes = (row * ppc) * bytesPerRow
        msync(canvas, flushedBytes, MS_ASYNC)   // MS_ASYNC = non-blocking
    }
}

Why (row * ppc) * bytesPerRow? A bitmap is a single contiguous byte array in memory — rows laid out top to bottom. My draw loop goes top row → bottom row, so once I'm on row N, every row above it is finished and lives at the start of the buffer:

buffer: [==== finished ====][ drawing ][=== empty ===]
        ↑ canvas            ↑
        |←── flushedBytes ──→|
        msync(MS_ASYNC) on this range =
        "you can write these pages back now"

row * ppc → number of finished pixel rows (ppc = pixels per cell)
× bytesPerRow → convert rows to bytes

One nuance worth stating precisely: MS_ASYNC doesn't free memory directly. It marks those pages clean (safely written to disk). Clean pages are the ones the OS can evict for free when it needs RAM back — because an identical copy already exists on disk. So msync doesn't reclaim memory; it makes memory reclaimable, which keeps your peak footprint low.

The other trap: `makeImage()` copies everything

Second landmine: encoding the JPEG.

Remember context.makeImage() duplicates the whole bitmap. Call it here and you've just asked for +4.8 GB — undoing everything.

So skip it. Wrap the same mmap region in a CGImage directly, handing the pointer to CGDataProvider with no copy:

// Make sure the whole canvas is synced to disk
msync(canvas, totalBytes, MS_SYNC)

// Wrap the mapping in a CGImage WITHOUT copying it.
// The empty releaseData is intentional: the deferred munmap above
// owns the mapping, and it outlives this scope-local image.
guard let provider = CGDataProvider(
    dataInfo: nil,
    data: canvas,
    size: totalBytes,
    releaseData: { _, _, _ in }   // no-op
), let cgImage = CGImage(
    width: imgWidth,
    height: imgHeight,
    bitsPerComponent: 8,
    bitsPerPixel: 32,
    bytesPerRow: bytesPerRow,
    space: CGColorSpaceCreateDeviceRGB(),
    bitmapInfo: CGBitmapInfo(rawValue: CGImageAlphaInfo.premultipliedLast.rawValue),
    provider: provider,
    decode: nil,
    shouldInterpolate: false,
    intent: .defaultIntent
) else {
    throw NSError(...)
}

// Write JPEG straight to a file (no UIImage in between)
let tempURL = FileManager.default.temporaryDirectory
    .appendingPathComponent(UUID().uuidString).appendingPathExtension("jpg")

guard let dest = CGImageDestinationCreateWithURL(
    tempURL as CFURL, "public.jpeg" as CFString, 1, nil
) else { throw NSError(...) }

CGImageDestinationAddImage(dest, cgImage, [
    kCGImageDestinationLossyCompressionQuality: size.jpegQuality
] as CFDictionary)

guard CGImageDestinationFinalize(dest) else { throw NSError(...) }

return tempURL

CGImageDestinationFinalize reads from the CGImage (i.e. the mmap'd file) while it writes the JPEG. The encoder pulls data in tiles, so no giant buffer ever lands fully in RAM here either.

Result: both ends of the pipeline — the canvas input and the JPEG output — stay off the RAM budget.

Bonus win: decode tiles at draw size, not full size

One more thing that mattered. Mozary stores each tile's thumbnail as a 600px JPEG on disk. Decode all of them at full size for a 1,000-photo mosaic and:

600 × 600 × 4 bytes × 1000 photos ≈ 1.4 GB

1.4 GB just for the tile cache — but I only ever draw them at cell size (ppc, 60–150px). So decode them straight to that size with CGImageSourceCreateThumbnailAtIndex:

let thumbOptions = [
    kCGImageSourceCreateThumbnailFromImageAlways: true,
    kCGImageSourceShouldCacheImmediately: true,
    kCGImageSourceCreateThumbnailWithTransform: true,
    kCGImageSourceThumbnailMaxPixelSize: ppc   // ← decode at cell size
] as CFDictionary

// CGImageSourceCreateThumbnailAtIndex(source, 0, thumbOptions)

At 100px a tile is ~40 KB decoded. 1,000 of them fit in a few dozen MB. Never decode at a higher resolution than you'll draw — downsampling on decode is a Core Graphics rule of thumb worth tattooing somewhere.

Spending disk means guarding disk

Trading RAM for disk creates a new constraint: free disk space. During export the uncompressed canvas (4.8 GB) and the JPEG being written (~2 GB) coexist — a peak of ~7 GB.

So I check the actual working space needed, not the final file size, before starting:

// The final "~2 GB" file size badly understates what export transiently needs.
let requiredBytes = size.requiredWorkingBytes(columns: columns, rows: rows)
let freeSpace = (try? FileManager.default.temporaryDirectory
    .resourceValues(forKeys: [.volumeAvailableCapacityForImportantUsageKey])
    .volumeAvailableCapacityForImportantUsage) ?? 0
if freeSpace > 0, freeSpace < requiredBytes {
    throw NSError(...)  // "needs about N GB of temporary free space"
}

func requiredWorkingBytes(columns: Int, rows: Int) -> Int64 {
    let ppc = effectivePixelsPerCell(columns: columns, rows: rows)
    let pixels = Double(columns * ppc) * Double(rows * ppc)
    // uncompressed canvas (4B/px) + JPEG being encoded + safety margin
    return Int64(pixels * 4 + pixels * estimatedBytesPerPixel) + 500_000_000
}

I actually found this the hard way. On a test device with ~2 GB free, the export failed even though my original check (which only accounted for the final file) said there was room. Testing on a nearly-full device is what surfaced it — the real working set needs the transient space, obviously in hindsight. Glad I debugged on a cramped device.

And if the app gets killed mid-export, the defer cleanup never runs and a 2 GB+ temp file is orphaned — which would then eat into the next export's disk check. So I sweep old canvas files on start:

// Sweep temp canvases orphaned by a previous crash
if let leftovers = try? FileManager.default.contentsOfDirectory(
    at: FileManager.default.temporaryDirectory, includingPropertiesForKeys: nil
) {
    for url in leftovers where url.lastPathComponent.hasPrefix("mozary_canvas_") {
        try? FileManager.default.removeItem(at: url)
    }
}

(I also clamp cell size so no dimension exceeds JPEG's 65,535px limit, plus a few other small guards.)

Results

	Before	After
High-res export	Rejected by pre-flight, or crashed on some devices	Works
Peak RAM	~4.8 GB (canvas) + ~4.8 GB (`makeImage` copy)	A few dozen MB, flat
Depends on output size?	Yes — bigger = death	No — constant footprint

Ordinary iPhones now export 1.2-gigapixel mosaics without breaking a sweat.

Takeaways

On iOS, drawing a big image blows up because the uncompressed canvas (4 B/px) exceeds the memory limit — the compressed file size tells you nothing about that.
Back the canvas with mmap so writes page out to disk and stay off your app's memory footprint.
For the output CGImage, avoid context.makeImage() (it copies) — wrap the mmap region with CGDataProvider for a zero-copy hand-off, then stream to disk with CGImageDestination.
Decode inputs at draw resolution, never larger.
Once you spend disk instead of RAM, pair it with a free-space pre-flight and post-crash cleanup.

The general principle — "if it won't fit in RAM, back it with a file and let the OS page it" — goes way beyond Core Graphics. Any time you're wrangling a buffer bigger than memory, mmap is worth reaching for.

If you've fought the same "Core Graphics eats all my memory" battle, I hope this saves you a few crash reports.

Try it out!

Mozary is on the App Store if you want to see the export in action (and I'd genuinely love feedback):
👉 https://apps.apple.com/us/app/mozary/id6759013945

What's your go-to trick for large-image or large-buffer work on mobile? I'd love to hear it in the comments.

Want to keep using Fable 5? Teach Opus and Sonnet to "behave" like it.

Yuiko Koyanagi — Mon, 06 Jul 2026 21:45:11 +0000

A while back I wrote about how I use Fable 5 without going token-bankrupt:

Yuiko Koyanagi

Jul 2

Use Fable 5 where it pays for itself

#claudecode #ai #productivity #agents

7 min read

I put Fable 5 in the orchestrator seat — scoping, design, delegation, final review — while the hands-on implementation, testing, shipping, and code review are done by Opus and Sonnet subagents. The expensive model plans and judges; the cheaper models execute. This ran beautifully for most tasks.

There's just one problem. As you probably know, Fable 5 access via subscription ends on July 7. (I'm praying it comes back to subscription someday… 🙏)

The orchestration setup itself works without Fable 5 — but if the model at the top, the one cutting scope and judging everything, gets downgraded, output quality drops with it.

Here's the thing though: Opus and Sonnet are not bad models. Used correctly, they produce genuinely good output. What matters is writing down what to do, how to do it, and what to do when something fails. So before losing access, I decided to document how Fable 5 actually works and hand it down to Opus/Sonnet — as skills.

This post is about what I did and how. Finding a "replacement for Fable" seemed hopeless, so the goal became something else: raise the whole team's capability so that quality holds even with Opus in the orchestrator seat.

The gap between Fable 5 and Opus/Sonnet is not intelligence

To keep using a pseudo-Fable after the shutdown, I started by examining what the difference actually is.

When Opus/Sonnet produce output I didn't intend during everyday engineering, the failures turn out to follow recognizable patterns. For example:

Slapping "use client" at the top of a Next.js page because one button needs an onClick
- …which drops the entire page and its import tree onto the client
Writing fetch with no cache option
- The defaults are opposite between Next.js 14 and 15, but "it works" was only checked on the dev server — hello, production caching surprise
Skipping input validation in a Server Action because it's "only called from my form"
- It's actually a public POST endpoint anyone can hit with arbitrary arguments
Fetching initial data inside useEffect
- An await in a Server Component would do it, without the request waterfall and the layout flash
"Fixing" a failing test by rewriting the assertion
- Don't touch the assertion until you've proven, with evidence, that the code side is the wrong one
Saying "this should work now" without running anything
- Run it first, then conclude whether it works

What matters here: none of these are knowledge gaps. Ask Sonnet directly — "is a Next.js Server Action dangerous without input validation?" — and it answers correctly. The knowledge is in there. What's missing is the correct procedure.

Fable 5 runs these checks implicitly, without being asked, and pushes back when something's off. With Opus/Sonnet, those checks have to be written down explicitly.

Raw reasoning differences are real, of course. But for routine implementation, review, and debugging, most of the observable quality gap comes down to discipline, sequencing, and verification — and all three can be written as skills.

"Be careful" prompts don't work

My first attempt at Fable-izing Opus/Sonnet was writing "be careful, always verify, follow best practices" into the prompt. Result: nothing happened (obviously, in hindsight). A sentence that doesn't change the model's next move doesn't change its behavior.

So the first rule of documenting Fable's working method was a ban list. No line may contain:

"be careful" / "follow best practices" / "think hard" / "ensure quality"

Every line has to be executable or checkable — runnable as a command, defined as a threshold, expressed as if/then, or greppable as a pattern. It must be unambiguous what the reader does next.

I documented Fable 5's working method along five axes

Before getting into the "how": I maintain ccteams, a CLI that installs pre-built Claude Code subagent teams with one command.

From v0.2.x, every team ships with two skills: a shared working method and a per-team playbook. Here's what actually went into them, in order.

1. Fix the work routine

The classic Opus/Sonnet mistake is starting to write immediately — leaning on training data or earlier context ("Go is usually written like this", "this library's API was like that") without checking the repository in front of it.

So each playbook opens with a numbered procedure that forces pre-writing behavior:

Read go.mod (and its version) before using a language feature
Read the lockfile for the actually-installed version before trusting library docs
Read two neighboring files before picking a pattern
grep before writing a helper (it usually already exists under a different name)

In short, it pre-commits the model to one principle: don't decide from memory — read the repo and decide.

2. Define the failure patterns and their fixes

What mid-tier models lack isn't knowledge — it's that they carry wrong assumptions, and proceed on the premise that the plausible implementation is the correct one. Crushing that tendency is the priority.

So for each team, I defined the common failure patterns in a fixed format:

symptom → wrong instinct → correct move

so that when Opus/Sonnet hits the symptom, it knows exactly how to correct course.

From the ccteams Next.js playbook:

One button needs an onClick → put "use client" at the top of the page → extract the button into its own leaf component, mark only that file client, keep the page a Server Component.

From the Go playbook:

Handler hits an error → call http.Error(w, msg, 500) and keep going → add return immediately after. http.Error writes and returns; your handler doesn't — the success path below writes a second body onto a committed 500 response.

There are 10–15 of these per team (Go team, React Native team, Rails team, and so on). Naming the wrong instinct explicitly lets the model recognize the exact moment it's about to make the mistake. You're patching the decision point, not the knowledge base.

3. Define the decision branches

A frontier model's edge is judgment. Judgment itself can't be transplanted — but 80–90% of the recurring cases can be compiled into explicit branches. From the Go playbook:

Before launching any goroutine — three questions, "nobody" is a forbidden answer:

Who cancels it?

Who waits for it?

Where does its error go?

If any answer is "nobody", don't launch it.

Why this one? Because a goroutine is trivial to launch and hard to clean up. When a mid-tier model casually writes go doWork(), the typical outcomes are:

Nobody stops it → it keeps running after the program should be done, or lives forever (goroutine leak = memory leak)
Nobody waits for it → main exits first and the work silently never completes
The error has nowhere to go → failures inside the goroutine get swallowed, and no one ever notices

This is exactly the kind of thing that goes wrong when vibe-coding Go, so it's defined specifically for the Go team.

There's also a team-independent rule shared by everyone:

State your hypothesis before touching code. A fix without a confirmed root cause is a guess.

This blocks the classic mid-tier move of applying a plausible-looking fix before the root cause is confirmed.

For debugging specifically — where "patch the symptom's location and feel done" accidents are constant — the debug team has a dedicated gate:

Before writing any fix, you must be able to say: "X causes Y, because Z" — where X and Y are observed, and Z explains why this exact symptom appears. If you can't fill in Z, you have a correlation, not a cause.

In other words: no causal sentence, no fix phase. You get sent back to re-verify the hypothesis.

This is the pattern across ccteams: for each team, the decision branches that stop that team's characteristic accidents are written out explicitly.

4. Define the verification method

Verification is cheap compared to generation. Which means: a mid-tier model plus a strong verification harness beats a mid-tier model alone, by a wide margin. So every playbook contains an exact, ordered verification recipe.

Not "please test it" — but which commands, in which order, and what each failure means. For Go: go build ./... → go vet ./... → go test -race ./... (with -race marked non-negotiable). The frontend playbook includes checks no linter will ever run for you: a keyboard-only walkthrough, and resize tests at 320/768/1280px.

On top of that, the shared working method demands execution as the basis for claims. A typical mid-tier shortcut is returning code that has never been run, with a cheerful "this should work". To kill that:

The diff is a claim; execution is evidence. Only after actually running build/test/lint and reading their output is the claim backed.

And to enforce it, every claim in a report must carry a label — VERIFIED (ran it) / REASONED (read the code) / ASSUMED (unchecked) — with silent upgrades forbidden. You can no longer pass off "should work" as "works".

5. Absorb failures one at a time with a learning loop

Everything above was written by Fable in advance — rules based on predicting "a mid-tier model will probably get this wrong". Not bad, but predictions are predictions. Rules grounded in mistakes that actually happened in your project are obviously stronger.

So the working method includes a learning loop: the more you use the team, the more it optimizes itself to your project.

The rule itself is simple: when a mistake surfaces that the playbook didn't anticipate, turn it into a catalog entry, and add it as a rule after human approval.

From v0.2.2, running ccteams use automatically creates .claude/skills/team-lessons/SKILL.md. Once created, this file is never overwritten — not by team switches, not by ccteams updates. It exists to accumulate your project's own failure patterns and their fixes.

When an unanticipated mistake occurs, the AI works out the symptom → wrong instinct → correct move and asks you whether it should be recorded. On approval, the agent appends the entry to team-lessons/SKILL.md.

The result is a team that gets smarter with every failure it absorbs.

That said, bloat is unavoidable on a long-running project. As first-line countermeasures there's a duplicate check (sharpen an existing entry instead of appending a near-copy) and the human approval gate itself — but long-term operation is an open question I'm still thinking about.

Making sure it actually reaches the subagents

Claude Code skills are on-demand: they get invoked when the model decides they're relevant. Which means a "working method" skill is never used unless something makes it relevant — and the subagents actually doing the work never invoke skills on their own, period.

To solve this, I planted it in two places.

1. Embed it in the agent definitions

Every agent's system prompt now begins with FIRST ACTION: Read .claude/skills/<team>-playbook/SKILL.md and follow it. But "read this" alone is sometimes ignored — so as a fallback, the 5–6 most load-bearing rules from the playbook are also embedded inline in the system prompt itself.

2. Embed it at delegation time

The orchestration rules obligate the orchestrator to paste a compressed digest of the shared working method, verbatim, into every delegation prompt.

And as the last line of defense, in case both get slipped past: the orchestrator is instructed to check every report against named gates and reject on failure. "The build output isn't quoted? Sent back." Even if delivery fails completely, work that ignored the discipline doesn't get accepted.

Why not just paste the full text everywhere? Because the more instructions you add, the lower the compliance per instruction. So the always-loaded portion is 5–6 lines, each agent carries ~10 inline lines, and the full ~200 lines are read on demand.

Sounds like a lot of setup, right?

ccteams (v0.2.x and later) already ships with Fable 5's working method handed down to Opus/Sonnet, exactly as described above. If you just want a good team quickly — or a template to study — give it a try:

npm install -g ccteams
ccteams list
ccteams use go-api   # or next-ts, python-fastapi, rails, django, debug — pick your team
# restart Claude Code

If this saved you some setup time, a star on the repository would make my day. Issues and impressions from trying it are very welcome too!

Afterword

My initial plan was to define rules for the orchestrator only. That turned out to be a dead end — because the one getting weaker is the orchestrator. Fable could catch subagents' mistakes at report time with high precision and send them back; no amount of orchestrator-side rules reproduced that behavior on a weaker model.

Rejection is also more expensive than prevention. So I shifted the weight onto preventing mistakes in the first place — raising the whole team — rather than catching them at the top.

I reverse-engineered, shipped, and tested it, and the results were satisfying: bugs that Opus used to miss are now getting caught. For routine work, I'd say this setup has closed most of the gap between Fable and the other models.

What it can't cover is Fable's unique strength: handling the unanticipated. Noticing "something is off" when nothing on any checklist says so; grasping the structure of a genuinely novel problem at a glance. That doesn't transfer through anything you can write in a skill.

That remaining gap is what the learning loop above chips away at — one absorbed failure at a time.

"Make Opus/Sonnet behave like Fable 5" is an idea you see floated a lot, but I rarely found articles that go into the details — so I actually did it and wrote them down. I hope some of it is useful to you.

Use Fable 5 where it pays for itself

Yuiko Koyanagi — Thu, 02 Jul 2026 19:56:24 +0000

Claude Fable 5 is the model I reach for in Claude Code when a task is ambiguous, long-running, or full of tradeoffs — planning across steps, untangling a messy goal, weighing a design choice, keeping a long session pointed in the right direction. It's genuinely good at the hard parts.

Which is exactly why I stopped letting it do the easy ones. At $10 per million input tokens and $50 per million output — double Opus 4.8's $5 / $25 — spending it on boilerplate and lint fixes is like paying a principal engineer to reformat your imports. The work still needs doing. It just doesn't need that person doing it.

A Claude Code task is rarely one task. Take a one-liner like:

Add rate limiting to our API.

Sounds small. But it unfolds into work of very different weights:

deciding the algorithm — token bucket, sliding window, fixed window
choosing where the counter lives — in-memory, or Redis because we run multiple instances
thinking through what happens under a burst, and what a client sees on a 429
writing the middleware
wiring it into every route
writing the tests
fixing the lint and type errors
checking the edge cases — clock skew, the limiter itself failing, keys never expiring

The first three are real design decisions — the kind where a wrong call is expensive and annoying to unwind six months later. The rest is execution: careful work, but not work that rewards a frontier model over a merely-very-good one.

So I don't try to replace Fable 5. I just keep it on the decisions and hand everything else to something cheaper.

Make Fable 5 the lead, not the labor

Concretely, that means treating Fable 5 like a tech lead: it plans and delegates, and other models do the actual building.

Fable 5 = orchestrator — plans, decomposes, synthesizes. Writes no code.
Opus = deep reasoning subagent — architecture, complex debugging, review
Sonnet = mechanical work subagent — implementation, boilerplate, tests, chores
(Optionally) Codex = peer senior engineer — an independent second opinion from a different model family

Fable 5 thinks, delegates, and stitches the results together; the cheaper models handle work they're already good at. So the pricey model is only on the clock for the steps that actually reward its judgment.

The token savings were what I was after. What I didn't expect was the second effect: because Fable 5 never touches raw file contents or stack traces, its context stays clean, and it's still making sharp calls six hours into a session instead of drowning in half-finished edits.

I figured that was the whole setup — three quick steps. It wasn't.

The hard part is the subagents

On paper, it's three steps:

/model → Fable 5
Create subagents with /agents, pinned to Opus and Sonnet
Write routing rules in your CLAUDE.md — which work goes to whom

Step 1 takes ten seconds.

Steps 2 and 3 are where the actual work is. Creating a subagent is fast. Creating one that pulls its weight is not.

Three things I learned the hard way:

The description field decides who gets the work. The orchestrator picks a subagent by reading its description. "Use for reasoning-heavy tasks" is vague enough that the routing quietly drifts, and you don't notice until an answer comes back wrong.
The system prompt decides what comes back. Subagents can't see your conversation. If the prompt doesn't say what to read before acting and what to return — a conclusion, a diff, file:line findings — the orchestrator ends up cleaning up after them. Which is the one thing you were trying to avoid.
"Thinker" and "doer" is too few roles. It's a reasonable start. But real work splits into scoping, design, implementation, verification, and shipping. Collapse verification into the builder, and you have an agent reviewing its own code.

The decision that actually takes time, then, isn't picking models — it's writing a team of subagents whose roles are sharp enough that delegation just works. And that's a surprising amount of careful prose.

ccteams: install the team design in one command

This is the part I got tired of rewriting by hand, so I built a tool for it: ccteams, a package manager for Claude Code agent teams.

npm install -g ccteams
ccteams list           # see the teams
ccteams use generalist # apply one to the current project

That single command drops a full set of role-specialized subagents into .claude/ — descriptions, system prompts, tool restrictions, and a model: per agent already written — plus the orchestration rules that tell the lead session how to run them. Step 3 above (hand-writing routing rules in CLAUDE.md) ships in the box. So does the model assignment — more on that below.

Teams come stack-specific out of the box:

Team	What it's for
`generalist`	Stack-agnostic feature team: scope → design → build → QA → ship
`next-ts`	Next.js (App Router) + TypeScript + Tailwind
`go-api`	Go HTTP API backends
`python-fastapi`	FastAPI + Pydantic v2
`rails` / `django`	Rails / Django + DRF
`debug`	Reproduce → root-cause → minimal fix → regression test
`research`	Technical research that writes no code

Prefer staying inside Claude Code? There's a plugin:

/plugin marketplace add toffyui/ccteams
/plugin install ccteams@ccteams

Then /ccteams:choose-team something for backend API work picks and applies the right team from a natural-language description.

The models are already assigned

Here's the part I only got right recently: every bundled agent already ships with a model: in its frontmatter, assigned by how much reasoning the role needs. You don't add anything. ccteams use generalist lands this:

Agent	Role	Model (preset)
(main session)	Orchestrator	Fable 5 — you pick this with `/model`
`scope-planner`	Cut scope, pin down requirements	`opus`
`architect`	Design decisions	`opus`
`builder`	Implementation, boilerplate, tests	`sonnet`
`qa-reviewer`	Verification, edge-case hunting	`opus`
`shipper`	Commits, CI, chores	`sonnet`

Open any agent file and the line is right there:

---
name: architect
description: Technical design specialist. ...
tools: Read, Glob, Grep, WebSearch, WebFetch
model: opus        # ← already set by ccteams
---

The one model ccteams doesn't touch is the lead session's — that's yours to pick with /model (Fable 5). Everything below it is pinned.

The split is similar to the usual “thinker / doer” setup, but the extra roles matter. Once the work is separated into scoping, design, building, review, and shipping, delegation gets much more precise — and the model choice becomes part of the role instead of a judgment the orchestrator has to remake every time.

The important detail is that I do not assign Fable 5 to roles like architect or qa-reviewer.

That can look backwards at first. If planning and review are the important parts, why not put the best model there too? Because by the time a task reaches those agents, Fable 5 has already done the hardest part: turning an ambiguous user request into a clear, bounded problem that another model can solve.

That is where Fable 5 earns its keep — ambiguous, long-running work full of tradeoffs. Once the question is clearly framed, Opus is usually more than enough to propose a design or review a fix. And those agents still do not get the final say. They propose; Fable 5 decides what to accept.

So Fable 5 keeps control of the core judgment without spending tokens on every intermediate role. The setup does require good orchestration rules and agent prompts, but that is exactly what ccteams installs for you.

Adding Codex as the peer engineer

OpenAI's official Codex plugin lets you call Codex from inside Claude Code (install the Codex CLI on your machine first):

/plugin marketplace add openai/codex-plugin-cc
/plugin install codex@openai-codex
/reload-plugins
/codex:setup

Then add one paragraph to your project's CLAUDE.md (below the @.claude/active-team.md import that ccteams creates):

## Peer engineer
Codex (/codex:rescue --background) is a peer senior engineer with a different
perspective. For high-stakes decisions, task the architect agent and Codex on
the same problem in parallel and synthesize — without showing either the
other's answer.

The point is to use Codex as a peer rather than a rubber-stamp reviewer. On a high-stakes call, I give the same problem to the Opus-pinned architect and to Codex at the same time, neither seeing the other's answer, and let Fable 5 reconcile the two. You get the most out of this when the two models come from different lineages — Opus and Codex were trained differently enough that they tend to miss different things, so one often catches what the other glossed over.

Back to "add rate limiting"

Remember that one-liner from the top? Here's the whole prompt I use:

Add rate limiting to our API.
Context: Express + Redis, deployed as 3 instances behind a load balancer.

I just state the goal. Claude Code routes the rest on its own — it matches the task against each agent's description and delegates automatically, so Fable 5 sends the algorithm-and-storage question to architect, the implementation to builder, the edge cases to qa-reviewer, without me naming any of them.

And because each agent's model is pinned in its frontmatter, that routing decision is the model decision. The moment architect is chosen, the design call runs on Opus, where being wrong is expensive; builder's middleware and tests run on Sonnet. Fable 5 plans and synthesizes on a clean context and writes no code itself — so the priciest model in the room is billed only for the judgment that actually needed it.

That was the goal all along: not to spend less on Fable 5, but to spend it only where it pays for itself.

In short

Fable 5 is worth its price on judgment — planning, design, review — and wasteful on everything else
The hard part of this setup isn't picking models, it's designing the team that surrounds them
ccteams installs a considered team in one command — orchestration rules and a per-agent model: preset included, so the Fable-lead / Opus-reason / Sonnet-build split is live the moment you apply it
Pick your lead model with /model, restart Claude Code, and you're done — repin any agent's model: line if you want a different split

If this saves you some setup, a star on the repo is the nicest way to say so — and if the presets don't match how you'd split the work, open an issue and tell me 🙌

React Native team and django team are available now!

Yuiko Koyanagi — Wed, 01 Jul 2026 14:23:58 +0000

Yuiko Koyanagi

Jun 18

One command turns Claude Code into a full dev team

#claudecode #ai #opensource #cli

3 min read

I built a Chrome extension that lets you blow up any webpage

Yuiko Koyanagi — Tue, 30 Jun 2026 15:25:11 +0000

I built a Chrome extension called Site Bomb. It does exactly one thing: you drop little bombs anywhere on a webpage, and the text near the blast gets physically blown apart, letter by letter.

It is completely useless. It is also genuinely satisfying when you're stressed.

Here's how it works, and the three things I had the most fun figuring out.

1. Turning page text into something you can blow up

You can't apply physics to a plain text node — a paragraph is one indivisible blob as far as the DOM is concerned. So before anything explodes, Site Bomb walks the page and rewrites every visible text node, wrapping each individual character in its own element:

string.split("").map((char) =>
  /\s/.test(char)
    ? "&nbsp;"
    : `<particle style="display:inline-block;">${char}</particle>`
);

Now every letter is its own inline-block box that can be moved, rotated, and flung around independently — while the page still reads normally until a bomb goes off. Whitespace is preserved so the layout doesn't collapse.

2. The blast: a little bit of fake physics

When a bomb explodes, each particle (letter) looks at its distance from the blast center and gets pushed away with a force that falls off with distance — roughly an inverse-square feel, capped so close letters don't fly off to infinity:

const distX = this.x - blast.x;
const distY = this.y - blast.y;
const distance = distX * distX + distY * distY;

let force = 150000 / distance; // closer = stronger
if (force > 40) force = 40;    // clamp so it doesn't explode *too* hard

const rad = Math.asin((distY * distY) / distance);
this.velocityX = Math.cos(rad) * force * (distX < 0 ? -1 : 1);
this.velocityY = Math.sin(rad) * force * (distY < 0 ? -1 : 1);

Then every frame each letter drifts by its velocity, slowly bleeding off speed (a crude friction) and rotating as it goes, all driven through a CSS transform inside a requestAnimationFrame loop. It's not real physics — it just has to feel explosive, and a distance-based force plus some decay gets you there surprisingly cheaply.

3. The bug that annoyed me for years: clicks getting eaten

The most satisfying fix had nothing to do with explosions.

Originally the click handler lived on document.body.onclick. That relies on the click event bubbling up to <body>. The problem: tons of sites call event.stopPropagation() on their own click handlers, so the event dies before it ever reaches body. The symptom was maddening — on some sites bombs only dropped intermittently, and you'd click five times and then all five would go off at once.

The fix was to stop relying on bubbling and listen on the way down instead,
using the capture phase:

document.addEventListener(
  "click",
  (event) => dropBomb(event),
  true // useCapture — fires before any element can stopPropagation()
);

Capture-phase listeners run as the event travels from the root down to the target, before the bubbling phase where stopPropagation() usually lives. One true and clicks now register instantly, everywhere.

Keeping it well-behaved

Actually I released this a few years ago but then one day it got pulled from the Chrome Web Store because it didn't follow Chrome extension best practice.

So, whilst updating Manifest from V2 to V3 this time, I also made corrections to the following minor details.

A couple of small things that matter for an extension that injects into any site:

Minimal permissions. It only needs activeTab — temporary access to the current tab, granted when you click the toolbar icon. No "read all your data on every website" scare. (It's also Manifest V3, with the script injected via chrome.scripting.)
One click to toggle. Clicking the icon turns bomb mode on for that tab (with an ON badge), and clicking again turns it off — state is tracked per tab.
Don't break the page. A re-injection guard stops it from running twice, and elements like <script>, <input>, and <video> are skipped so the page stays usable.

Try it

If you ever want to blow up a webpage:

🔗 https://chromewebstore.google.com/detail/site-bomb/hnnabnffilimfgdcinlijkjkdemdonea?authuser=0&hl=ja

One command turns Claude Code into a full dev team

Yuiko Koyanagi — Thu, 18 Jun 2026 09:43:49 +0000

I love Claude Code's subagents. But I kept noticing the same chore: every new project, I'd hand-write the same crew again — a builder, a reviewer, someone to keep the stack conventions straight. Good setups, but they lived in one repo and never got reused.

So I built ccteams — a package manager for agent teams. One command drops a ready-made team of Claude Code subagents into your project.

npm install -g ccteams
ccteams use go-api // apply your favourite team

That applies a Go builder + reviewer, tuned for net/http, to the current project. Switch when the work changes:

ccteams use next-ts     # Next.js App Router + TypeScript + Tailwind
ccteams use generalist  # scope -> design -> build -> QA -> ship, any stack

Are you not sure which team you need? Don't worry, you can use /ccteams:choose-team and AI will choose the best team for you!

/plugin marketplace add toffyui/ccteams
/plugin install ccteams@ccteams
/ccteams:choose-team I want to create a todo app.

What's a "team"?

A team is just a curated bundle of Claude Code subagents — each a markdown file with the usual name / description / tools frontmatter and a system prompt — plus an orchestration.md that gets merged into your project's CLAUDE.md. Nothing magic, nothing proprietary. It's the setup you'd build by hand, except already built and ready to reuse.

ccteams ships with 8 teams:

generalist — stack-agnostic, takes a feature scope → design → build → QA → ship
next-ts — Next.js App Router + TypeScript + Tailwind
frontend — framework-agnostic UI/UX and accessibility
go-api — idiomatic Go HTTP APIs
python-fastapi — FastAPI + Pydantic v2
rails — Ruby on Rails
debug — reproduce → root-cause → fix → regression test
research — compares options and recommends; writes no code

What `use` actually does

No black box. ccteams use <team>:

Copies the team's agents into .claude/agents/
Writes .claude/active-team.md and adds an @.claude/active-team.md import to your CLAUDE.md
Tracks everything in .claude/.ccteams-manifest.json so switching teams is clean
Won't overwrite agents you wrote by hand — there's a collision guard

Switching to another team removes only what ccteams placed last time. Your own files are never touched.

The one catch: restart

Being honest, because this trips people up: Claude Code loads subagents at session start. So after ccteams use, you have to restart Claude Code for the team to take effect. It is not instant. Run the command, then /exit and relaunch.

Optional: do it from inside Claude Code

There's an optional plugin that adds slash commands, so you don't have to leave Claude Code:

/plugin marketplace add toffyui/ccteams
/plugin install ccteams@ccteams

Then /ccteams:list-teams, /ccteams:use-team <team>, and the fun one — /ccteams:choose-team — where you describe what you need in plain English and it picks the team for you. The plugin is optional; the CLI works fine on its own.

Power users: parallel teammates

If you want the team members to run in parallel and message each other instead of one-at-a-time delegation, opt in:

ccteams use generalist --agent-teams

That turns on Claude Code's experimental agent-teams mode for the project. It's experimental, so treat it as a power-user option, not the default.

Try it

npm install -g ccteams
ccteams list

It's open source (MIT): github.com/toffyui/ccteams. If it's useful, a star helps a lot.

One real question for you: which stack should I add a team for next? I'm weighing Spring Boot, Django, and SwiftUI — tell me in the comments what you'd actually use.

I built “Mozary”: An iOS App That Turns Your Photos Into a Zoomable Mosaic

Yuiko Koyanagi — Fri, 13 Mar 2026 15:42:56 +0000

Mozary is an iOS app that turns hundreds of your photos into a single zoomable mosaic.

Zoom out → it looks like one image
Zoom in → individual photos appear (and you rediscover forgotten moments)

App Link: https://apps.apple.com/us/app/mozary/id6759013945
Try it out!

#buildinpublic #mobileapp #computervision #imageprocessing #productdevelopment | Yuiko Koyanagi

I’ve been building a photo mosaic app that creates an image from images. You pick a target photo, and the app composes it using many smaller photos—so from a distance it looks like one picture, but when you zoom in, you can still see each individual photo clearly. I put a lot of work into the processing pipeline, and the generation is genuinely fast (the video isn’t sped up). Now it’s in app review—excited to share more once it’s live! #buildinpublic #mobileapp #computervision #imageprocessing #productdevelopment

linkedin.com

The idea (why I built it)

I take a lot of photos, but I rarely revisit them.

I wanted a way to turn “a pile of photos” into something you actually want to look at.

During a trip, I saw a huge mosaic wall and thought: what if my own memories could become a mosaic artwork?

That became Mozary.

How it works (user flow)

Choose a target image (what the mosaic becomes)
Choose photos from your library to use as tiles (up to 1000)
Generate (usually 5–20s, up to ~40s for 1000 photos)
Pinch to zoom, then export as an image/video

The engineering part: making the viewer buttery smooth

The hardest part wasn’t generating the mosaic.

It was rendering it interactively.

A mosaic like 200×150 already means 30,000 tiles.

Naively drawing them every frame is a fast path to jank (or crashes).

Borrowing an idea from Google Maps: LOD (Level of Detail)

Google Maps doesn’t draw every tiny detail at every zoom level.

It switches what it renders depending on zoom.

Mozary uses a similar LOD approach (3 levels):

Zoomed out: draw a single pre-rendered image

Instead of looping through 30,000 tiles, I pack each tile color into a pixel and render one image.

Same look, dramatically cheaper.
Zoomed in: render only what’s visible, in 256×256px tiles

I issue render requests only for the region currently on screen.
Keep the main thread free: heavy rendering runs on a background thread

So pan/zoom stays responsive.

Result: the mosaic scrolls/zooms smoothly even at large sizes.

Color matching: RGB → Lab

Mosaic quality is mostly about color matching.

I first tried RGB distance, but it often chose tiles that were numerically close yet visually off.

RGB isn’t perceptually uniform.

Switching to Lab color space improved matches immediately:

Convert each photo’s average color RGB → Lab
For each grid cell, pick the tile with the smallest Euclidean distance in Lab

Simple change, big visual improvement.

Optional: Color grading when your photo set lacks colors

Sometimes your selected photos don’t cover the target’s color palette.

So I added an optional “color grading overlay”:

overlay the target’s hue + saturation
keep the tiles’ luminance (so the photo texture stays)

It’s subtle when your set already has enough color, but helpful when it doesn’t:

Speed tricks that mattered

Two practical optimizations made generation fast enough for real use:

Parallelize photo analysis (average color computation)
Downsample for analysis (I use ~40×40px instead of full-res)

Even if photos are several MB, the color info needed for matching is captured at small size—saving both memory and time.

What I want to improve next

Reduce repeated use of the same tile photo (more even distribution)

That's it!

If you try it, I’d love feedback—especially on export quality and performance on older devices.

App Link: https://apps.apple.com/us/app/mozary/id6759013945

Hosting Applications with AWS CDK: An Introduction to Infrastructure as Code

Yuiko Koyanagi — Wed, 16 Oct 2024 10:18:27 +0000

Introduction

Until now, I have been manually building the infrastructure for my applications. This time, I challenged myself to manage the infrastructure using Infrastructure as Code (IaC).

By utilizing AWS CDK, I was able to codify complex infrastructure settings, manage them simply, and enable efficient deployments. In this article, I will introduce how to host an application using IaC with AWS CDK.

Overview of the Application Architecture

The application I created this time has the following structure. I designed it to efficiently run both the frontend and backend using Docker images on AWS.

Frontend: React + TypeScript
Backend: NestJS + TypeScript Below is a diagram of the application's architecture:

Infrastructure Design

First, I needed to create a secure network configuration using a VPC (Virtual Private Cloud). Therefore, I set up public and private subnets within the VPC.

I placed an ALB (Application Load Balancer) in the public subnet and the backend and frontend servers managed by ECS (Elastic Container Service) Fargate in the private subnet. This ensures that the servers are not directly exposed to the outside, enhancing security.

Users can access the application via the Internet Gateway. Access is received through the ALB placed in the public subnet. The ALB is designed to route requests to the appropriate services and perform load balancing.

For the database, I decided to use DynamoDB to store data. The ECS tasks in the private subnet are configured to access DynamoDB via VPC endpoints. This allows communication with DynamoDB without going through the internet, improving communication security and performance.

The Docker images used by the servers are stored in ECR (Elastic Container Registry). ECS uses these images to run the application. Additionally, by obtaining images from S3 and ECR via VPC endpoints, it is possible to use resources within the private network.

Implementation

Next, I will translate the above infrastructure design into code.

Setup

First, set up the authentication information using AWS CLI:

aws configure

Then, proceed with the CDK setup:

npm install -g aws-cdk
mkdir cdk && cd cdk  # Create a directory of your choice and move into it
cdk init app --language typescript
cdk bootstrap aws://${AWS_ACCOUNT_ID}/${AWS_REGION_NAME}

This automatically generates the files necessary for CDK settings.

Prepare Docker images for both the frontend and backend and store them in ECR.

Writing the CDK Content

Modify cdk-stack.ts Since the CdkStack class is already created, write the above design into its constructor. I want to create various environments such as testing and production, so I add environment as an argument to the constructor for future use.

export class CdkStack extends cdk.Stack {
  constructor(
    scope: Construct,
    id: string,
    environment: string, // Added
    props?: cdk.StackProps
  ) {

This CdkStack class is called in cdk.ts, so modify the code in cdk.ts to make environment usable:

#!/usr/bin/env node
import * as cdk from "aws-cdk-lib";
import "source-map-support/register";
import { CdkStack } from "../lib/cdk-stack";

const app = new cdk.App();
const environment = app.node.tryGetContext("env"); // Obtain from command line during deployment
new CdkStack(app, `${environment}CdkStack`, environment);
app.synth();

From here, write the content inside the constructor of the CdkStack class in cdk-stack.ts.

First, create a VPC. Since we need private and public subnets this time, write as follows:

const vpc = new ec2.Vpc(this, `${environment}AppVpc`, {
  vpcName: `${environment}AppVpc`,
  maxAzs: 2,
  natGateways: 1,
  subnetConfiguration: [
    {
      name: `${environment}AppPublicSubnet`,
      subnetType: ec2.SubnetType.PUBLIC,
      cidrMask: 24,
    },
    {
      name: `${environment}AppPrivateSubnet`,
      subnetType: ec2.SubnetType.PRIVATE_ISOLATED,
      cidrMask: 24,
    },
  ],
});

Regarding the Internet Gateway, since we are creating a public subnet, it is automatically created even though it is not explicitly mentioned in the code.

Next, create VPC endpoints that the private subnet will use:

// VPC Endpoint for DynamoDB
vpc.addGatewayEndpoint(`${environment}DynamoDbEndpoint`, {
  service: ec2.InterfaceVpcEndpointAwsService.DYNAMODB,
});

// VPC Endpoint for S3 (necessary for obtaining Docker images)
vpc.addGatewayEndpoint(`${environment}S3Endpoint`, {
  service: ec2.GatewayVpcEndpointAwsService.S3,
});

// VPC Endpoint for ECR (endpoint to send requests)
vpc.addInterfaceEndpoint(`${environment}EcrApiEndpoint`, {
  service: ec2.InterfaceVpcEndpointAwsService.ECR,
  subnets: { subnetType: ec2.SubnetType.PRIVATE_ISOLATED },
});

// VPC Endpoint for ECR Docker (endpoint to obtain Docker images)
vpc.addInterfaceEndpoint(`${environment}EcrDockerEndpoint`, {
  service: ec2.InterfaceVpcEndpointAwsService.ECR_DOCKER,
  subnets: { subnetType: ec2.SubnetType.PRIVATE_ISOLATED },
});

// VPC Endpoint for CloudWatch Logs (for logging)
vpc.addInterfaceEndpoint(`${environment}CloudWatchLogsEndpoint`, {
  service: ec2.InterfaceVpcEndpointAwsService.CLOUDWATCH_LOGS,
  subnets: { subnetType: ec2.SubnetType.PRIVATE_ISOLATED },
});

All connections are with the private subnet, but for DynamoDB and S3, we can use addGatewayEndpoint (gateway-type endpoints), so specifying the subnet is unnecessary.

Next, create ECS, which is necessary for container management:

const cluster = new ecs.Cluster(this, `${environment}AppCluster`, {
  clusterName: `${environment}AppCluster`,
  vpc: vpc,
});

Create an IAM role for Fargate to use:

const taskExecutionRole = new iam.Role(
  this,
  `${environment}TaskExecutionRole`,
  {
    // Ensure only ECS tasks can assume this role
    assumedBy: new iam.ServicePrincipal("ecs-tasks.amazonaws.com"),
  }
);

// Attach necessary access permissions
taskExecutionRole.addManagedPolicy(
  iam.ManagedPolicy.fromAwsManagedPolicyName(
    "service-role/AmazonECSTaskExecutionRolePolicy"
  )
);

Create a Fargate task definition for the frontend:

const frontendTaskDef = new ecs.FargateTaskDefinition(
  this,
  `${environment}AppFrontendTaskDef`,
  {
    family: `${environment}AppFrontendTaskDef`,
    memoryLimitMiB: 512,
    cpu: 256,
    executionRole: taskExecutionRole,
  }
);

Since we are using ECR, specify the image repository for the frontend (unnecessary if using Docker Hub):

const frontendRepository = ecr.Repository.fromRepositoryName(
  this,
  `${environment}frontendRepository`,
  "app-react-nginx-image"
);

Add container information to the task definition created above. This time, we specify the image repository:

const frontendContainer = frontendTaskDef.addContainer(
  `${environment}AppFrontendContainer`,
  {
    containerName: `${environment}AppFrontendContainer`,
    image: ecs.ContainerImage.fromEcrRepository(
      frontendRepository,
      "latest"
    ),
    logging: new ecs.AwsLogDriver({
      streamPrefix: "Frontend", // Prefix for logging
    }),
  }
);

frontendContainer.addPortMappings({
  containerPort: 80,
  protocol: ecs.Protocol.TCP,
});

The containerPort refers to the port for access from the ALB to Fargate, so it can remain as 80 regardless of whether the app itself is hosted with HTTPS.

Next, launch a Fargate service for the frontend server:

const frontendService = new ecs.FargateService(
  this,
  `${environment}AppFrontendService`,
  {
    serviceName: `${environment}AppFrontendService`,
    cluster: cluster,
    taskDefinition: frontendTaskDef,
    assignPublicIp: false,
    vpcSubnets: {
      subnetType: ec2.SubnetType.PRIVATE_ISOLATED,
    },
  }
);

// Configure auto-scaling
const scalingFrontend = frontendService.autoScaleTaskCount({
  minCapacity: 1,
  maxCapacity: 5,
});

// Auto-scale when CPU utilization exceeds 50%
scalingFrontend.scaleOnCpuUtilization("CpuScalingFrontend", {
  targetUtilizationPercent: 50,
});

// Auto-scale when memory utilization exceeds 70%
scalingFrontend.scaleOnMemoryUtilization("MemoryScalingFrontend", {
  targetUtilizationPercent: 70,
});

With this, the settings for the frontend server are complete. Next, proceed to set up the backend server. Since it is almost the same as the frontend server, explanations will be brief.

const backendTaskDef = new ecs.FargateTaskDefinition(
  this,
  `${environment}AppBackendTaskDef`,
  {
    family: `${environment}AppBackendTaskDef`,
    memoryLimitMiB: 512,
    cpu: 256,
    executionRole: taskExecutionRole,
  }
);

const backendRepository = ecr.Repository.fromRepositoryName(
  this,
  `${environment}backendRepository`,
  "app-nestjs-image"
);

const backendContainer = backendTaskDef.addContainer(
  `${environment}AppBackendContainer`,
  {
    containerName: `${environment}AppBackendContainer`,
    image: ecs.ContainerImage.fromEcrRepository(
      backendRepository,
      "latest"
    ),
    logging: new ecs.AwsLogDriver({
      streamPrefix: "Backend",
    }),
  }
);

backendContainer.addPortMappings({
  containerPort: 3000,
  protocol: ecs.Protocol.TCP,
});

const backendService = new ecs.FargateService(
  this,
  `${environment}AppBackendService`,
  {
    serviceName: `${environment}AppBackendService`,
    cluster: cluster,
    taskDefinition: backendTaskDef,
    assignPublicIp: false,
    vpcSubnets: {
      subnetType: ec2.SubnetType.PRIVATE_ISOLATED,
    },
  }
);

const scalingBackend = backendService.autoScaleTaskCount({
  minCapacity: 1,
  maxCapacity: 5,
});

scalingBackend.scaleOnCpuUtilization("CpuScalingBackend", {
  targetUtilizationPercent: 60,
});

scalingBackend.scaleOnMemoryUtilization("MemoryScalingBackend", {
  targetUtilizationPercent: 75,
});

Next, create the ALB:

const loadBalancer = new elbv2.ApplicationLoadBalancer(
  this,
  `${environment}AppApplicationLoadBalancer`,
  {
    vpc,
    loadBalancerName: `${environment}AppApplicationLoadBalancer`,
    internetFacing: true,
  }
);

Connect the ALB to resources in the private subnet:

const FrontendTargetGroup = new elbv2.ApplicationTargetGroup(
  this,
  `${environment}AppFrontendTG`,
  {
    targetGroupName: `${environment}AppFrontendTG`,
    vpc,
    port: 80,
    protocol: elbv2.ApplicationProtocol.HTTP,
    targets: [frontendService],
    healthCheck: {
      path: "/",
    },
  }
);

const backendTargetGroup = new elbv2.ApplicationTargetGroup(
  this,
  `${environment}AppBackendTG`,
  {
    targetGroupName: `${environment}AppBackendTG`,
    vpc,
    port: 3000,
    protocol: elbv2.ApplicationProtocol.HTTP,
    targets: [backendService],
    healthCheck: {
      path: "/v1/health", // Specify the API for health checks
    },
  }
);

Describe the ALB's request handling:

const listener = loadBalancer.addListener(`${environment}HttpListener`, {
  port: 80,
  open: true,
  defaultAction: elbv2.ListenerAction.forward([FrontendTargetGroup]),
});

listener.addTargetGroups(`${environment}BackendTargetGroups`, {
  targetGroups: [backendTargetGroup],
  priority: 1,
  conditions: [elbv2.ListenerCondition.pathPatterns(["/v1/*"])],
});

This time, we are using a single ALB to distribute traffic to the frontend and backend. By default, requests are forwarded to the frontend, but if there is access with /v1, it is set to forward to the backend Fargate. If you are using two ALBs, the addTargetGroups configuration is unnecessary.

Finally, create the necessary DynamoDB table. In DynamoDB, only the PartitionKey is mandatory, but you can include SortKey, Index, and TTL as needed.

const usersTable = new dynamodb.Table(this, `${environment}UsersTable`, {
  tableName: `${environment}-users`,
  partitionKey: {
    name: "account_id",
    type: dynamodb.AttributeType.STRING,
  },
});
usersTable.grantReadWriteData(backendTaskDef.taskRole);

Now that we have written the code necessary for IaC, we just need to execute and verify it.

Execution

First, check for syntax errors in the CDK code above:

cdk synth --context env=dev

If there are errors, they will appear as follows, so fix them as needed:

Error: Validation failed with the following errors:
  [undefinedCdkStack/undefinedAppFrontendTargetGroup] Target group name: "undefinedAppFrontendTargetGroup" can have a maximum of 32 characters.
  [undefinedCdkStack/undefinedAppBackendTargetGroup] Target group name: "undefinedAppBackendTargetGroup" can have a maximum of 32 characters.

If you can execute without errors, proceed to deploy. If the Docker image is not functioning properly, Fargate will repeatedly start up, encounter errors, shut down, and restart. If it is taking an excessive amount of time, please check the AWS Management Console.

cdk deploy --context env=dev

With this, hosting the application using IaC is complete.

Conclusion

This was my first attempt at IaC, and by managing the infrastructure as code, I found it very beneficial to build infrastructure for multiple environments such as production and development without human errors.

If this article was helpful in any way, I would be encouraged if you could press the like button! Thank you for reading to the end.

How to Automatically Adjust Colors in High Contrast Mode

Yuiko Koyanagi — Thu, 22 Aug 2024 14:10:05 +0000

Introduction

I recently received a bug report where an SVG icon was not displaying correctly in high contrast mode. In this article, I’ll share the solution that worked for me.

Solution

In high contrast mode, I used the CanvasText system color to automatically adjust the icon's color.

.icon {
  mask-image: url(svg-link);
  background-color: currentColor;
  ...
}

@media (forced-colors: active) {
  .icon::before {
    background-color: CanvasText;
  }
}

In my case, I initially used currentColor to inherit the color from the parent element. However, in high contrast mode, I wanted to set the background-color to CanvasText universally within the child element, so I applied this change.

What is CanvasText?

CanvasText refers to the text color used for application content or documents. It automatically adjusts to provide the best contrast against the system's background color.

By using CanvasText, you ensure that text and icons remain visible even when the user enables high contrast mode. Additionally, since CanvasText adapts based on the system's theme, it works well with both dark and light modes.

In my case, the icon's background-color was initially set to black. However, when the background turned black in high contrast mode, the icon became invisible. Changing the color to white made it visible again, but to handle this consistently across all scenarios, I opted to use the system color CanvasText.

References

https://developer.mozilla.org/en-US/docs/Web/CSS/system-color

DEV Community: Yuiko Koyanagi

Best AI Gateways with Built-In Observability & Governance (2026)

What an AI gateway is

The two families

Self-hosted: Bifrost

Self-hosted: LiteLLM

Managed: Cloudflare AI Gateway

Managed: Vercel AI Gateway

Cost structure

How to choose

Bottom lines

Stop asking your AI agent to follow rules. Enforce them.

TL;DR

Two kinds of rules

The mechanism: exit code 2

What I shipped

Why this beats prompt rules

The payoff: you can downgrade the model

The boundary (don't hook everything)

Try it

Apple quietly shipped everything you need to build a real-time translator — so I built one

TL;DR

First attempt: Electron (and why I threw it away)

Architecture: four stages, zero dependencies

Making it feel like movie subtitles (not a log viewer)

Gotcha #1: Set the sample rate at capture time

Gotcha #2: SpeechAnalyzer is slow by default — in three different ways

Gotcha #3: Recognition results rewrite the past

Gotcha #4: The Translation framework only works inside SwiftUI

Bonus: taming the on-device LLM

Try it / tell me what you think

How I export 1.2-gigapixel images on an iPhone without running out of memory

TL;DR

The problem: "compressed file size" is a lie about memory

The naive way (what I had before)

The fix: put the canvas on disk, not in RAM

What mmap actually buys you

Step 1 — create the file and map it

Step 2 — hand the mapping to CGContext

Step 3 — nudge finished rows out to disk

The other trap: makeImage() copies everything

Bonus win: decode tiles at draw size, not full size

Spending disk means guarding disk

Results

Takeaways

Try it out!

Want to keep using Fable 5? Teach Opus and Sonnet to "behave" like it.

Use Fable 5 where it pays for itself

The gap between Fable 5 and Opus/Sonnet is not intelligence

"Be careful" prompts don't work

I documented Fable 5's working method along five axes

1. Fix the work routine

2. Define the failure patterns and their fixes

3. Define the decision branches

4. Define the verification method

5. Absorb failures one at a time with a learning loop

Making sure it actually reaches the subagents

1. Embed it in the agent definitions

2. Embed it at delegation time

Sounds like a lot of setup, right?

Afterword

Use Fable 5 where it pays for itself

Make Fable 5 the lead, not the labor

The hard part is the subagents

ccteams: install the team design in one command

The models are already assigned

Adding Codex as the peer engineer

Back to "add rate limiting"

In short

React Native team and django team are available now!

One command turns Claude Code into a full dev team

I built a Chrome extension that lets you blow up any webpage

1. Turning page text into something you can blow up

2. The blast: a little bit of fake physics

3. The bug that annoyed me for years: clicks getting eaten

Keeping it well-behaved

Try it

One command turns Claude Code into a full dev team

What's a "team"?

What use actually does

What `mmap` actually buys you

Step 2 — hand the mapping to `CGContext`

The other trap: `makeImage()` copies everything

What `use` actually does