magarcia

Using Claude Code Agent Teams for Incident Investigation

contact@magarcia.io — Mon, 02 Mar 2026 00:00:00 GMT

Last week we had a production incident at work. Services were failing, pods were restarting, and the on-call channel was filling up fast. I decided to try something I hadn't used in a real scenario before: Claude Code's agent teams feature.

The result surprised me. With a single, unstructured prompt and a few MCP integrations, Claude self-organized a parallel investigation that identified the root cause in minutes.

Agent teams: parallel Claude sessions that talk to each other

Claude Code has an experimental feature called agent teams that coordinates multiple Claude Code instances. One session acts as the orchestrator and spawns teammates, each running in its own context window on a different part of the problem.

Unlike regular subagents, which run inside a single session and report back only to the main agent, teammates communicate with each other directly. They share a task list, claim work, and exchange findings.

This matters for incident investigation because you're typically exploring multiple hypotheses at once: is it a deployment issue? A database problem? An infrastructure change? Having agents investigate these in parallel, sharing what they find, mirrors how a good incident response team operates.

Enabling agent teams

Agent teams are disabled by default. To enable them, add this to your settings.json (either global at ~/.claude/settings.json or project-level):

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

That's all the setup needed. Once enabled, you can ask Claude to create a team from any session.

The MCP setup that makes it useful

Agent teams pair well with MCP (Model Context Protocol) integrations. I had three configured:

Datadog — for querying logs and metrics
Slack — for reading incident channels and coordination threads
Sentry — for error tracking and exception details

With these in place, Claude's agents query the same observability tools your team uses during incidents — dashboards, logs, error traces — without you copy-pasting anything.

MCP is a protocol that lets AI tools connect to external services. Claude Code supports it natively, and you configure servers in a .mcp.json file at the root of your project or globally.

A note on data privacy: this setup sends production logs, error traces, and Slack messages to Anthropic's API. Before doing this at your company, make sure your usage complies with your organization's data handling policies. Check whether your API plan includes zero data retention, and consider whether the telemetry you're sending contains PII or other sensitive data that shouldn't leave your infrastructure.

How I kicked it off

I opened a Claude Code session in our monorepo and gave it a deliberately minimal prompt. First:

Check the incident going on and make me a summary: https://myworkspace.slack.com/archives/C0123ABC456

Then, after getting the initial summary:

Use a team of agents to help me find the root cause, when doing any exploration ALWAYS use teammates to avoid filling the context of the main thread

That was it. Two messages, no detailed instructions. I wanted to see how much structure Claude would impose on its own.

What happened next:

Claude created an orchestrator that broke the investigation into areas: infrastructure metrics, error tracking, recent code changes, and team communications.
It spawned four specialized agents, one for each area. Each agent had a clear mandate and access to the relevant MCP tools.
The agents started investigating in parallel. One queried Datadog for pod metrics and restart patterns. Another pulled recent exceptions from Sentry. A third reviewed recent deployments and code changes. The fourth monitored the Slack incident channel to pick up context from what the human team was reporting.

The orchestrator's task list ended up looking something like this:

Task List (incident-investigation)
─────────────────────────────────────────────
#1  ✅  Read Slack incident channel for context       @slack-monitor
#2  ✅  Query Datadog for pod restart patterns         @infra-agent
#3  ✅  Pull recent Sentry exceptions                  @error-tracker
#4  ✅  Review recent deployments and code changes     @code-reviewer
#5  ✅  Cross-reference login failures with pod metrics @infra-agent
#6  ✅  Investigate missing config parameter           @infra-agent
#7  ✅  Synthesize findings into root cause summary    @orchestrator

Four agents, one root cause

The agents explored several hypotheses simultaneously. Some turned out to be dead ends — a recent dependency upgrade, a configuration key change — but because agents worked in parallel, they ruled out bad leads fast without blocking the main thread.

Cross-agent communication stood out. When the Slack-monitoring agent picked up that teammates were reporting login failures, it shared that with the infrastructure agent, which narrowed its search to authentication-related services. When the code review agent found that a recent change was unrelated to the failing service (it affected a Node.js backend, but the failing service was PHP/Apache), it reported back and the team pivoted.

The agents converged on the root cause, and the orchestrator delivered an explicit verdict:

Root Cause: Missing Config Parameter → Pod Crash Loop → Database Connection Leak

A service needed a configuration parameter during initialization. Without it, pods crashed on start. A deployment restart turned that into a self-perpetuating crash loop that exhausted database connections and cascaded into worker exhaustion, memory limits exceeded, and downstream service degradation.

The agents pieced the timeline together from Datadog metrics, Sentry exceptions, and Slack messages, and the orchestrator synthesized it into the cascade chain above.

The orchestrator went further. It provided the exact CLI commands to verify the missing parameter and confirm the diagnosis. It cross-referenced pod logs, metrics dashboards, and error tracking to establish when the parameter disappeared and why the cascade followed. Once it confirmed the root cause, it proposed mitigation strategies: which services to restart, in what order, and what to check after each step to confirm recovery.

The whole process — from "here's the Slack channel" to "here's the root cause and full cascade chain" — took about 10 minutes of wall clock time. A solo walkthrough of the same investigation, manually querying Datadog, Sentry, and cross-referencing Slack messages, would typically take 30–45 minutes.

Five takeaways from a real incident

You don't need a perfect prompt. I gave Claude almost no instructions, and it figured out a reasonable investigation structure on its own: splitting work into logical areas, assigning agents, and coordinating findings.

MCP integrations are the real prerequisite. The agents are only as useful as the data they can access. Without Datadog, Slack, and Sentry connected, they'd just be guessing. Agent teams parallelize the investigation; MCP makes the investigation possible.

It complements human investigation well. While the agents dug through logs and metrics, the rest of the team worked in the incident channel. The agents picked up context from Slack about what others were finding, and the human team benefited from the agents' systematic hypothesis elimination.

It's token hungry. Each agent is a separate Claude Code session with its own context window, so four parallel agents means roughly 4x the token cost of a single session. I use a Claude Code subscription with a monthly usage cap, so I don't pay per-token, but I'd estimate this investigation consumed the equivalent of $8–10 in API credits compared to ~$2–3 for a single-session walkthrough. Worth it when time matters during an active incident, but not something you'd run for every minor investigation.

The orchestrator's context stays clean. Because each agent works in its own context — processing raw logs, metrics, and API responses — the orchestrator only receives summarized findings. It reasons about the big picture without its context window filling up with noise. In a single-session investigation, you'd hit context limits fast when querying multiple observability tools.

Best for multi-hypothesis problems

Agent teams shine when a problem has multiple possible causes you can investigate independently. Production incidents are a natural fit, but the pattern applies to:

Performance investigations — one agent profiling the database, another checking application metrics, another reviewing recent changes
Security incident response — parallel analysis of access logs, code changes, and network traffic
Complex debugging — when you're not sure which layer of the stack is responsible

Break the problem into independent investigation areas, let agents explore them in parallel, and have the orchestrator synthesize the findings.

For simpler issues where the cause is likely in one place, a regular Claude Code session (or even a subagent) is more cost-effective. Agent teams add value when parallel exploration saves time.

Getting started

If you want to try this yourself:

Enable agent teams in your settings.json (the config snippet above)
Set up MCP integrations for the observability tools your team uses — this is the important part
Open a Claude Code session in your project and describe the problem, asking Claude to use a team of agents

The official documentation covers the full feature set, including display modes (in-process vs. split panes with tmux), how to interact with individual teammates, and how to control the team size.

Start with a low-stakes investigation to get a feel for how the coordination works before relying on it during a real incident. And if you already have MCP servers configured for your observability stack, you're most of the way there.

Moving Shell Secrets from .zshrc to 1Password CLI

contact@magarcia.io — Fri, 20 Feb 2026 00:00:00 GMT

I keep my shell config in a dotfiles repo so I can track changes in git. But a few API keys needed to be available at shell startup, and hardcoding them in .zshrc wasn't an option. So I loaded them from a separate .env file — one that stayed out of the repo.

The secrets were still plaintext, just in a different file. One wrong git add and they'd be in history. Then I thought: 1Password could handle this.

I moved the keys there and now load them at shell startup with op inject — one call, biometric unlock, no plaintext files anywhere.

The problem with `.env` and `.zshrc` secrets

Most developers store secrets one of two ways: a .env file or export statements scattered across shell configs. Either way, the values are plaintext and end up in backups, dotfiles repos, or shell history.

I wrote about secure credential storage for Node.js with cross-keychain. Shell environment variables are a different problem — they load before any application runs, and every process in your terminal needs access to them.

1Password CLI (op) solves this at the shell level.

Create a vault and enable biometric unlock

Install the 1Password CLI first, then set up two things before touching your shell config.

A vault for the secrets. I created a vault called development with multiple entries for each service. Each secret is the credentials field for that service. This gives you clean op://development/<SERVICE_NAME>/credentials URIs. You can organize it however you like, but I recommend a consistent structure for easy reference.

Biometric unlock. Without this, op prompts for your master password every time you open a terminal. Enable it in the 1Password desktop app under Settings → Developer → "Integrate with 1Password CLI". After that, op authenticates via Touch ID or your system keychain.

Split your shell into two files

With the vault in place, replace your .env file with two shell files. One for non-secret configuration that zsh sources automatically. One for secrets that op inject processes before loading.

`.zshenv` — plain configuration, no secrets

export EDITOR="nvim"
export LANG="en_US.UTF-8"
export PATH="$HOME/.local/bin:$PATH"
export NODE_ENV="development"

Zsh sources this file automatically on every shell invocation — interactive, non-interactive, scripts, SSH commands. No secrets here, ever.

`.zshsecrets` — secret references, not values

export GITHUB_TOKEN="{{ op://development/github/credentials }}"
export ANTHROPIC_API_KEY="{{ op://development/anthropic/credentials }}"
export NPM_TOKEN="{{ op://development/npm/credentials }}"

It's safe to commit to your dotfiles repo. Anyone reading it sees op:// URIs, not credentials.

`.zshrc` — wire it together

if command -v op &>/dev/null; then
  eval "$(op inject -i ~/.zshsecrets 2>/dev/null)" || echo "⚠ op: secrets not loaded"
fi

op inject reads the template, resolves every {{ op://... }} reference against your 1Password vault, and outputs the result with real values. eval executes the exports. If op isn't authenticated or unavailable, the shell still starts — you just won't have secrets loaded until you run op signin and re-source.

Why `op inject` over `op read`

Two ways to pull secrets from op. Per-variable reads:

export GITHUB_TOKEN="$(op read 'op://development/github/credentials' 2>/dev/null)"

Or template injection, which I use. The difference is performance. Each op read spawns a subprocess and makes an API call. With 5+ secrets, shell startup grows by 1–2 seconds. op inject resolves everything in a single call — around 200–400ms with biometric unlock enabled.

The cleanup you can't skip

After migrating, I did three things:

Removed every hardcoded secret from my shell files. A quick grep finds stragglers:

grep -rn 'export.*KEY\|export.*TOKEN\|export.*SECRET' ~/.zsh*

Scrubbed my dotfiles git history. If you ever committed secrets — even if you deleted them later — they're still in the history. git filter-repo or BFG Repo-Cleaner can purge them.

Rotated every token that had been in plaintext. Even if your secrets never touched a git repo, they may have lived in Time Machine backups or shell history. If you're not certain of your full exposure, rotate. It's not optional.

Tradeoffs

Startup latency. The op inject call adds 200–400ms to shell startup. Without biometric unlock, op prompts for your master password — painful if you open terminals frequently. Even with it enabled, the Touch ID prompt interrupts flow when opening terminals in quick succession.

Authentication gaps. If op isn't authenticated, your secrets won't load. You'll notice when a command fails, then run op signin and source ~/.zshrc. It's minor friction and a reasonable trade for no plaintext secrets.

No remote support. SSH sessions to remote machines won't have op. If you need secrets there, you'll need a different mechanism — op service accounts, or forwarding specific variables through SSH config.

A dotfiles repo you can make public

My dotfiles repo is now public-safe. Every secret lives in 1Password, a template file with op:// URIs loads them at startup, and Touch ID handles the rest.

If you need secrets on remote machines, the 1Password CLI docs cover service accounts and SSH agent forwarding.

Your Test Output Is Burning Tokens: Taming Verbose Reporters for AI Agents

contact@magarcia.io — Mon, 09 Feb 2026 00:00:00 GMT

Test runners like Jest and Vitest ship with reporters designed for humans watching terminals. Every file gets a line:

PASS src/components/Button.test.tsx
PASS src/components/Card.test.tsx
PASS src/components/Dialog.test.tsx
PASS src/components/Dropdown.test.tsx
PASS src/utils/format.test.ts
PASS src/utils/date.test.ts
... (200 more lines)
FAIL src/components/Nav.test.tsx
  ● Nav > renders active state

    Expected: "active"
    Received: "inactive"

For a developer at their terminal, scrolling green text reassures. But tests now run in two other contexts where that output costs more than it helps:

CI — nobody reads the log unless something fails. A red build forces you to scroll past hundreds of "PASS" lines to find the failure.
AI agents read every line of that output. Each "PASS" line consumes tokens, filling the context window with successful test output instead of the actual problem.

We hit this at Buffer. A 215-suite test run produced ~3,500 tokens of output, almost all "PASS" lines. Our AI agent spent more tokens reading test results than writing code. We tried adding --reporter=dot to our CLAUDE.md instructions, but the agent didn't always use it. The flag was a suggestion; we needed a guarantee.

Detect the Environment, Choose the Reporter

The fix: detect the environment in your test config and switch reporters automatically. No agent instructions required, no flags to remember.

Claude Code sets CLAUDECODE=1 in every shell it spawns. CI providers — GitHub Actions, GitLab CI, CircleCI, Travis CI, and Jenkins — all set CI=true. Your config reads these variables and picks the right reporter — deterministic regardless of how the agent invokes the test command.

Here's what we shipped at Buffer. CI and Claude Code each get their own reporter configuration; local development keeps the default.

For Jest, add the logic to jest.config.ts. The summary reporter prints a final count plus full details for any failures, with no per-file output. Jest's default summaryThreshold is 20, meaning it only prints failure details when more than 20 tests fail. Set it to 0 so every failure prints in full. In CI, you can pair it with a custom reporter that collects failures for GitHub PR comments:

const isCI = process.env.CI === "true";
const isClaude = process.env.CLAUDECODE === "1";

function getReporters() {
  if (isCI) {
    return [["summary", { summaryThreshold: 0 }], "jest-ci-reporter"];
  }
  if (isClaude) {
    return [["summary", { summaryThreshold: 0 }]];
  }
  return ["default"];
}

export default {
  reporters: getReporters(),
  // ... rest of your config
};

For Vitest, add it to vitest.config.ts. The dot reporter compresses each file to a single character — a dot for pass, an x for fail:

import { defineConfig } from "vitest/config";

const isCI = process.env.CI === "true";
const isClaude = process.env.CLAUDECODE === "1";

function getReporters() {
  if (isCI) {
    return ["dot", "ci-reporter"];
  }
  if (isClaude) {
    return ["dot"];
  }
  return ["default"];
}

export default defineConfig({
  test: {
    reporters: getReporters(),
    // ... rest of your config
  },
});

Both frameworks also accept reporter flags on the command line (--reporters for Jest, --reporter for Vitest). But relying on an AI agent to pass the right flag is probabilistic — the agent may forget or run a different test script that omits it. Environment variables make it deterministic.

The resulting matrix:

Environment	Jest Reporter	Vitest Reporter
Local dev	`default`	`default`
CI	`summary` + CI reporter	`dot` + CI reporter
Claude Code	`summary`	`dot`

What the Agent Sees

Before (default reporter, ~250 lines):

PASS src/components/Button.test.tsx (3 suites, 12 tests)
PASS src/components/Card.test.tsx (2 suites, 8 tests)
... (200+ more PASS lines)
FAIL src/components/Nav.test.tsx
  ● Nav > renders active state
    expect(received).toBe(expected)
    Expected: "active"
    Received: "inactive"

Test Suites: 1 failed, 214 passed, 215 total
Tests:       1 failed, 847 passed, 848 total

After (summary reporter, ~10 lines):

FAIL src/components/Nav.test.tsx
  ● Nav > renders active state
    expect(received).toBe(expected)
    Expected: "active"
    Received: "inactive"

Test Suites: 1 failed, 214 passed, 215 total
Tests:       1 failed, 847 passed, 848 total

Same failure details, 96% less output.

When all tests pass, the gap widens further. The default reporter prints every file name — 215 lines. The summary reporter prints two:

Test Suites: 215 passed, 215 total
Tests:       848 passed, 848 total

Trade-offs

You lose progress feedback. The summary reporter stays silent until the suite finishes. For long-running suites, the agent sees nothing until completion. In practice this has not mattered — AI agents do not need reassurance that the process is running.

Debugging intermittent failures gets harder. The default reporter's per-file timing helps identify slow or flaky tests. Use the verbose reporter when investigating flakiness.

The Same Fix Applies to Linters and Build Logs

Test reporters are one interface between your tools and whatever reads the output. Linters and type checkers have the same problem. Anywhere a tool produces verbose output that an AI agent consumes, you can detect the environment and switch to a compact format. Check your test config — if process.env.CI is set and you're still using the default reporter, you're paying for output nobody reads.

AI-Native Development: When Building Is Faster Than Planning

contact@magarcia.io — Sat, 24 Jan 2026 00:00:00 GMT

AI coding tools have inverted software economics. When a working prototype takes hours instead of weeks, the meetings to plan that prototype cost more than building it. This shift is creating a new category of AI-native companies that ship faster by building first and planning from working software.

We debated a feature for weeks. Then someone built it in a day with AI. When execution costs less than coordination, meetings become the bottleneck. This is reshaping how software teams work.

Prototyping is Now Fast and Cheap

We can build things faster and cheaper than ever. The second-order effects are profound. When execution is cheap, the entire apparatus we built around expensive execution—planning meetings, design reviews, sprint ceremonies, estimation rituals—starts to look like overhead.

A real example from Buffer: We had a project that got deprioritized. The feature had clear value. The backend logic already existed in a legacy service, but it needed to be migrated to our new systems—new APIs, new frontend, new patterns. The project kept slipping down the backlog because the estimated effort was significant: backend design proposals, architecture reviews, frontend designs, multiple rounds of feedback. We spent more time discussing whether to build it than it would have taken to just build it.

Then one of my coworkers decided to just do it. With Claude Code and a few iterations, he had a working prototype of the entire project in less than a day.

The prototype wasn't production-ready—it needed cleanup and proper tests—but it followed our patterns because we've taught our AI tools our codebase conventions. Refactoring working code that follows your architecture is far easier than rewriting something built on foreign patterns.

The math feels surreal. We spent days in meetings, drafting specifications, debating approaches—all to conclude "not now, too expensive." Meanwhile, the actual implementation took hours.

The Coordination Cost Now Exceeds the Execution Cost

We've crossed a threshold where coordination often costs more than execution. The meeting to discuss a feature—aligning stakeholders, gathering requirements, getting approval—can take longer than implementing that feature with AI assistance.

This inverts decades of software economics. Planning meetings existed because measure twice, cut once made sense when cutting was expensive. When cutting is cheap, measure once, cut, look at the result, cut again, and let the iteration loop serve as the planning process.

Build First, Then React

The old workflow: Spec → Approval → Build → Demo → Feedback → Iterate.

The emerging workflow is: Build → Demo → Feedback → Iterate. The spec emerges from the iterations.

This works because people struggle to articulate abstract wants. "What should the dashboard show?" produces vague answers. But "Is this dashboard useful?" produces specific, actionable feedback. Show someone a working prototype and ask "What's wrong with this?"—you'll get better requirements in three iterations than in ten hours of requirements meetings.

The prototype becomes the functional specification. You don't write a document describing what the software should do; you build software that does something and refine from there. The intent and constraints still get documented—but the mechanics are defined by working code.

Product and Design Need to Adapt Too

This shift isn't just about engineering. Product and design processes were also built around the assumption that implementation is expensive. When building was slow, it made sense to invest heavily in wireframes, mockups, and PRDs—proxies for the real thing that were cheaper to iterate on than actual software.

That calculus has changed. For interaction-heavy features—dashboards, forms, workflows—high-fidelity mockups often take longer than building the real thing. But this doesn't mean skipping design thinking entirely. A quick sketch or wireframe combined with rapid AI prototyping lets you explore possibilities faster than either approach alone.

Design isn't obsolete. Designers and product managers become critics and directors—reacting to working prototypes and guiding them toward good solutions rather than authoring specifications upfront.

What AI-Native Companies Look Like

Companies that embrace this shift don't just use AI—they become AI-native. Their processes, timelines, and expectations restructure around what's now possible.

Anthropic itself is the clearest example. Claude Code launched in February 2025 and became generally available that May. Six months later, it hit $1 billion in annualized revenue. But what's more striking is how they built on that momentum.

In January 2026, Anthropic shipped Cowork—a desktop agent that brings Claude Code's power to non-technical users. A team of four engineers built the entire product in roughly ten days, using Claude Code itself. The AI coding tool built its own non-technical sibling.

In a traditional company, a product like Cowork would take months of requirements gathering, design reviews, architecture proposals, and stakeholder alignment. Anthropic skipped all of that. They noticed users were forcing Claude Code to do non-coding tasks—vacation research, slide decks, email cleanup—and instead of debating whether to build a solution, they just built one.

But Anthropic builds AI. What about companies that just use it?

Sentry built their MCP server using Claude Code. The result is excellent—good enough to make me reconsider our own error tracking setup. When your integration is better because AI helped your engineers build it faster and iterate more, that's the competitive advantage in action.

Lovable reached $100 million in annual revenue eight months after launch. They hit $200 million ARR just four months later. With a team of around 45 people. The entire platform is powered by Claude, and when Claude 4 launched, their CEO posted that it "erased most of Lovable's errors." They're not building AI—they're building on it, and shipping at a pace that would have been impossible with traditional development cycles.

This is the competitive advantage of AI-native companies: they validate ideas with working software instead of slide decks, and iterate in days instead of quarters. The companies that figure this out will outpace those still running traditional planning cycles.

Build Fast, But Own What You Ship

There's a risk here worth naming: just because something is cheap to build doesn't mean it should exist. An expanding backlog isn't good—it can lead to feature bloat and unfocused products. The new discipline: "should this exist at all?"

This is the paradox of cheap execution: because we can build faster, we need sharper judgment about what to build. The old constraint—"this would take too long"—forced prioritization. Without it, we can efficiently build the wrong things. Build-first thinking requires more product discipline, not less.

Another discipline becomes more important: code review.

Vibe Coding Doesn't Belong in Production

"Vibe coding"—shipping AI-generated code you don't understand—is tempting when building is this fast. The prototype works, the tests pass, why not just merge it? Because someone has to be responsible when it breaks at 3am.

Every change to production should be reviewed by someone who will be on-call for that system. This wisdom predates AI. The difference is that AI makes it easier to produce code that works without understanding why it works. That's fine for exploration. It's dangerous for production.

This is about operational accountability, not gatekeeping. Non-engineers can absolutely use AI to build useful prototypes. But the constraint for production isn't technical ability—it's operational accountability. If you won't be paged when the system fails, your changes need review from someone who will be. The reviewer isn't blocking your contribution; they're accepting responsibility for it.

Engineers bring knowledge that AI doesn't replace: operational experience and the accumulated wisdom of having been paged at 3am for problems that looked fine in testing. AI makes engineers faster; it doesn't make them unnecessary.

This creates a natural quality gate that scales with AI acceleration. Build as fast as you want, prototype freely, but the path to production runs through someone who owns the consequences, and that ownership separates demos from deployments.

The Job Changes, But It Doesn't Disappear

What's shifting is the nature of the work. Less time writing boilerplate. More time understanding problems, directing AI, reviewing output, and making judgment calls. The developer becomes a code director.

This requires different skills. Clarity becomes primary—you need to articulate precise intent because AI executes instantly and literally. Vague input produces immediate, concrete wrong output. Debugging AI-generated code is a distinct skill: you're evaluating someone else's implementation choices, not reasoning through your own intentions.

Review becomes more important, not less. When anyone can generate plausible code, the ability to evaluate that code—to spot subtle bugs, understand performance implications, anticipate edge cases—is what separates working software from time bombs. The engineers who thrive will be those who can direct AI effectively and then critically assess what it produces.

The job has always been solving problems with software. AI strips away the pretense that it was about typing.

<br />

We're early in this shift. The tools are evolving rapidly, and we're all figuring out new workflows in real time. But the direction is clear: execution is cheap, coordination is expensive, and building is the new way to think.

The question is how fast you can adapt while still owning what you ship.

More on AI-assisted development: Learn techniques for building tools with AI, see how AI helped design the QWBP serverless WebRTC protocol, or explore writing Claude Code skills with Bun.

Breaking the QR Limit: The Discovery of a Serverless WebRTC Protocol

contact@magarcia.io — Mon, 19 Jan 2026 00:00:00 GMT

QWBP (QR-WebRTC Bootstrap Protocol) enables serverless peer-to-peer connections by compressing WebRTC signaling into QR codes. By designing a custom binary protocol that reduces SDP from 2,500 bytes to just 55 bytes, two devices can establish encrypted WebRTC connections by scanning each other's QR codes—with no signaling server required.

The reasonable man adapts himself to the world: the unreasonable one persists in trying to adapt the world to himself. Therefore all progress depends on the unreasonable man.

— George Bernard Shaw

I hardcoded passwords into production. I violated WebRTC best practices. I designed a custom binary protocol. Then I threw it all away when I discovered the real problem wasn't compression—it was physics.

This is the story of a Thursday evening, a Friday morning, and an unreasonable protocol that shouldn't exist.

The User Request I Couldn't Answer

January 2025. Palabreja, my daily Spanish word game, had grown over 30K monthly active players across Spain and Latin America. Built as a static Progressive Web App with zero backend—no database, no user accounts—everything lived in localStorage.

Then came the Bluesky notification:

"I'm buying a new phone. How can I keep my progress?"

Most developers answer: "Log into your account." I had no accounts, no server, no answer.

"Currently, there is no way."

That response gnawed at me. Players who upgraded phones would lose 2+ years of game progress. Statistics carefully maintained over months would vanish.

I refused to spin up a database to move a few kilobytes of JSON between two devices sitting next to each other. I wanted direct device-to-device transfer with zero servers.

Thursday Evening: The "Serverless" Lie

After work, I opened my laptop. WebRTC seemed perfect — peer-to-peer connections, browser-native APIs, no relay servers.

Every tutorial showed the same pattern:

const peer = new RTCPeerConnection();
const offer = await peer.createOffer();
await peer.setLocalDescription(offer);

// Send offer to other peer via... WebSocket server?
socket.send(JSON.stringify(offer));

There it was. Signaling requires a server.

Before two browsers connect peer-to-peer, they exchange Session Description Protocol (SDP) messages—offers and answers containing network information and encryption parameters. The WebRTC spec leaves signaling unspecified, assuming you'll use WebSockets, HTTP POST, or another server-mediated channel.

I had no server. I wanted no server.

QR codes. Display the offer as a QR code, scan it with the other phone, display the answer as another QR code, scan that. No server. Air-gapped communication using screens and cameras.

I built a prototype. The QR code appeared.

It was massive.

A Version 30+ QR code—over 130 modules per side—filled my phone screen. Dense, chaotic, unreadable.

Scanning results:

Good lighting, steady hands: 8 seconds, 60% success
Dim room: 15+ seconds, failed most attempts
Scratched lens: Never succeeded

My "instant sync" took longer than typing the data manually.

I printed the SDP to understand what I was fighting:

v=0
o=- 4682389562847392847 2 IN IP4 127.0.0.1
s=-
t=0 0
a=group:BUNDLE 0
a=extmap-allow-mixed
a=msid-semantic: WMS
m=application 9 UDP/DTLS/SCTP webrtc-datachannel
c=IN IP4 0.0.0.0
a=ice-ufrag:eP8j
a=ice-pwd:3K9m...
a=ice-options:trickle
a=fingerprint:sha-256 E7:3B:38:46:1A:5D:88:B0:...
a=setup:actpass
a=mid:0
a=sctp-port:5000
a=max-message-size:262144
a=candidate:1 1 udp 2122260223 192.168.1.100 54321 typ host
... (20 more candidate lines)

2,487 bytes. Session Description Protocol[^1] dates to 1998, designed for VoIP where endpoints negotiate video codecs, audio sampling rates, bandwidth constraints. I controlled both endpoints. 90% of this data was ceremony for a negotiation that would never happen.

[^1]: RFC 8866 - SDP: Session Description Protocol, https://datatracker.ietf.org/doc/html/rfc8866

The question became: "Which SDP fields are actually required?"

The Path I Didn't Take

Prior work exists: animated QR sequences that flash frames until the scanner captures all parts[^2][^3], and fountain codes (TXQR[^4]) that tolerate missed frames. These achieve ~9 KB/s under ideal conditions but require holding steady for 10+ seconds—acceptable for crypto wallet signing, but too ceremonial for casual use.

The fork in the road: Animated QRs solve the transport problem—"how do I move 2.5KB through a QR code?" I needed to solve the meaning problem—"do I need 2.5KB?"

I looked at existing libraries like sdp-compact, which strip whitespace and apply standard compression. But they still hit the "Generic Compression Limit"—the overhead of headers and Base64 encoding often outweighed the savings for small payloads.

[^2]: Franklin Ta, "Serverless WebRTC using QR codes" (2014), https://franklinta.com/2014/10/19/serverless-webrtc-using-qr-codes/

[^3]: webrtc-via-qr GitHub repository, https://github.com/Qivex/webrtc-via-qr

[^4]: TXQR: Transfer via QR with fountain codes, https://github.com/divan/txqr

The Hack That Worked

Analyzing the SDP structure revealed what was actually needed: ICE credentials, DTLS fingerprint, setup value, and ICE candidates. Everything else—session description, bundling info, SCTP parameters—could be hardcoded on both ends.

Quick glossary for the uninitiated:

ICE (Interactive Connectivity Establishment): The protocol that figures out how two devices can reach each other across networks, firewalls, and NATs
ICE candidates: Network addresses (IP + port) where a device can potentially be reached
DTLS (Datagram TLS): Encryption layer for WebRTC—like HTTPS but for real-time data
DTLS fingerprint: A hash of the device's security certificate, used to verify you're talking to the right peer

First insight: Hardcode the ICE credentials.

a=ice-ufrag:eP8j
a=ice-pwd:3K9m...

These are the ICE "username fragment" (ufrag) and password—random strings that peers exchange to authenticate connectivity checks. 50 bytes of high-entropy data—impossible to compress. I asked: "Can I hardcode these? What breaks?"

Digging into RFC 5245 revealed the answer. ICE credentials authenticate connectivity checks between peers, but the real security comes from the DTLS fingerprint[^5]—a SHA-256 hash of the device's TLS certificate. An attacker with ICE credentials but the wrong certificate cannot connect; the DTLS handshake fails.

[^5]: RFC 8827 - WebRTC Security Architecture, https://datatracker.ietf.org/doc/html/rfc8827

I hardcoded them:

const ICE_UFRAG = "palabreja";
const ICE_PWD = "xK9...........cB0";

Saved: 50 bytes.

Second insight: Filter candidates.

Browsers emit 15-30 ICE candidates—every network interface: Wi-Fi, VPN, Docker, link-local IPv6. Most fail or connect slowly. But my first test with a single candidate failed—the VPN interface appeared first, hiding the Wi-Fi address that could actually connect.

I raised the limit to 3 "host" candidates (local network addresses) plus 1 "srflx" (server-reflexive) candidate. The srflx candidate is your public IP address as seen from the internet, discovered by asking a STUN server "what's my IP?" This handles the case where devices are on different networks.

Saved: 1,200+ bytes.

Third insight: Binary protocol.

I stared at the minified JSON I was transmitting. Brackets. Quotes. Key names. The string "type" appeared in every message—5 bytes to encode something that could only ever be "offer" or "answer". The fingerprint was a 95-character hex string with colons, but underneath it was just 32 bytes of raw data.

JSON is designed for interoperability—human-readable, self-describing, universally parseable. But I controlled both endpoints and wrote encoder and decoder. Nothing needed to be human-readable or self-describing.

I remembered studying low-level networking—how TCP headers pack flags, sequence numbers, and ports into fixed positions. No field names. No delimiters. Just bytes at known offsets. What if I designed a packet format instead of a JSON object?

Strip everything constant. Keep only what's dynamic:

┌────────┬─────────────────────┬──────────────────────────────┐
│ Byte 0 │ Bytes 1-32          │ Bytes 33+                    │
├────────┼─────────────────────┼──────────────────────────────┤
│ Type   │ DTLS Fingerprint    │ ICE Candidates (packed)      │
│ 0=offer│ SHA-256 hash        │ "h|u|192.168.1.5|54321|..."  │
└────────┴─────────────────────┴──────────────────────────────┘

One byte for type instead of "type":"offer". 32 raw bytes for the fingerprint instead of 95 ASCII characters. No brackets, no quotes, no field names.

But I wasn't done. The candidates were still strings: "h|u|192.168.1.5|54321". That IP address alone is 13 characters—but an IPv4 address is just 4 bytes. Why three ASCII characters for 192 when 0xC0 suffices?

I pushed further. Each candidate became a fixed-layout binary structure:

┌─────────┬────────────────┬────────┐
│ Flags   │ IP Address     │ Port   │
│ (1B)    │ (4B or 16B)    │ (2B)   │
└─────────┴────────────────┴────────┘

Flags byte (bitmask):
  Bits 0-1: Address family (00=IPv4, 01=IPv6, 10=reserved*)
  Bit 2:    Protocol (0=UDP, 1=TCP)
  Bit 3:    Candidate type (0=host, 1=srflx)
  Bits 4-5: TCP type[^6] (if TCP): 00=passive, 01=active, 10=so
  Bits 6-7: Reserved

*The reserved slot becomes important later—browser privacy features require it.

[^6]: RFC 6544 - TCP Candidates with Interactive Connectivity Establishment (ICE), https://datatracker.ietf.org/doc/html/rfc6544

The string "h|u|192.168.1.5|54321" (21 characters) became 7 bytes. A 66% reduction on candidate data alone—and candidates were the bulk of the payload.

The full packet structure:

┌─────────┬─────────────────┬─────────────────────────────────┐
│ Field   │ Size            │ Description                     │
├─────────┼─────────────────┼─────────────────────────────────┤
│ Type    │ 1 byte          │ 0x00 = offer, 0x01 = answer     │
│ FP      │ 32 bytes        │ DTLS fingerprint (SHA-256)      │
│ Cand 1  │ 7 bytes (IPv4)  │ Flags + IP + Port               │
│         │ 19 bytes (IPv6) │                                 │
│ Cand 2  │ 7-19 bytes      │ (repeat until end of payload)   │
│ ...     │                 │                                 │
└─────────┴─────────────────┴─────────────────────────────────┘

Typical payload: 1 + 32 + (4 × 7) = 61 bytes (4 IPv4 candidates)
Maximum payload: 1 + 32 + (4 × 19) = 109 bytes (4 IPv6 candidates)

Fourth insight: DEFLATE compression.

I applied fflate (DEFLATE level 9) to the binary payload:

Before compression: 91 bytes
After compression:  44 bytes
After base64:       60 bytes

Result: 2,487 bytes → 60 bytes. 97.6% reduction.

The QR codes scanned quickly—under a second in my tests. I had solved the compression problem.

But something bothered me. Hardcoded passwords felt wrong. I'd made progress, but this was still a hack, not a protocol.

Refining the Hack

The hardcoded credentials nagged at me. It's a JavaScript website—the source code is readable. Anyone could open DevTools, find the ICE password, and... well, what exactly? The real encryption happens in the DTLS handshake, authenticated by the fingerprint. ICE credentials are just for routing verification. Not critical.

Still, it bothered me. Having the source code shouldn't give you the keys. Then I realized: there's already something unique per session. The DTLS fingerprint—a SHA-256 hash of each device's certificate—is already in the QR code. What if I derived the ICE credentials from that?

Discovery: Derive credentials, don't hardcode them.

The solution: HKDF-SHA256[^7], a standard key derivation function. The key insight: each peer derives its own credentials from its own fingerprint—not shared credentials from a common secret.

How it works:

Peer A derives ufrag_A from Fingerprint_A using HKDF
Peer B derives ufrag_B from Fingerprint_B using HKDF
QR codes exchange both fingerprints
Each peer can locally compute the other's expected credentials for validation
ICE connectivity checks use standard username format: ufrag_remote:ufrag_local[^8]

HKDF parameters (for implementers):

// Salt is empty because the entropy source (DTLS certificate) is already
// high-entropy and ephemeral—no additional randomness needed
const salt = new Uint8Array(0);
const ufragInfo = new TextEncoder().encode("QWBP-ICE-UFRAG-v1");
const pwdInfo = new TextEncoder().encode("QWBP-ICE-PWD-v1");

// Derive 4 bytes for ufrag, encode as base64url (yields 6 chars, min is 4)
const ufragBytes = await hkdf(fingerprint, salt, ufragInfo, 4);
const ufrag = base64url(ufragBytes);

// Derive 18 bytes for pwd, encode as base64url (yields 24 chars, min is 22)
const pwdBytes = await hkdf(fingerprint, salt, pwdInfo, 18);
const pwd = base64url(pwdBytes);

RFC 8839 requires ufrag ≥4 chars, pwd ≥22 chars, using [A-Za-z0-9+/]. Base64url satisfies this.

This satisfies RFC 8839's entropy requirement[^9]—the randomness comes from the ephemeral DTLS certificate, not from HKDF itself. This avoids shipping secrets in code and guarantees per-session uniqueness as long as each connection attempt generates a fresh certificate.

Now the source code alone yields nothing. You need visual access to the specific QR code to know that session's credentials. The security boundary shifted from "secret in code" to "physical proximity required."

[^7]: RFC 5869 - HMAC-based Extract-and-Expand Key Derivation Function (HKDF), https://datatracker.ietf.org/doc/html/rfc5869

[^8]: RFC 8445, Section 7.2.2 - Forming Credentials, https://datatracker.ietf.org/doc/html/rfc8445#section-7.2.2

[^9]: RFC 8839, Section 5.4 - ICE Password, https://datatracker.ietf.org/doc/html/rfc8839#section-5.4

Discovery: The compression paradox.

Testing with real Chrome and Firefox SDP data revealed a surprising result. The binary payload—already stripped of redundancy—was high-entropy. Running DEFLATE on it increased the size:

Binary payload:     61 bytes
After compression:  83 bytes
After base64:       112 bytes

Compression header overhead exceeded entropy gains. For optimized binary data, skip compression entirely.

Discovery: Base64 is a tax.

QR codes support raw binary (Byte mode, ISO 8859-1). Most JavaScript QR libraries accept Uint8Array directly. Base64 adds 37% overhead for no benefit.

With base64:    84 bytes → QR v5
Without base64: 61 bytes → QR v4

I had been paying a 37% size penalty because I assumed QR codes needed text encoding. They don't.

The hack was becoming a protocol. But I still hadn't addressed the fundamental problem.

Friday Morning: The "Return Trip" Problem

I had optimized the offer. But WebRTC requires bidirectional exchange—the receiver must send an answer back.

In a serverless PWA environment:

Device A cannot listen for incoming connections (browsers are clients, not servers)
Unsolicited DTLS packets from Device B are dropped
ICE authentication prevents connectivity without both peers knowing each other's credentials

You cannot establish a WebRTC connection with a single unidirectional scan.

I explored alternatives:

Bluetooth: Web Bluetooth API cannot act as a peripheral (server role). PWAs can only be central devices, meaning both phones would try to connect, neither would listen.
NFC: Web NFC cannot emulate tags. Both phones would try to read, neither would write.
Audio data transfer: Requires microphone permission. Unreliable in noisy environments. Users would rightfully be suspicious.
Wi-Fi Direct: No Web API exists.

Every alternative either demanded a server or required permissions that would spook users.

The only universal, permission-friendly I/O channel available to PWAs is bidirectional QR code scanning.

I called it the "QR Tango":

Device A displays QR code
Device B scans it, then displays its QR code
Device A scans Device B's QR code
Connection establishes

But this introduced a new problem.

The Glare Problem

If both users press "Connect" simultaneously, both phones generate offers. WebRTC's state machine crashes when it receives an offer while in the "have-local-offer" state.

The obvious solution: designate one device as "sender" and one as "receiver." Consider the UX: Most Palabreja players are 50+ years old. They know how to scan a QR code—that's intuitive. But explaining "first you press Send, then they scan your code, then they press Receive, then you scan their code, and it has to be in that order"? That's not intuitive. That's a support nightmare. It felt broken.

I wanted one button: "Connect." Both users press it. Both scan. It just works.

But that reintroduces the technical problem. I needed role assignment. And if roles are encoded in the QR code, you get race conditions:

User A displays "Offer" QR
User B displays "Offer" QR
Neither can proceed

Or worse—"stale QRs":

User A displays "Offer" QR
User B scans it, role updates to "Answerer"
Screen refreshes with "Answer" QR
User A scans the old cached QR before it updates

I kept asking: how do I remove the offer/answer byte from the protocol header? Every approach led to the same problem—the protocol needs to know who acts as offerer and who acts as answerer. It seemed fundamental to WebRTC's state machine.

Then it clicked. I'd already solved a similar problem with ICE credentials—deriving them from data already in the payload instead of transmitting them separately. What if I did the same for role assignment?

The fingerprints. They're unique per device. They're already in the QR code. And crucially: two different fingerprints are never equal. One is always higher than the other when compared byte-by-byte. If they are equal, you're scanning your own QR code—an error the protocol should catch anyway.

The breakthrough: Symmetric identity exchange.

Instead of encoding "Offer" or "Answer," both QR codes contain only identity (fingerprint) and location (IP addresses)—like business cards. After both scans complete, each device has both fingerprints. Roles are assigned deterministically by comparison:

if (localFingerprint > remoteFingerprint) {
  // Higher fingerprint ID → Offerer
  role = "OFFERER";
} else if (localFingerprint < remoteFingerprint) {
  // Lower fingerprint ID → Answerer
  role = "ANSWERER";
} else {
  // Same fingerprint → Loopback error
  throw new Error("Cannot connect to self");
}

Simple byte comparison. Deterministic. No race conditions. No stale QRs.

The offerer synthesizes a "fake" SDP answer locally using the answerer's fingerprint and candidates. This satisfies the browser's state machine without additional data transmission.

Result: Role-independent QR codes. Press "Connect," display your card, scan theirs. Order doesn't matter.

The Browser State Paradox

Solving the glare problem introduced a subtle bug. To generate the QR code, both devices must first gather candidates, which puts both browsers into the "Have Local Offer" state.

If the protocol decides you are the Answerer, you have a problem: you can't accept an Offer if you already have an Offer.

The naive solution is to destroy the WebRTC connection and start fresh. But you can't. The QR code currently displayed on your screen encodes specific network ports (e.g., port 54321). If you destroy the connection object, the OS closes those ports. The map you just gave your partner becomes a dead end.

The solution is Signaling Rollback. We use setLocalDescription({type: 'rollback'}) to reset the signaling state to stable while keeping the underlying ICE transport—and those precious ports—alive. It allows the software to change its mind about who is calling whom without the physics of the network layer noticing.

Reconstructing the SDP

Both peers now have everything needed to synthesize a complete SDP locally:

From the QR code:

DTLS fingerprint (32 bytes)
ICE candidates (3-4 packed binary structures)
Remote device identity

Generated locally:

ICE credentials (derived from fingerprints via HKDF)
Role assignment (fingerprint comparison)
Session metadata (timestamps, IDs)

The offerer—who already has a valid local offer pending from the gathering phase—uses the scanned data to synthesize a fake Remote Answer. This tricks the browser into thinking a standard negotiation took place without actually receiving an SDP answer packet.

The answerer does the inverse: it performs a signaling rollback (telling the browser "forget that offer I just made you generate, but keep the network ports open"), synthesizes a fake Remote Offer from the QR data, and then generates a real local Answer to complete the connection.

The browser sees a normal WebRTC negotiation—it's unaware the SDP came from a QR code rather than a signaling server.

The mDNS Complication

While reviewing the protocol, one last obstacle emerged. Modern browsers hide local IP addresses behind mDNS hostnames for privacy—instead of 192.168.1.5, the browser reports something like b124-98a7-c3d2-f1e0.local.

The problem: QWBP's binary format expects raw IPs (4 bytes for IPv4, 16 for IPv6). A 42-character mDNS hostname doesn't fit.

The solution is surprisingly elegant—and standards-compliant. WebRTC browser implementations (following the IETF mDNS draft[^10]) mandate that mDNS hostnames consist of "a version 4 UUID as defined in RFC 4122, followed by '.local'".

A UUID is 128 bits—exactly the size of an IPv6 address. The protocol doesn't need to change the binary format; it just needs to expand the IP version flag from 1 bit to 2 bits, encoding three states:

00 = IPv4 (4 bytes)
01 = IPv6 (16 bytes)
10 = mDNS UUID (16 bytes, packed as raw bytes)

This isn't a workaround—it's compliance optimization. Modern browsers (Chrome, Safari) use this exact format for privacy[^11].

[^10]: draft-ietf-mmusic-mdns-ice-candidates-03, Section 3.1.1, https://datatracker.ietf.org/doc/html/draft-ietf-mmusic-mdns-ice-candidates-03#section-3.1.1

[^11]: RFC 4122 - A Universally Unique IDentifier (UUID) URN Namespace, https://datatracker.ietf.org/doc/html/rfc4122

However, mDNS resolution between devices that haven't exchanged packets can be slow or fail entirely. For the initial bootstrap, raw IPs are more reliable. On Android and Chrome, requesting camera permission (needed anyway for QR scanning) often causes the browser to reveal the raw local IP alongside the mDNS name. Safari on iOS is stricter—it only provides mDNS hostnames, making the UUID packing essential rather than optional.

The protocol was functionally complete. But was it secure?

Threat Model: The Optical Channel

QWBP's security relies on the optical channel—the screen displaying the QR code.

What it protects against:

Remote attackers: Cannot participate without visual access to both devices
Source code inspection: Knowing the implementation doesn't reveal session keys
Replay attacks: Ephemeral keys (DTLS certificates generated per-session) expire after connection
MITM attacks: DTLS fingerprint verification[^12] prevents impersonation

What it assumes:

Physical proximity is the authentication factor. If an attacker can photograph both QR codes, they can potentially intercept the session (though they'd need to be on the same network segment and win the race to establish connection first).
Short-lived sessions: Keys are valid only for the current connection attempt (~30 seconds).
Visual confirmation: Users can see who they're connecting to (same room).

Optional: Short Authentication String (SAS): After connection, display a short code (e.g., 4 words or 6 digits) derived from both fingerprints. Users verbally confirm the code matches on both screens—this catches active MITM attacks where an attacker substitutes their own QR. ZRTP[^13] pioneered this pattern for voice calls; it applies equally to QWBP.

[^12]: RFC 8122, Section 5 - Fingerprint Attribute, https://datatracker.ietf.org/doc/html/rfc8122#section-5

[^13]: RFC 6189 - ZRTP: Media Path Key Agreement for Unicast Secure RTP, Section 4.3 (SAS), https://datatracker.ietf.org/doc/html/rfc6189#section-4.3

The Bigger Picture: A Protocol, Not a Hack

Then it hit me. I'd been thinking too small.

A full WebRTC video call requires negotiating codecs, resolutions, bandwidth constraints. A typical Chrome video SDP with audio, video (VP8, VP9, H.264, AV1, H.265), and DataChannel weighs in at 6,255 bytes—sometimes more with all the codec options. No QR code can hold that. Version 40, the largest possible, maxes out at 2,953 bytes. A video SDP exceeds the maximum possible QR capacity by over 3KB.

But the DataChannel SDP I'd been compressing? That's just the bootstrap. It establishes a minimal encrypted pipe between two devices. Once that pipe exists, you can send anything through it—including a 6KB video SDP.

I wasn't building a game sync feature. I was building a signaling protocol.

Two-stage architecture:

┌─────────────────────────────────────────────────────────────────┐
│  Layer 0: QR Bootstrap                                          │
│  ───────────────────────                                        │
│  • 55-100 bytes binary payload                                  │
│  • Fits in QR Version 4-5 (33-37 modules)                       │
│  • Establishes encrypted DataChannel                            │
│  • Scans in under 1 second (in my testing)                      │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  Layer 1: Application Protocol                                  │
│  ─────────────────────────────                                  │
│  • No size constraints                                          │
│  • Exchange full video/audio SDPs (6KB+)                        │
│  • Stream files of any size                                     │
│  • Run any application protocol                                 │
└─────────────────────────────────────────────────────────────────┘

This two-stage architecture—small bootstrap leading to full capability—follows the same pattern as Wi-Fi Easy Connect (DPP)[^14], which uses a QR code to bootstrap secure IoT provisioning.

[^14]: Wi-Fi Alliance, "Wi-Fi Easy Connect Specification v3.0", https://www.wi-fi.org/discover-wi-fi/wi-fi-easy-connect

The implications went beyond Palabreja:

Video calls without servers: Scan a QR code, establish the bootstrap channel, negotiate full video through it. (The irony of setting up a video call face-to-face is not lost on me.)
File sharing: The DataChannel can stream files of any size. A 55-byte QR becomes a serverless AirDrop.
Device pairing: IoT devices, smart home setup, any scenario where two devices need to establish trust and a secure channel.
Multiplayer games: Bootstrap a mesh network between players in the same room. No game server needed for local multiplayer.

A 55-100 byte bootstrap (a 99.12% reduction from the 6,255-byte video SDP) unlocks full video negotiation, which unlocks unlimited bandwidth. A 4K video call, initiated by scanning a QR code in dim lighting.

This wasn't a hack anymore. It was a protocol worth naming.

I called it the QR-WebRTC Bootstrap Protocol (QWBP) — pronounced "cue-web-pee" (/kjuː wɛb piː/). Claude suggested the name; I liked it.

Why Not Animated QRs?

A fair question: if fountain codes can reliably transfer 9KB through animated QRs, why shrink the protocol?

Three reasons:

1. Latency Kills Manual Signaling

Manual signaling fights browser ICE timers. Firefox's media.peerconnection.ice.trickle_grace_period (default: 5000ms) can mark gathering failed if it doesn't receive expected candidates in time. QWBP sidesteps this by completing ICE gathering before displaying the QR—but users still need to scan within a reasonable window.

TXQR can transfer 9KB in ~1 second under ideal conditions, but real-world performance degrades:

Poor lighting: 15+ seconds
User fumbling with camera permissions: 20+ seconds
Missed frames requiring rescan: restart from zero

By reducing payload to 55 bytes (Version 4 QR), scan time drops to sub-500ms—safely inside browser timeout windows.

2. UX Ceremony Tax

Animated QRs require:

Holding phone perfectly still
Waiting for sequence completion
Two-handed operation or phone stand
Understanding what "3 of 12 frames captured" means

Static QRs require:

Point camera
Done

For motivated users (crypto transactions), ceremony is acceptable. For casual users (game sync), it's a support nightmare.

3. Semantic Compression Beats Transport Compression

Animated QRs compress at the transport layer—fountain codes, LZMA, base32 encoding.

QWBP compresses at the semantic layer—understanding what ICE candidates mean achieves 97.79% reduction.

Approach	Technique	Data Size	Scan Time
Franklin Ta (2014)	LZMA + animated	~1000 bytes → 10 QR codes	10-15 sec
TXQR	Fountain codes	9KB → 30 QR codes	1-10 sec
BBQr	Chunking + base32	3KB → 12 QR codes	5-12 sec
QWBP	Binary protocol	55 bytes → 1 QR code	<0.5 sec

When you control both endpoints, domain knowledge is a compression algorithm.

The Final Protocol

By Friday afternoon, I had completed the QR-WebRTC Bootstrap Protocol (QWBP) v1.0.0.

What QWBP is (and isn't):

DataChannel-only bootstrap (DataChannel is WebRTC's raw data pipe, separate from audio/video)—not a general SDP replacement

Optimized for two devices in physical proximity with controlled scanner/encoder

"Serverless" on LAN; requires STUN/TURN servers for cross-network scenarios (explained later)

Not designed for video/audio negotiation, mesh networks, or untrusted environments

The packet structure evolved from my Thursday prototype. I added a Magic Byte (0x51 = 'Q') for protocol identification—so scanning a restaurant menu QR fails fast instead of crashing—and a Version field for future compatibility:

QWBP v1 Packet Structure:

┌───────────┬─────────────┬──────────────────────┬────────────────────┐
│ Magic (1B)│ Version (1B)│ Fingerprint (32B)    │ Candidates (Var)   │
│ 0x51 'Q'  │ Version:3b  │ SHA-256 DTLS         │ Binary-packed IPs  │
│           │ Reserved:5b │ (32 raw bytes)       │ (7B IPv4, 19B IPv6)│
└───────────┴─────────────┴──────────────────────┴────────────────────┘

Typical size: 55-100 bytes → QR Version 4-5 (33-37 modules)

Connection flow:

Both peers generate DTLS certificate and gather ICE candidates
Both encode identity + location → display QR code
Peer A scans Peer B's QR (order irrelevant)
Peer B scans Peer A's QR
Both compare fingerprints → determine roles
Both synthesize appropriate SDP locally
DTLS handshake + ICE connectivity check
DataChannel established

ICE Gathering: Unlike standard WebRTC (which uses "Trickle ICE" to send candidates as they're discovered), QWBP waits for complete ICE gathering before encoding the QR. Implementation must wait for iceGatheringState: 'complete'. This adds 1-2 seconds of latency but ensures the QR contains all candidates needed for connection—better than fast QR generation with failed scans.

Final optimization decisions:

Decision	Rationale
Derive ICE credentials via HKDF	Per-session uniqueness without transmission overhead.
Skip compression	High-entropy binary data expands under DEFLATE.
Skip base64	QR codes support raw binary natively.
3 host + 1 srflx candidates	Handles VPN, tethering, and cross-network scenarios.
Symmetric identity exchange	Eliminates race conditions and role assignment complexity.
mDNS as UUID in IPv6 slot	Preserves binary format while supporting browser privacy features.

The Compression Journey

Stage	Bytes	QR Version	Scan Time
Standard WebRTC SDP	2,487	v34-40	10+ sec
Remove boilerplate	820	v20	6 sec
Hardcode credentials	770	v20	6 sec
Filter candidates	210	v9	3 sec
Binary format	91	v5	1 sec
Skip base64	55-100	v4-5	<0.5 sec

97.79% reduction. In my testing, Version 4 QR codes scanned in under a second across varied lighting conditions—a significant improvement over the v30+ codes I started with.

The QR codes use Error Correction Level L (7% recovery). For binary data displayed on screens—high contrast, no physical damage—Level L minimizes size while remaining scannable. Higher levels (M at 15%, H at 30%) would push v4 codes back to v5-6, defeating the optimization work.

A Note on "Serverless"

The protocol works without servers on the same local network—both devices use their LAN IP addresses (host candidates) and connect directly.

For cross-network scenarios (one device on Wi-Fi, another on 5G), you need a STUN server[^15] to discover public IPs. STUN (Session Traversal Utilities for NAT) is simple: your device asks "what's my public IP?" and the server responds. Public STUN servers like stun:stun.l.google.com:19302 are free, stateless, and don't relay your data—they just answer that one question. You don't deploy or maintain them.

[^15]: RFC 8489 - Session Traversal Utilities for NAT (STUN), https://datatracker.ietf.org/doc/html/rfc8489

The QR Tango solves single symmetric NAT. This was a pleasant discovery. NAT (Network Address Translation) is how your router lets multiple devices share one public IP—but it creates problems for peer-to-peer connections because devices can't directly reach each other. Symmetric NAT[^16] is the strictest type—it won't accept incoming packets until the device sends one first. Traditional WebRTC signaling struggles here because one side waits for the other.

But with QWBP, both devices have complete connection information from the QR codes. Both can fire packets simultaneously. When Device A sends to Device B, Device A's NAT opens a "hole" for return traffic. Device B does the same. The packets cross in flight, each NAT sees outgoing traffic, and both allow the responses through. This is called "simultaneous open" or hole punching[^17]—and it works because neither device is waiting for the other.

For symmetric NAT on both sides, a TURN relay is still needed. TURN (Traversal Using Relays around NAT) is a server that both devices connect to, which then forwards traffic between them—a last resort when direct connection is impossible. Neither peer can predict what port their NAT will assign for the other destination—it's a deadlock that even simultaneous transmission can't solve. This affects maybe 10% of connections, mostly on enterprise WiFi and carrier-grade NAT. An acknowledged limitation.

[^16]: RFC 4787 - Network Address Translation (NAT) Behavioral Requirements for Unicast UDP, https://datatracker.ietf.org/doc/html/rfc4787

[^17]: RFC 5128 - State of Peer-to-Peer (P2P) Communication across Network Address Translators (NATs), https://datatracker.ietf.org/doc/html/rfc5128

When It Fails

QWBP handles most same-network scenarios, but some failures are expected:

Same Wi-Fi but won't connect:

VPN active on one device → try disabling VPN or use mobile hotspot
Enterprise firewall blocking peer traffic → TURN relay required
iOS local network permission denied → check Settings > Privacy > Local Network

QR scanned but nothing happens:

Scanned a menu/URL QR → magic byte validation rejects non-QWBP codes
Session expired → the 30-second timeout passed; regenerate QR and try again

Connection drops immediately:

DTLS handshake failed → certificates may have regenerated; restart both devices

Glare still possible? No. Fingerprint comparison deterministically assigns roles after both scans complete. If both devices compute the same role (only possible with identical fingerprints = scanning yourself), the protocol throws an error.

What I Learned

Semantic compression beats generic compression. Understanding what data is actually needed achieves 97% reduction. DEFLATE on the original SDP: 60% reduction. Domain knowledge: 97.79%.

"Best practices" assume interoperability. ICE credentials exist because generic WebRTC implementations can't trust the signaling channel. When you control both endpoints and authenticate via QR scan, the threat model changes.

Physics constrains design. I spent Thursday evening optimizing compression before realizing the return trip—not payload size—was the real problem. Bidirectional QR scanning wasn't a workaround; it was the only viable serverless channel.

Dialogue beats solitary genius. The protocol emerged from conversation, not isolation. More on this below.

What's Next

The protocol works for any WebRTC project needing QR-based signaling. The techniques apply to any protocol where you control both endpoints.

I've published a formal specification, a TypeScript library, and a live demo:

QWBP Specification — The complete protocol reference
qwbp on npm — Drop-in TypeScript/JavaScript library
Live Demo — Try it between two devices right now

If you build something with QWBP, I'd love to hear about it.

Rubber Ducking with a Robot

I should be transparent about how this protocol came together: I didn't design it alone. I designed it in conversation with Claude, Anthropic's AI assistant.

It started with a problem: "I have a PWA with no backend, and a user wants to sync their game progress to a new phone." I shared this with Claude, and we started exploring options. WebRTC looked promising but the signaling overhead seemed insurmountable. Over the course of several sessions—Thursday evening into Friday morning—the conversation evolved from "this is impossible" to "wait, what if we just..."

What AI did well:

Research at conversation speed. When I asked "can I hardcode ICE credentials?", Claude pulled the relevant RFC sections and explained the security implications in seconds. When I wondered if Web Bluetooth could work, Claude systematically eliminated it by citing specific browser API limitations. This kind of RFC-diving and compatibility research would have taken me hours or days.
Provided resistance to push against. Claude kept insisting the "offer/answer" distinction was fundamental to WebRTC—you need an offer, you need an answer, that's how it works. That resistance forced me to articulate why I thought we could do better, until I asked: "What if we infer the roles from something already in the QR?" That question—mine, born from frustration with the constraint—led to the symmetric fingerprint comparison that eliminated race conditions. Sometimes AI is most useful when it's wrong.
Validated security decisions. When I proposed deriving ICE credentials from the DTLS fingerprint, I wasn't sure if I was introducing vulnerabilities. Claude analyzed the threat model and confirmed the real security boundary is the DTLS handshake, not the ICE layer—the change was safe.
Caught things I missed. The "compression paradox" (DEFLATE making the payload larger) emerged when Claude ran the actual numbers. I would have assumed compression always helps.

What AI didn't do:

Make architectural decisions. Every design choice—the binary format, the QR Tango UX, the candidate limits—came from me asking "what if?" and Claude helping me evaluate the tradeoffs. The AI never said "here's the design." It said "here's what happens if you do X."
Replace domain intuition. Knowing that a 55-byte payload "feels" right for QR codes, or that users over 50 won't tolerate animated QR sequences—that came from building products, not from prompting.

The honest assessment:

Without AI, I probably would have given up after a few hours. This wasn't a critical problem—I could have told the user "sorry, this is not possible" and moved on. No one was demanding a solution. But because each question got an answer in seconds instead of hours, I kept going. Each small breakthrough made the next question worth asking. The momentum carried me through problems I would have abandoned.

Reading RFCs, testing browser quirks, validating security assumptions—weeks of unglamorous work. With AI, I compressed it into a day. Not because AI is smarter, but because it's faster at the boring parts, and that speed changes what feels worth attempting.

The experience felt like pair programming with someone who has read every RFC but has no opinions. I drove the architecture. Claude drove the research. When I got stuck, I'd describe the problem out loud (rubber ducking), and Claude would either confirm my instinct or point out something I'd missed.

Appendix: Quick Reference

For the complete specification, see the QWBP Specification. Here's a quick reference for the binary format.

Packet Structure

┌───────────┬─────────────┬──────────────────────┬────────────────────┐
│ Magic (1B)│ Version (1B)│ Fingerprint (32B)    │ Candidates (Var)   │
│ 0x51 'Q'  │ Version:3b  │ SHA-256 DTLS         │ Binary-packed IPs  │
│           │ Reserved:5b │ (32 raw bytes)       │ (7B IPv4, 19B IPv6)│
└───────────┴─────────────┴──────────────────────┴────────────────────┘

Flags Byte Layout

Bits	Field	Values
0-1	Address Family	`00`=IPv4, `01`=IPv6, `10`=mDNS
2	Protocol	`0`=UDP, `1`=TCP
3	Candidate Type	`0`=Host, `1`=srflx
4-5	TCP Type	`00`=passive, `01`=active, `10`=so
6-7	Reserved	Must be `0`

Test Vector

Minimal valid packet (1 IPv4 host candidate):

Hex: 51 00 [32 bytes fingerprint] 00 C0A80105 D431
     ^  ^   ^                       ^  ^        ^
     |  |   |                       |  |        Port 54321
     |  |   |                       |  IP 192.168.1.5
     |  |   |                       Flags: IPv4, UDP, host
     |  |   DTLS fingerprint (SHA-256)
     |  Version 0
     Magic byte 'Q'

Total: 1 + 1 + 32 + 1 + 4 + 2 = 41 bytes

Decoded candidate line:

a=candidate:1 1 udp 2122260223 192.168.1.5 54321 typ host

<br />

A user asked a simple question. I spent an evening and a morning talking to an AI about protocol design. Being unreasonable turned out to be the only reasonable solution.

Want to learn more about AI-assisted development? Read about how AI is changing software team workflows or explore techniques for building tools with AI.

Why I Switched from Bun to Deno for Claude Code Skills

contact@magarcia.io — Thu, 15 Jan 2026 00:00:00 GMT

Bun's auto-install feature breaks when any node_modules directory exists in parent paths. This makes Bun unreliable for portable Claude Code skills that run from project directories or monorepos. After testing my previous npx bun approach in real environments, I switched to Deno. Here is why Deno's npm: specifier is the better choice for self-contained TypeScript skills.

Bun's auto-install only works when no node_modules directory exists in the working directory or any parent directory. When node_modules is present anywhere up the tree, Bun switches to standard Node.js module resolution. Version specifiers in imports—the core feature that made the approach useful—throw VersionSpecifierNotAllowedHere errors:

$ cd ~/my-project  # has node_modules/
$ cat skill.ts
#!/usr/bin/env -S npx -y bun
import chalk from "chalk@^5.0.0"
console.log(chalk.green("Hello"))

$ ./skill.ts
error: VersionSpecifierNotAllowedHere
  import chalk from "chalk@^5.0.0"
                    ^

This breaks in practical scenarios. Run a skill from within a project directory? Broken. Work in a monorepo where some ancestor has node_modules? Broken. Your home directory happens to have an old node_modules from a forgotten experiment? Broken.

For portable Claude Code skills that might run from anywhere, this is a footgun. The script works when you test it in ~/.claude/skills/, then fails mysteriously when Claude invokes it from a different directory. The error message obscures the problem—diagnosing it requires understanding Bun's internal resolution logic.

Credit for the solution goes to J Edward Wynia, who pointed me toward Deno in response to that article. I forget why I skipped Deno initially—probably because Bun's syntax looked cleaner—but the suggestion was right.

Why Deno Solves This

Deno's npm: specifier works regardless of whether node_modules exists. Dependencies always go to Deno's global cache at ~/.cache/deno. Local node_modules directories don't affect resolution—though you need the --node-modules-dir=false flag to ensure this behavior when running from directories that already have a node_modules folder. Consistent behavior everywhere.

The same npx distribution trick works. Just like npx -y bun, you can use npx -y deno to run Deno without installing it globally. Any environment with npm can execute Deno scripts.

One caveat: if Deno is already installed on your system, npx -y deno still downloads a separate copy to npm's cache (~40MB, comparable to Bun's ~100MB first-download cost). For systems with Deno pre-installed, use deno run directly. The npx approach targets portability—scripts that work on any machine with npm, regardless of what's pre-installed.

The Deno Approach

Here's what a Deno-based skill looks like:

#!/usr/bin/env -S npx -y deno run --node-modules-dir=false --allow-read --allow-write

import { parse } from "npm:csv-parse@^5.0/sync";
import chalk from "npm:chalk@^5.0.0";
import { z } from "npm:zod@^3.23";

const inputPath = Deno.args[0];
const content = await Deno.readTextFile(inputPath);

const rows = parse(content, { columns: true });
console.log(chalk.green(`Parsed ${rows.length} rows`));

The npm: prefix is more verbose than Bun's bare imports, but it clarifies package origins. TypeScript works natively. Version pinning lives in the import path, same as with Bun. No deno.json or import map required—dependencies resolve directly from the specifiers.

Deno requires permission flags—--allow-read, --allow-write, --allow-net, etc. More verbose than Bun, but you declare exactly what the script does. For skills running through Claude Code, explicit permissions document what the script can access. For trusted environments, --allow-all (or -A) skips the ceremony.

Trade-offs

Aspect	Bun	Deno
Import syntax	`import x from "pkg@1.0"`	`import x from "npm:pkg@1.0"`
node_modules safe	No	Yes
Raw performance	~20-30% faster	Slightly slower
TypeScript	Native	Native
Permissions model	Permissive by default	Explicit flags required

Bun is faster. Startup time, runtime performance, HTTP serving—Bun consistently beats Deno in benchmarks. If you're building a production API or a performance-critical CLI tool, that matters.

For Claude Code skills, it doesn't.

Why Performance Doesn't Matter Here

The agent's thinking time dwarfs script execution time. Claude takes two to five seconds to decide what to do next. A skill that runs in 50 milliseconds versus 80 milliseconds is effectively the same—both are instant compared to the agent's decision loop.

Reliability matters more. A skill that works from any directory is more valuable than a skill that's 30% faster but breaks in monorepos.

Practical Example for Skills

The structure follows the same pattern from the original article—a SKILL.md pointing to executable scripts. The only changes are the shebang and Deno-specific APIs:

#!/usr/bin/env -S npx -y deno run --node-modules-dir=false --allow-read --allow-write

import { parse } from "npm:csv-parse@^5.0/sync";
import * as XLSX from "npm:xlsx@^0.20";

const inputPath = Deno.args[0];
const content = await Deno.readTextFile(inputPath);

const rows = parse(content, { columns: true });
console.log(JSON.stringify(rows, null, 2));

Claude runs the skill, the script accesses npm packages, and everything works regardless of directory.

Conclusion

The npm: prefix is more verbose. Permission flags add ceremony. Bun's import syntax is cleaner and faster. But Deno's reliability across different directory structures makes it the better choice for Claude Code skills.

You don't have to debug why a skill works in one directory and fails in another. You don't have to document "this only works outside of projects with node_modules." The script just works.

If Bun adds a flag to force auto-install regardless of node_modules presence, I'd reconsider. Until then, Deno's consistency wins.

References

Writing Powerful Claude Code Skills with npx bun — The original exploration of this approach
Deno — A modern runtime for JavaScript and TypeScript
Deno npm compatibility — How the npm: specifier works
Bun Auto-Install Documentation — Understanding when auto-install activates
Claude Code Skills Documentation

YumML: A Human-Readable YAML Recipe Format for the AI Era

contact@magarcia.io — Sat, 10 Jan 2026 00:00:00 GMT

YumML is a human-readable recipe format based on YAML that makes cooking recipes easy to read, write, and parse. Unlike XML-based formats like RecipeML or proprietary formats, YumML prioritizes readability while remaining fully machine-parseable and AI-friendly.

Years ago, talking with a friend, we realized that no standard format exists for saving cooking recipes. At that time I was learning React, and one of my early projects was a recipe management app. I didn't succeed (like many projects I started and never finished), but along the way I found a draft spec for a recipe format: YumML.

<br />

Yes, I'm fully aware of the irony. xkcd.com/927

<br />

Paul Jenkins published this format on vikingco.de, but the site is now offline. The only references available are from the Internet Archive and the repository of the page that remains available.

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

History

The first draft of the YumML format is from September 21, 2011, made by Paul Jenkins, you can check the original specification here that I rescued from the old archives I found.

This draft is promising as a format for cooking recipes, so I want to recover it from the forgotten archives and revive it, adding extra functionalities and specifications.

Motivation

As the original author of YumML mentioned in his blog post, I've investigated cooking recipe formats and, to be clear, most suck. The landscape of recipe interchange formats is fragmented, but most share one trait: they lack human readability.

Most cooking software ships with proprietary formats that only that software can read. Some can be imported by other programs. Meal-Master is one of these widely supported formats and due to that there is a huge collection of recipes available online.

But looking at an example, the format seems poorly specified:

MMMMM----- Now You're Cooking! v5.65 [Meal-Master Export Format]

      Title: Agua De Valencia
 Categories: beverages, spanish
      Yield: 4 servings

      1    bottle of spanish cava
           -(sparkling wine or; champag
           plenty fresh orange juice
           cointreau
           ice cubes

Put some ice cubes into a large jug and pour over lots of orange juice. Now
add the bottle of cava. Once the fizz subsides, stir in a good dash of the
cointreau and it's ready to serve.

  Contributor:  Esther Pérez Solsona

  NYC Nutrilink: N0^00000,N0^00000,N0^00000,N0^00000

There are some other "famous" formats like:

But they are mainly XML-based formats, and no human can read a recipe written in them. If you're interested in finding other recipe formats, there is a list of software-related cooking formats.

It's worth mentioning some formats that came with the age of the Internet. HTML microdata like Google rich snippets and schema.org microdata are widely used by commercial recipe sites. Although microdata's main objective is machine-readability (especially for SEO), people still read and follow recipes.

Finally, I found pesto, which aims for a simpler human-readable format, but I find it difficult to understand for someone who is unfamiliar with the syntax.

Original design considerations

The original author of YumML had some considerations in mind during the design of the format:

Does not need a long reference guide.
Can be easily read by non-technical people in the "raw" format.
Can be translatable between imperial and metric.
Want something like the markdown of recipes (but still easy to parse with software).

YumML is based on YAML to create a human and system readable format.

From yaml.org

What It Is: YAML is a human friendly data serialization standard for all programming languages.

Why YAML in the Age of AI

When the original YumML spec was drafted in 2011, the consideration was purely about human and machine readability. Today, there's a third reader to consider: Large Language Models (LLMs).

As AI assistants become common in kitchens (think voice assistants reading recipes aloud, or chatbots helping you adapt recipes), the format you choose for structured data matters more than ever. Recent research shows that data format significantly impacts both token efficiency (cost) and model accuracy when LLMs process structured information.

Benchmarks across different models show that YAML uses 27-40% fewer tokens than JSON and 38-40% fewer than XML for the same data. Beyond cost savings, format also affects comprehension: YAML achieved 12-18 percentage points higher accuracy than JSON when models extracted information from nested data. The cleaner syntax with less punctuation noise helps models parse semantic content more reliably. While minified JSON can be more efficient, it sacrifices human readability entirely, which defeats YumML's core goals.

The best of both worlds

YAML's design strikes a balance that works well for this three-way readability requirement:

Humans can read it without training (no angle brackets or curly braces)
Machines can parse it with standard libraries in any language
AI models process it more efficiently and accurately than alternatives

This makes YumML particularly well-suited for modern recipe applications where an AI might help you scale a recipe, suggest substitutions, or convert between metric and imperial, all while keeping the source format readable in a text editor.

Goals

I want to define more formal goals for the spec.

YumML format:

MUST be human and system readable.
MUST be self contained, so it MUST NOT require additional resources to be interpreted.
MUST have support for different metric systems (metric, imperial).
SHOULD be easy to translate into different languages (recipes have a strong cultural influence and language should not be a barrier to someone who wants to understand).
SHOULD be easy to parse using already existing tools.
SHOULD be easy to extend in the future.

Technical Details

File extension: .yumml (files MUST be valid YAML)
MIME type: application/x-yumml+yaml
Encoding: UTF-8

Basic Example

name: Mrs Fields Choc-Chip Cookies
date: 2011-09-21
prepTime: 15 minutes
cookTime: 10 minutes
ingredients:
  - quantity: 2.5
    unit: cups
    item: plain flour

  - quantity: 0.5
    unit: tsp
    item: bicarbonate of soda

instructions:
  - step: Mix flour, bicarbonate of soda, and salt in a large bowl
  - step: Blend sugars with electric mixer, add margarine to form a grainy paste

Spec

There are three main sections that every recipe MUST include: the header, the ingredients list, and the instructions.

Header

The header is an implicit section where all the attributes are placed at the root level of the file. All the attributes SHOULD be placed at the top of the file, before ingredients and instructions.

Attribute	Type	Status	Description
`name`	string	REQUIRED	Name of the recipe
`date`	string	OPTIONAL	Publication date (RFC 3339 format, e.g., `2017-07-21`)
`author`	string	OPTIONAL	Author of the recipe
`description`	string	OPTIONAL	Brief description of the recipe
`prepTime`	duration	OPTIONAL	Preparation time (e.g., `15 minutes`)
`cookTime`	duration	OPTIONAL	Cooking/baking time (e.g., `10 minutes`)
`totalTime`	duration	OPTIONAL	Total time (MAY be derived from `prepTime` + `cookTime`)
`servings`	integer	OPTIONAL	Number of portions the recipe serves
`yield`	string	OPTIONAL	What the recipe produces (e.g., `24 cookies`, `1 loaf`)
`rating`	number (1-5)	OPTIONAL	Recipe rating
`tags`	string[]	OPTIONAL	Categorization tags

Duration format: Human-readable strings. For maximum compatibility, use integers followed by minutes, hours, or seconds (e.g., 15 minutes, 1 hour 30 minutes). Parsers SHOULD also accept common abbreviations (15 min, 1 hr) and natural variations (1.5 hours).

Example

name: Mrs Fields Choc-Chip Cookies
date: 2011-09-21
author: Paul Jenkins
description: Classic chocolate chip cookies, crispy outside and chewy inside.
prepTime: 15 minutes
cookTime: 10 minutes
servings: 4
yield: 24 cookies
tags:
  - cookies
  - chocolate
ingredients:
  - quantity: 2.5
    unit: cups
    item: plain flour

  - quantity: 0.5
    unit: tsp
    item: bicarbonate of soda

instructions:
  - step: Mix flour, bicarbonate of soda, and salt in a large bowl
  - step: Blend sugars with electric mixer, add margarine to form a grainy paste

Ingredients

The ingredients section is a REQUIRED list of all ingredients needed for the recipe.

Attribute	Type	Status	Description
`quantity`	number \| string	OPTIONAL	Amount (number, fraction like `"1/2"`, or descriptor like `"to taste"`)
`unit`	string	OPTIONAL	Unit of measurement (see canonical units below)
`item`	string	REQUIRED	Name of the ingredient
`notes`	string	OPTIONAL	Additional notes (e.g., `room temperature`, `finely chopped`)
`optional`	boolean	OPTIONAL	Whether the ingredient is optional (default: `false`)

Canonical Units

To support conversion between metric and imperial systems, implementations SHOULD recognize these canonical unit abbreviations:

Category	Units
Volume	`tsp`, `tbsp`, `cup`, `ml`, `l`, `fl-oz`
Weight	`g`, `kg`, `oz`, `lb`
Count	(omit `unit` for countable items like eggs)

Example

ingredients:
  # Numeric quantities
  - quantity: 2.5
    unit: cups
    item: plain flour

  - quantity: 200
    unit: g
    item: chocolate chips
    notes: semi-sweet

  # Fraction string (more readable than 0.5)
  - quantity: "1/2"
    unit: cup
    item: walnuts
    notes: chopped
    optional: true

  # Countable items (no unit needed)
  - quantity: 2
    item: eggs
    notes: room temperature

  # Descriptor string for fuzzy amounts
  - quantity: "to taste"
    item: salt

  # No quantity (implied "some")
  - item: cooking spray
    notes: for greasing

Instructions

The instructions section is a REQUIRED list of steps to prepare the recipe. Instructions support two formats: a simple flat list or grouped sections for complex recipes.

Simple Format

Attribute	Type	Status	Description
`step`	string	REQUIRED	The instruction text
`duration`	duration	OPTIONAL	Time for this step
`temperature`	string	OPTIONAL	Temperature setting (e.g., `180C`, `350F`)

instructions:
  - step: Preheat oven
    temperature: 180C
  - step: Mix dry ingredients in a large bowl
  - step: Bake until golden brown
    duration: 10 minutes

Grouped Format

For complex recipes with multiple stages, instructions MAY be organized into sections:

Implementation note: Parsers MUST handle both formats. Check for the presence of section to determine the format: if any item has a section field, treat as grouped; otherwise, treat as simple.

instructions:
  - section: For the dough
    steps:
      - step: Mix flour and salt
      - step: Add water gradually

  - section: For the filling
    steps:
      - step: Sauté onions until translucent
        duration: 5 minutes
      - step: Add remaining filling ingredients

Design Notes

A few decisions deserve explanation.

Why `quantity` is optional and accepts strings

Cooking is fuzzy. Real recipes include instructions like "salt to taste", "a pinch of nutmeg", or "butter for greasing". Forcing a numeric quantity would either exclude these cases or push authors toward awkward workarounds like quantity: 0.

Allowing strings also enables fractions like "1/2", which are more readable in a recipe context than 0.5. The trade-off is that parsers need to handle multiple types, but this reflects the inherent ambiguity of cooking rather than fighting it.

Why human-readable durations instead of ISO 8601

ISO 8601 durations (PT25M) are unambiguous and machine-friendly, but they fail the "readable by a non-technical person" goal. A home cook glancing at a .yumml file should immediately understand 25 minutes without consulting a reference.

The spec recommends a structured subset (integer + unit) for tools that need reliable parsing but remains flexible enough to accept natural variations.

Why instructions support two formats

Simple recipes don't need sections. Forcing authors to write section: main for a basic cookie recipe adds friction. But complex recipes (like a multi-component pie) genuinely benefit from grouping steps by stage.

The polymorphic design prioritizes author convenience over parser simplicity. The implementation note makes the parsing logic explicit: check for section to determine the format.

Complete Example

Here's a comprehensive example demonstrating all YumML features:

name: Classic Apple Pie
date: 2024-03-15
author: Jane Baker
description: A traditional apple pie with a flaky butter crust and cinnamon-spiced filling.
prepTime: 45 minutes
cookTime: 55 minutes
totalTime: 1 hour 40 minutes
servings: 8
yield: 1 pie (9-inch)
rating: 5
tags:
  - dessert
  - pie
  - baking

ingredients:
  - quantity: 2.5
    unit: cups
    item: all-purpose flour

  - quantity: 1
    unit: tsp
    item: salt

  - quantity: 1
    unit: cup
    item: unsalted butter
    notes: cold, cubed

  - quantity: 6
    unit: tbsp
    item: ice water

  - quantity: 6
    item: apples
    notes: peeled and sliced (Granny Smith recommended)

  - quantity: 0.75
    unit: cup
    item: sugar

  - quantity: 2
    unit: tsp
    item: cinnamon

  - quantity: 0.25
    unit: cup
    item: caramel sauce
    optional: true

instructions:
  - section: For the crust
    steps:
      - step: Combine flour and salt in a large bowl
      - step: Cut in cold butter until mixture resembles coarse crumbs
      - step: Add ice water gradually, mixing until dough forms
      - step: Divide dough in half, wrap in plastic, and refrigerate
        duration: 30 minutes

  - section: For the filling
    steps:
      - step: Preheat oven
        temperature: 375F
      - step: Toss sliced apples with sugar and cinnamon
      - step: Roll out bottom crust and place in pie dish

  - section: Assembly
    steps:
      - step: Add apple filling to crust
      - step: Roll out top crust and place over filling
      - step: Crimp edges and cut vents in top
      - step: Bake until golden brown and bubbling
        duration: 55 minutes
        temperature: 375F
      - step: Cool before serving
        duration: 30 minutes

What's Next

This spec is a starting point—to become useful, YumML needs implementations. If you're interested in contributing:

Write a parser in your favorite language (TypeScript, Python, Go, Rust...)
Build a converter from schema.org/Recipe to YumML
Create a VS Code extension with syntax highlighting and validation
Experiment with LLMs to see how well they can generate and parse YumML

If you build something, I'd love to hear about it.

Interested in more open-source projects? Check out cross-keychain, a cross-platform secret storage library, or see how I used AI to design the QWBP protocol for serverless WebRTC.

Writing Powerful Claude Code Skills with npx bun

contact@magarcia.io — Wed, 07 Jan 2026 00:00:00 GMT

Update (January 15, 2026): After more testing, I've found Bun's node_modules detection can break auto-install in unexpected situations. I now recommend Deno for this use case. The approach below still works for standalone scripts, but see Why I Switched from Bun to Deno for Claude Code Skills for the full breakdown.

Claude Code skills let you extend Anthropic's agentic coding CLI with custom instructions and executable scripts. But what if your script needs third-party npm packages like lodash, zod, or csv-parse? Without a build step or node_modules folder, imports fail. This guide shows how to use npx bun to write self-contained TypeScript skills that auto-install dependencies at runtime—no package.json required.

The problem: Claude Code skills have no build step. You cannot just import lodash from 'lodash' and expect it to work. The script runs in a fresh environment with no node_modules folder.

What I Wanted: uv run for JavaScript

Python solves this elegantly with uv. You declare dependencies inline using PEP 723 metadata:

#!/usr/bin/env -S uv run
# /// script
# dependencies = ["requests", "rich"]
# requires-python = ">=3.10"
# ///

import requests
from rich import print

print(requests.get("https://example.com"))

Run it with uv run script.py or just ./script.py. Dependencies install automatically into an isolated environment. No requirements.txt, no virtual environment management, no build step. The script is self-contained.

Python was my first professional programming language, and I still admire how its ecosystem has evolved. But my team at Buffer works in TypeScript. I needed something that would be easy for my teammates to pick up—familiar npm packages, familiar syntax—but as flexible and powerful as uv run.

The Constraint

A typical Claude Code skill looks like this:

my-skill/
├── SKILL.md
└── scripts/
    └── process.js

Claude reads SKILL.md for instructions and executes the scripts when relevant. But if process.js imports any npm package, it fails. No package.json, no node_modules, no dependencies.

The obvious solutions—committing node_modules or running npm install at runtime—are ugly. The first bloats your skill folder. The second adds latency every time.

I explored several approaches.

Approach 1: Pre-bundling with esbuild

Bundle your script into a single file with all dependencies included:

esbuild script.ts --bundle --platform=node --outfile=script.mjs

The output is self-contained. No runtime dependencies. Ship it with your skill and Claude runs it directly.

This works, but requires a build step. You must rebuild after every change. Debugging bundled code is harder. It's the opposite of what I wanted.

Approach 2: Dynamic imports with esm.sh

esm.sh serves npm packages as ES modules over HTTPS:

import _ from "https://esm.sh/lodash@4.17.21";
import { z } from "https://esm.sh/zod@3.23.0";

No installation needed. The runtime fetches the module on first use. Version pinning lives in the URL.

The problem: Node.js doesn't natively support HTTPS imports without experimental flags or custom loaders. Some packages don't work well as pure ESM. Network latency on every cold start adds up.

Approach 3: Google `zx` with `--install`

zx is Google's tool for writing shell scripts in JavaScript. It wraps child_process and adds conveniences like the $ template literal for running commands.

The --install flag auto-installs missing dependencies:

#!/usr/bin/env zx
import _ from "lodash"; // @^4.17
import { parse } from "yaml"; // @^2.0

await $`echo "Dependencies auto-installed"`;

Run it with npx zx --install script.mjs. On first run, zx detects the imports, installs the packages, and caches them.

This gets closer to what I wanted. But version pinning through comments feels hacky. And there's no native TypeScript support—you'd need tsx or similar.

Approach 4: Bun

Bun takes a different approach. Auto-install is built into the runtime. Write normal imports and Bun handles the rest:

#!/usr/bin/env bun
import _ from "lodash";
import { z } from "zod@^3.20";
import chalk from "chalk@^5.0.0";

console.log(chalk.green("Dependencies just work"));

Version pinning happens directly in the import path—cleaner than zx's comment syntax. TypeScript runs natively. Startup is fast.

The catch: Bun might not be installed in every environment. Claude Code environments have Node.js and npm, but not necessarily Bun.

The Discovery: npx bun

Then I realized: I don't need Bun installed globally. I just need npm.

npx -y bun script.ts

The -y flag skips the confirmation prompt, which matters for non-interactive execution. This works because bun is published as an npm package. When you run npx bun, npm downloads the Bun binary and executes your script. You get Bun's auto-install, TypeScript support, and speed—all through the npm/Node.js toolchain that's already everywhere.

I tested this in a fresh environment:

import chalk from "chalk@^5.0.0";
import { z } from "zod@3.23.0";
import _ from "lodash@^4.17.0";

console.log(chalk.green("✓ chalk loaded"));

const schema = z.object({ name: z.string() });
console.log(chalk.blue(`✓ zod loaded - validation works`));

const grouped = _.groupBy(["one", "two", "three"], "length");
console.log(chalk.yellow(`✓ lodash loaded`));

Output:

✓ chalk loaded
✓ zod loaded - validation works
✓ lodash loaded

No package.json. No node_modules. No build step. The first run installs dependencies to Bun's global cache. Subsequent runs are instant.

This is the JavaScript equivalent of uv run. Same developer experience, same self-contained scripts, familiar npm ecosystem.

Making Scripts Directly Executable

It gets better. Just like Python's #!/usr/bin/env -S uv run, you can use a shebang to make scripts directly executable:

#!/usr/bin/env -S npx -y bun

import chalk from "chalk@^5.0.0";

console.log(chalk.green("Hello!"));

The -S flag tells env to split the string into separate arguments. Make the script executable and run it directly:

chmod +x script.ts
./script.ts

Now you have self-contained TypeScript scripts—no explicit invocation needed.

Using This in Claude Code Skills

Structure your skill like this:

my-skill/
├── SKILL.md
└── scripts/
    └── process.ts

In SKILL.md:

---
name: data-processor
description: Process and transform data files using advanced libraries
allowed-tools: [Bash, Read, Write]
---

# Data Processor

Run the processing script:

```bash
./scripts/process.ts <input-file>
```

In scripts/process.ts:

import { parse } from "csv-parse/sync@^5.0";
import * as XLSX from "xlsx@^0.20";

const [, , inputPath] = Bun.argv;
const file = Bun.file(inputPath);
const content = await file.text();

const rows = parse(content, { columns: true });
console.log(JSON.stringify(rows, null, 2));

Claude runs the skill, the script executes with full access to npm packages, and you never touch a package.json.

Comparison

Approach	Build Step	TypeScript	Version Pinning	First-run Speed
esbuild bundle	Yes	Via build	In source	Fast
esm.sh	No	No	In URL	Network-bound
npx zx --install	No	Via tsx	Comments	Moderate
npx -y bun	No	Native	In import path	Fast after cache

Caveats

This approach isn't perfect. A few things to consider:

Auto-install requires no node_modules directory. Bun's auto-install feature only works when no node_modules directory is found in the working directory or any parent directory.[^1] When a node_modules folder exists—common in monorepos or existing projects—Bun switches to regular Node.js module resolution instead of its auto-install algorithm. Even the --install=force flag doesn't fully solve this: version specifiers in imports (like import { z } from "zod@3.0.0") will throw a VersionSpecifierNotAllowedHere error when node_modules is present. This means the approach works best for standalone scripts outside of existing projects. For Claude Code skills stored in ~/.claude/skills/, this typically isn't an issue. But if you're writing scripts inside a project directory with node_modules, you'll need to either use a traditional package.json or move the script outside the project tree.

Bun is not fully Node.js compatible. Most npm packages work fine, but some Node.js APIs behave differently or aren't implemented yet. If your script depends on edge-case Node.js behavior—certain fs operations, specific child_process options, native addons—you might hit unexpected issues. Check Bun's Node.js compatibility documentation before committing to this approach.

First-run latency still exists. The first execution downloads Bun via npx (~100MB depending on architecture) and installs dependencies. On a slow connection or in a cold-start environment, this adds noticeable time. Subsequent runs are fast, but that initial hit matters if your skill runs in ephemeral environments that don't preserve Bun's cache.

Version pinning in imports is non-standard. The import x from "pkg@^1.0" syntax is Bun-specific. Your IDE won't understand it for autocompletion or type checking. For quick scripts, you can add // @ts-ignore above the problematic imports. For more serious development, maintain a package.json with proper versions and only use the inline syntax in the deployed skill.

When to use zx instead. If you need guaranteed Node.js compatibility—because you're using a package that relies on Node-specific internals, or your team has strict runtime requirements—zx with --install is the safer choice. It runs on Node.js directly, so compatibility is never a question. The trade-off is no native TypeScript and the comment-based version pinning.

For most skills that use common packages like lodash, zod, or csv-parse, Bun works fine. But know the escape hatch exists.

Conclusion

npx -y bun combines the best properties: no build step, native TypeScript, clean version pinning, and availability anywhere npm runs. For Claude Code skills that need third-party packages, it's the simplest path to powerful scripts—as long as you stay within Bun's compatibility boundaries.

If you've used Python's uv and wished JavaScript had something similar, this is it. Same philosophy, same workflow, familiar tools. And when you hit Bun's edges, zx is there as a fallback.

References

[^1]: Bun Auto-Install Documentation — "If no node_modules directory is found in the working directory or higher, Bun will abandon Node.js-style module resolution in favor of the Bun module resolution algorithm."

Claude Code Skills Documentation
Bun — The JavaScript runtime with built-in auto-install
Bun Module Resolution — Understanding how Bun resolves modules
Google zx — A tool for writing better scripts
esm.sh — npm packages as ES modules over CDN
uv — Python's package manager with inline script dependencies (uv run)
PEP 723 — Inline script metadata specification for Python
esbuild — Fast JavaScript bundler

Building granola-cli: AI Meeting Notes in Your Terminal

contact@magarcia.io — Mon, 22 Dec 2025 00:00:00 GMT

Disclaimer: This project is an independent open-source tool and is not affiliated with, endorsed by, or connected to Granola.ai.

What if you could query your meeting history like a database? granola-cli brings your Granola.ai meeting notes to the command line—grep transcripts, export to JSON, and pipe action items directly into Claude Code or your task manager.

What is Granola?

Granola is an AI meeting assistant that sits in your menu bar. It records system audio, transcribes locally, and uses LLMs to produce structured summaries—key decisions, action items, discussion points. No bots joining your calls, no awkward "Granola is recording" notifications to your teammates. At Buffer, it has become a daily driver for our team.

The notes it generates are excellent. But I hit a ceiling.

The Problem I Needed to Solve

I wanted raw data in my terminal. I wanted to feed last week's engineering syncs into Claude Code to plan my next sprint. I wanted to grep through transcripts or pipe action items directly into my task manager.

Copy-pasting from a web UI fell short. I found Joseph Thacker's research on reverse engineering the Granola API, plus the getprobo/reverse-engineering-granola-api repo. The groundwork existed. A proper CLI for daily use did not.

So I built one.

How I Mapped Granola's API

The Granola desktop app stores authentication tokens in a local JSON file. The CLI reads these credentials, stores them securely in your system keychain via cross-keychain (which I wrote about previously), and uses them to call Granola's internal APIs.

Key endpoints I mapped:

POST /v2/get-documents — list meetings with cursor pagination
POST /v1/get-document-metadata — notes and participant data
POST /v1/get-document-transcript — transcript segments with speaker detection
POST /v2/get-document-lists — folders and workspace organization

Query, Filter, and Export Your Meetings

List and Filter

# Recent meetings
granola meeting list --limit 10

# Filter by date (natural language supported)
granola meeting list --date yesterday
granola meeting list --since "last week"
granola meeting list --since 2025-12-01 --until 2025-12-15

# Filter by attendee or search
granola meeting list --attendee "john@example.com"
granola meeting list --search "quarterly planning"

View Content

# Full meeting details with participants
granola meeting view <id>

# Your handwritten notes (converted from ProseMirror to Markdown)
granola meeting notes <id>

# AI-generated summary with key decisions and action items
granola meeting enhanced <id>

# Full transcript with speaker detection
granola meeting transcript <id>
granola meeting transcript <id> --timestamps

Export for Pipelines

# Export everything about a meeting
granola meeting export <id> --format json
granola meeting export <id> --format toon

# Pipe to LLMs
granola meeting enhanced <id> --output toon | llm "What were the action items?"

40% Fewer Tokens with TOON

The CLI supports TOON (Token-Oriented Object Notation), a format designed for LLM consumption. TOON delivers the same structured data as JSON using 40% fewer tokens.

When you pipe meeting data to Claude or another model, every token saved means more context for your question. TOON determines whether one meeting or three fits your context window.

$ granola meeting export abc123 --format json | wc -c
  15234

$ granola meeting export abc123 --format toon | wc -c
  9140

Same data. 40% smaller. That's the difference between asking a follow-up question or hitting your context limit.

Turning Meeting History into AI Context

This is why I built it: to empower my AI agents.

I use Claude Code heavily. With granola-cli installed, I can ask Claude to analyze my meetings directly:

You: Check my engineering syncs from last week and list any blockers mentioned.

Claude: I'll query your recent meetings using granola-cli.

[Runs: granola meeting list --since "last week" --search "sync"]

Found 3 engineering syncs. Analyzing transcripts...

Blockers mentioned:
1. CI pipeline flakiness blocking the release (Dec 18 sync)
2. Waiting on design review for the dashboard redesign (Dec 19 sync)
3. API rate limiting issues with the third-party integration (Dec 20 sync)

No copy-pasting. No switching windows. Claude reads the data directly and gives me answers.

I've also built Agent Skills that check meeting history, summarize decisions, and surface blockers from previous syncs. Your meeting history becomes a queryable database for your AI workflow.

Under the Hood

Secure Credential Storage

I refuse to store API tokens in plaintext config files. Too many CLI tools dump secrets into ~/.config/toolname/credentials.json. One accidental git add . or misconfigured backup exposes your tokens.

The CLI stores credentials via cross-keychain in your OS's native credential manager—macOS Keychain, Windows Credential Manager, or Linux Secret Service. These systems encrypt secrets at rest, integrate with your login session, and follow platform security best practices. Your Granola tokens never touch the filesystem in readable form.

Token Refresh with File Locking

Granola uses single-use refresh tokens—each token works once before invalidation. This improves security but creates a race condition: if two CLI processes refresh simultaneously, one gets a valid token while the other wastes the refresh token and fails.

The CLI solves this with file-based locking. Before refreshing, the process acquires an exclusive lock on a temp file. If another process is already refreshing, the second waits (30-second timeout) rather than racing. The lock releases immediately after refresh completes, so parallel CLI invocations work smoothly—they take turns when needed.

ProseMirror to Markdown Conversion

Granola stores notes in ProseMirror format—the same rich-text framework Notion, The New York Times, and Atlassian use. It represents content as a JSON tree of nodes with marks (formatting) attached.

The CLI walks this tree, converting it to Markdown. Headings become # lines, lists become - items, text marks become their Markdown equivalents: bold wraps in **, italic in *, code in backticks. The conversion preserves nested structures, so a bulleted list inside a blockquote renders correctly. The result: readable Markdown you can pipe to other tools, search with grep, or feed to an LLM.

Natural Language Date Parsing

Nobody types ISO dates willingly. The CLI accepts "today", "yesterday", "3 days ago", "last week", or partial dates like "Dec 1". For ranges, combine --since and --until with any format. The parser handles the rest.

The parser normalizes input, handles edge cases (what does "last week" mean on a Monday?), and returns UTC timestamps matching Granola's API expectations. The common case—"show me yesterday's meetings"—becomes a single intuitive flag.

4 Hours with Claude Code Opus 4.5

I built this tool in about 4 to 5 hours pairing with Claude Code Opus 4.5. I focused on architecture and intent while Claude handled implementation. The result: a production-ready CLI with strict TypeScript, 95%+ test coverage across 630+ test cases, and modular design—all in a single afternoon.

This is "vibe engineering" in practice. I skipped the lengthy planning phase, described what I wanted, reviewed the output, and iterated quickly.

Get Started

# Install
npm install -g granola-cli

# Login (reads credentials from your Granola desktop app)
granola auth login

# List your meetings
granola meeting list

The source is at github.com/magarcia/granola-cli. Issues and PRs welcome.

Related posts:

Cross-Platform Secret Storage in Node.js with cross-keychain - The library granola-cli uses for secure credential storage
Asking AI to Build the Tool Instead of Doing the Task - How I approach AI-assisted development

Cross-Platform Secret Storage in Node.js with cross-keychain

contact@magarcia.io — Wed, 01 Oct 2025 00:00:00 GMT

Stop storing API keys in plaintext .env files. cross-keychain is a TypeScript library that uses your OS's native credential manager to store secrets securely—macOS Keychain, Windows Credential Manager, or Linux Secret Service. One API, zero plaintext config files.

Born from mcp-tool-selector (still work in progress), where I needed to manage API keys for multiple MCP servers without scattering secrets across .env files — or worse, committing them to repos. It became a solid cross-platform utility, so I published it.

At a glance

Works on macOS, Windows, and Linux with native backend support
Provides both programmatic API and CLI for storing/retrieving secrets
Automatic fallback when native modules aren't available
Zero deps on the public API, TS-first, Node 18+, ESM/CJS

Docs & API: read the GitHub repo and the npm package page.

Quick taste: store & retrieve secrets

Programmatic usage:

import { setPassword, getPassword } from "cross-keychain";

// Store a secret
await setPassword("myapp", "api-token", "sk-1234567890");

// Retrieve it later
const token = await getPassword("myapp", "api-token");
console.log(token); // "sk-1234567890"

// Delete when done
await deletePassword("myapp", "api-token");

CLI usage:

# Store a secret
npx cross-keychain set myapp api-token

# Retrieve it
npx cross-keychain get myapp api-token

# Delete it
npx cross-keychain delete myapp api-token

Why this matters

Storing secrets in plaintext .env or config files is common but risky. You must remember to .gitignore them, rotate them when they leak, and manage them across environments. Native OS credential stores handle this—encrypted at rest, access-controlled, and integrated with your system.

cross-keychain provides a consistent API across platforms: write once, let the OS handle the heavy lifting.

My third AI-engineered project (after mcp-server-giphy and env-interpolation), built with multiple AI agents. Tired of managing plaintext secrets? This simplifies everything.

When to Use cross-keychain

This library is ideal for:

CLI tools that need to store API tokens between sessions
Development environments where you want secure credential storage
Local applications that authenticate with external services
Any Node.js app that currently uses .env files for secrets

It's not suitable for server-side applications in production—those should use dedicated secret managers like HashiCorp Vault or cloud provider solutions.

Conclusion

If you're building Node.js tools that handle credentials, stop relying on plaintext files. cross-keychain gives you secure, native storage with minimal API surface. Your users' secrets deserve better than credentials.json.

Related posts:

Enable environment variables in your configs with env-interpolation - Variable interpolation for config files
I Reverse Engineered My Meeting Notes into the Terminal - A CLI that uses cross-keychain for secure credential storage

Stop Sprinkling process.env Everywhere: Use env-interpolation

contact@magarcia.io — Mon, 29 Sep 2025 00:00:00 GMT

Tired of process.env scattered across your codebase? env-interpolation is a TypeScript library that resolves ${VAR} and ${VAR:default} placeholders inside config objects. It walks strings in objects/arrays and never touches keys, so shapes stay stable and predictable—perfect for layered configuration.

I built it for mcp-tool-selector, where I needed layered config without leaking secrets or scattering process.env calls. It became a sharp utility, so I published it.

At a glance

Resolves placeholders in values only (objects/arrays), keys untouched
Supports defaults and multi-pass resolution
Zero deps, TS-first, Node 18+, ESM/CJS

Docs & API: read the GitHub repo and the npm package page.

Quick taste: load JSON → interpolate

config.json

{
  "api": "${API_URL:https://api.example.com}",
  "timeoutMs": "${TIMEOUT:5000}",
  "flags": ["${PRIMARY:alpha}", "${SECONDARY:beta}"],
  "service": {
    "url": "${SERVICE_URL:${API_URL}/v1}",
    "headers": { "x-tenant": "${TENANT:public}" }
  }
}

load-config.ts

import { readFileSync } from "node:fs";
import { interpolate } from "env-interpolation";

const raw = readFileSync("config.json", "utf8");
const input = JSON.parse(raw);

const resolved = interpolate(input, {
  API_URL: "https://api.example.com",
  TIMEOUT: "8000",
  TENANT: "public",
});

console.log(resolved);

This is my second AI-engineered project (the first was mcp-server-giphy), built with multiple AI agents (Claude, Copilot, Gemini & Codex). If your configs span files, environments, and tools, this should smooth a few rough edges.

Why Not Just Use process.env Directly?

Reading environment variables inline scatters configuration logic throughout your codebase:

// Scattered approach - hard to audit and test
const apiUrl = process.env.API_URL || "https://api.example.com";
const timeout = parseInt(process.env.TIMEOUT || "5000", 10);

With env-interpolation, configuration stays centralized. Define the structure once, and the library handles resolution:

// Centralized approach - config.json is the source of truth
const config = interpolate(loadConfig("config.json"), process.env);

This makes configs easier to audit, test, and share across environments.

When to Use env-interpolation

Multi-environment configs: Development, staging, production with the same structure
Layered configuration: Base config with environment-specific overrides
Tool configuration: CLI tools that need portable config files
Monorepos: Shared config templates across packages

Related: For secure secret storage without plaintext files, check out cross-keychain, which stores credentials in your OS's native credential manager.

Asking AI to Build the Tool Instead of Doing the Task

contact@magarcia.io — Fri, 06 Jun 2025 00:00:00 GMT

What if the best way to use AI for code migrations isn't asking it to do the work, but asking it to build the tool that does? This counterintuitive approach transformed how our team handles large-scale refactoring, reducing errors by 95% and completing migrations in hours instead of days.

The Problem

Any reasonably sized codebase demands large-scale changes: migrating libraries, updating deprecated APIs, or refactoring components. The traditional AI approach looks like this:

Hey AI, please update all tooltip components from @old-design-system to @new-design-system

And then the problems begin:

The AI struggles to maintain context across hundreds of files
Token consumption explodes as it processes each file
Error rates increase with scale
You spend more time fixing the AI's mistakes than doing the migration yourself

The Better Approach

Instead of asking AI to perform the migration directly, we ask it to build a tool that performs the migration. Here's how it works:

Step 1: Manual Migration

First, pick a representative example and migrate it manually. This serves two purposes:

You understand the exact transformation needed
You have a concrete example to show the AI

// Before: Using old tooltip
import { Tooltip } from '@old-design-system';

<Tooltip content="Hello" position="top">
  <Button>Hover me</Button>
</Tooltip>

// After: Using new tooltip
import { Tooltip } from '@new-design-system';

<Tooltip title="Hello" placement="top">
  <Button>Hover me</Button>
</Tooltip>

Step 2: Extract the Pattern

Get the diff of your changes and document both the old and new component signatures:

- import { Tooltip } from '@old-design-system';
+ import { Tooltip } from '@new-design-system';

- <Tooltip content={text} position={position}>
+ <Tooltip title={text} placement={position}>

Step 3: Build the Automation

Now, instead of asking the AI to perform hundreds of similar changes, we ask it to build a codemod:

Based on this migration example, build a codemod that:
1. Updates the import statement
2. Renames the 'content' prop to 'title'
3. Renames the 'position' prop to 'placement'

The AI will generate a proper codemod using tools like jscodeshift that can be run across your entire codebase.

Real-World Results

We recently used this approach at Buffer to migrate tooltip components from our legacy design system to a new one. The results were impressive:

95% success rate: Most components migrated perfectly without manual intervention
2 hours instead of 2 days: The entire migration was completed in a fraction of the expected time
5% edge cases: The failures were weird corner cases and legacy tooltip variants we didn't even know existed

Compare this to our previous attempts where we asked AI to do the migration directly:

60% success rate
Constant need for manual fixes
Token limits hit frequently
Inconsistent transformations across files

Why This Works

AI excels at pattern recognition and code generation but struggles to maintain context across large-scale operations. Asking it to build a tool plays to its strengths:

Single focused task: Building a codemod is one coherent task, not hundreds of micro-tasks
Pattern abstraction: The AI can focus on understanding the transformation pattern rather than applying it
Testable output: You can test the codemod on a few files before running it everywhere
Reusable: The codemod can be shared with your team or used for similar migrations

The Beauty of Throwaway Code

We never review the codemod code that the AI generates. Why? Its quality does not matter — it runs once and gets deleted after the migration.

This is the perfect scenario for "vibe coding" — letting AI generate code without review. Only the outcome matters: Did the migration work? Are the transformed files correct?

Think about it:

The codemod runs once, then gets deleted
You review the actual changes in your pull request anyway
If it fails, you iterate
Nobody maintains or builds upon this code

This mindset shift liberates you. Skip perfecting the migration script; focus on the migrated code.

An Interesting Observation

While testing Claude Code on a similar migration task, I noticed something fascinating. The AI started by making changes file-by-file, but after processing a few files, it stopped and began writing migration scripts instead.

It created multiple bash scripts for different edge cases instead of a unified codemod — not perfect, but it shows that AI tools now recognize these patterns. The AI autonomously realized that building a tool beats doing the task manually.

When to Use This Approach

This technique works best for:

Library migrations
API updates
Component refactoring
Any repetitive transformation with a clear pattern

It's less suitable for:

One-off changes
Complex refactoring that requires human judgment
Changes with no clear pattern

Conclusion

The meta-lesson: have AI build the fishing rod, not catch each fish. When facing a large-scale code change, resist dumping the entire task on AI. Instead:

Do one example manually
Have AI build the automation
Review and run the tool

This approach transformed how our team handles migrations. Teammates I share it with consistently marvel at the results. Use AI smarter, not less.

Related posts:

Writing Powerful Claude Code Skills with npx + Bun - Extend AI capabilities with custom skills
Why I Switched from Bun to Deno for Claude Code Skills - Runtime considerations for AI tooling

A Comprehensive Guide to DMARC: Ensuring Email Integrity and Trust

contact@magarcia.io — Mon, 11 Sep 2023 00:00:00 GMT

While developing Voices.ink, a collaborative project with @Ester Martí that transcribes voice notes into Notion, I faced a common problem. How could I ensure our transactional emails reached inboxes rather than spam folders — or worse, prevent attackers from weaponizing our domain for phishing? My research led me to DMARC.

Email forms the backbone of professional communication, yet its security vulnerabilities remain startling. Cyber attackers constantly deceive through email spoofing and phishing. As fraud escalates, robust solutions become imperative. DMARC — an advanced email protocol — restores trust in our inboxes.

Why Do We Need DMARC?

Email's inherent vulnerabilities enable domain impersonation, where attackers send emails pretending to be from trusted sources. SPF (Sender Policy Framework) and DKIM (DomainKeys Identified Mail) counter these threats but remain imperfect. DMARC (Domain-based Message Authentication, Reporting & Conformance) fills this gap by leveraging both SPF and DKIM.

Understanding DMARC's Significance

DMARC serves three main purposes:

Authentication: Ensuring that an email claiming to be from a specific domain genuinely originates from that domain.
Reporting: Enabling domain recipients to report back to the sender about DMARC evaluation results, thereby offering insights into potential issues.
Policy Enforcement: Granting domain owners the power to specify how unauthenticated emails should be handled.

Credit: Emailonacid (How DMARC policy works)

The Building Blocks of DMARC: SPF & DKIM

SPF verifies that the email's sending server has the domain owner's authorization. It uses a specific TXT record in the DNS, like:

v=spf1 ip4:192.0.2.0/24 ip4:198.51.100.123 a:mail.example.com -all

This record essentially says, "Only the IP range 192.0.2.0 to 192.0.2.255 and 198.51.100.123 are authorized to send emails for my domain."

Explanation:

v=spf1: This indicates the version of SPF being used, which is SPF version 1.
ip4:192.0.2.0/24: Authorizes the IP range 192.0.2.0 to 192.0.2.255 to send emails for the domain.
ip4:198.51.100.123: Authorizes the specific IP address 198.51.100.123.
a:mail.example.com: Authorizes the IP address resolved from the domain name mail.example.com.
-all: Specifies that no other hosts are allowed to send emails. (The '-' is a hard fail, meaning emails from other sources should be rejected. ~all would be a soft fail, suggesting they should be accepted but marked.)

DKIM, on the other hand, ensures the email's integrity by using cryptographic signatures. A typical DKIM TXT DNS record might look like:

v=DKIM1; p=MIGfMA0GCSqG...

This record holds the public key used by receiving servers to decrypt the email's DKIM signature and verify its authenticity.

The record's name typically includes a selector prefix, allowing the domain to have multiple DKIM keys. When sending an email, the server will mention which selector it's using, guiding the receiving server to the right DNS record.

Explanation:

v=DKIM1: This signifies the version of DKIM being used.
p=: This is the public key that receiving servers use to decrypt the DKIM signature in the email header. The actual key would be a long string (truncated in the example).

DMARC in Action

When DMARC is implemented, domain owners publish a DMARC policy in their TXT DNS records (using the name _dmarc), such as:

v=DMARC1; p=reject; rua=mailto:reports@example.com; ruf=mailto:forensic@example.com; pct=100; aspf=r; adkim=r

This record translates to: "If an email fails DMARC authentication, reject it. And send aggregate DMARC reports to reports@example.com."

Explanation:

v=DMARC1: Indicates the DMARC version.
p=reject: Policy to apply to emails that fail DMARC. Other values can be none or quarantine.
rua=mailto:reports@example.com: Address where aggregate DMARC reports should be sent.
ruf=mailto:forensic@example.com: Address where forensic (detailed) DMARC reports should be sent.
pct=100: Percentage of emails to which the DMARC policy should be applied.
aspf=r: SPF alignment mode. 'r' means relaxed (default), while 's' stands for strict.
adkim=r: DKIM alignment mode. 'r' is for relaxed, and 's' is for strict.

Once an email is received, the receiving server validates it against SPF and DKIM. For DMARC to pass, at least one of these, SPF or DKIM, must be valid and aligned with the claimed domain. Emails failing this check are dealt with according to the DMARC policy — they might be rejected, quarantined, or let through with no action.

The Takeaway

Sophisticated phishing attacks make trust paramount in digital communication. DMARC goes beyond email security — it ensures genuine emails reach recipients while malicious ones stay blocked. For organizations and individuals alike, implementing DMARC moves us toward safer digital communication.

When reviewing your email security measures, remember: DMARC is not optional — it is necessary.

Further Resources and Tools

For deeper exploration of DMARC:

DMARC Guide: A comprehensive guide by the Global Cyber Alliance that covers the nuances of DMARC in detail. Check it out here.
DMARC Setup Checker: An invaluable tool provided by the Global Cyber Alliance. It not only checks if your DMARC is set up correctly but also offers tips on rectifications if needed. Try the tool here.

Check for undefined in JavaScript

contact@magarcia.io — Sun, 03 May 2020 00:00:00 GMT

If you write JavaScript regularly, you've likely needed to check whether a variable is undefined.

But, what is the best way to do it?

The intuitive way

Any programmer experienced in other languages will intuit:

if (x === undefined) { ... }

This works without problems--almost.

Direct comparison with undefined works in all modern browsers. Old browsers, however, allowed reassignment:

undefined = "new value";

With this reassignment, direct comparison fails.

ECMAScript 5 fixed this in 2009:

15.1.1.3 undefined
The value of undefined is undefined (see 8.1). This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.

The “safe” way

If you support old browsers and worry about undefined reassignment, use alternative methods.

Reading the type

The typeof operator returns "undefined" for undefined values:

if (typeof x === "undefined") { ... }

Note: typeof does not throw an error for undeclared variables.

Using `void`

The void operator also returns undefined:

if (x === void(0)) { ... }

The zero has no special meaning. As MDN states:

The void operator evaluates the given expression and then returns undefined.

Which way is better

As a consultant, I learned the best answer: it depends. Here are some tips.

Follow existing codebase conventions. For new code running only on modern browsers, use direct comparison--it's clear and readable even for JavaScript beginners. For old browser support, create an isUndefined function with your preferred method inside. This expresses intent clearly.

The power of MVP

contact@magarcia.io — Wed, 29 Jan 2020 00:00:00 GMT

Much has been written about minimum viable products (MVP). I doubt I can add new insights, but I can share my perspective from an experience with one client.

A minimum viable product (MVP) is a version of a product with just enough features to satisfy early customers and provide feedback for future product development.

Wikipedia

Let me set the scene. The client was a leading European real estate company—though the domain matters little here. The product team envisioned a complex product to sell to their customers. To gauge user acceptance, we ran multiple A/B tests to find the most successful approach. The product was straightforward to implement, but deciding which users should see what was another story. We had to account for user location, search location, last visit, and more. The number of variables was large, so we ran the tests for nearly half a year to gather meaningful data.

This kind of experiment requires proper metrics, so we measured everything. Once the test finished, the data analysis team did their job—and the results disappointed us. They fell far short of expectations. Yet one small part of the product resonated strongly with users, and a month later the product team built a new product around it.

Now the real story begins. The new product lacked the complex rules of the previous one: no location logic, no visit history, no search patterns. Customers would get a special section on the page to showcase their products and share it as they liked. Since the user-facing part already existed from the previous test, it was time to make it real and start selling.

We held a meeting to define the architecture and implementation plan. Two engineering teams, the head of technology, and the product owner—about 14 people in virtual rooms across countries—discussed the best approach and estimated completion. Someone pointed out that since customers had to purchase the product, we'd need to involve the commerce team. The products team would create a new microservice, and the website team would consume and process that data to enable the product for each customer.

Complexity piled up again. Initial estimates put delivery at three months minimum—probably more, given coordination across engineering, marketing, and design. Listening to these discussions, I asked the product owner: "How will you sell this product in the short term?" The answer unlocked an easier path. Initially, a small sales team would contact only the most important customers. After that, they'd evaluate which other customers might be interested.

With this information, I proposed an unorthodox approach. Instead of building the complex system, coordinating multiple teams, and blocking the launch until everything was done—why not hardcode customer IDs? A few lines of logic, and we're done. Each time the product sold, someone would email the team, and we'd add the ID in minutes. This solution doesn't scale, but it wasn't meant to. Since sales would be handled manually at first, we could control the pace of customer acquisition.

Everyone received the proposal well. We could start selling earlier and relieve pressure on the engineering teams. Within one week we had the product in place and sold to the first customer. Over the following months, the teams worked at a relaxed pace on the final implementation—one that would eliminate manual steps.

That's the story. Here's what I learned:

Keep the implementation as simple as possible. You'll reach the market earlier and may relax some deadlines along the way.
Involve engineering teams early in product definition. Different perspectives surface better solutions.
Share the full project vision with engineers, not just their piece. Context shapes better architecture.

In conclusion: I'll keep practicing what I consider one of the most important traits in a developer—laziness. That instinct drives me to find the simplest, fastest way to solve a problem.

SOLID - Principles of Object-Oriented Design

contact@magarcia.io — Sat, 07 Dec 2019 00:00:00 GMT

This article is based on the work done by Samuel Oloruntoba in his article S.O.L.I.D: The First 5 Principles of Object Oriented Design but using TypeScript instead of PHP for the examples.

SOLID is an acronym for the first five principles of the article Principles of Object-Oriented Design by Robert C. Martin.

These principles help you write maintainable and extensible code. They also help you catch code smells, refactor easily, and practice agile development.

S stands for SRP - Single Responsibility Principle
O stands for OCP - Open-Closed Principle
L stands for LSP - Liskov Substitution Principle
I stands for ISP - Interface Segregation Principle
D stands for DIP - Dependency Inversion Principle

SRP - Single Responsibility Principle

A software entity (classes, modules, functions, etc.) should have one, and only one, reason to change.

An entity should do only one thing. Single responsibility means work in isolation. If a software entity performs calculations, the only reason to change it is when those calculations need to change.

An example clarifies this principle. Say we must implement an application that calculates the total area of given shapes and prints the result. Let's start with our shape classes:

class Circle {
  public readonly radius: number;

  constructor(radius: number) {
    this.radius = radius;
  }
}

class Square {
  public readonly side: number;

  constructor(side: number) {
    this.side = side;
  }
}

Now we create an AreaCalculator class that is going to have the logic to sum the area of our shapes.

class AreaCalculator {
  public readonly shapes: Shape[];

  constructor(shapes: Shape[]) {
    this.shapes = shapes;
  }

  public sum(): number {
    // logic to sum the areas
  }

  public output(): string {
    return `Sum of the areas of provided shapes: ${this.sum()}`
  }

To use AreaCalculator, create an array of shapes, instantiate the class, and display the output.

const shapes: any[] = [new Circle(2), new Circle(3), new Square(5)];

const areas = new AreaCalculator(shapes);

console.log(areas.output());

This implementation has a problem: AreaCalculator handles both the area calculation logic and the output formatting. What if the user wants JSON output?

The Single Responsibility Principle addresses this. AreaCalculator should change only when the calculation logic changes, not when we want different output formats.

We fix this by creating a class whose sole responsibility is output formatting.

const shapes: any[] = [new Circle(2), new Circle(3), new Square(5)];

const areas = new AreaCalculator(shapes);
const output = new Outputter(areas);

console.log(output.text());
console.log(output.json());

Now each class has one responsibility. Changing the calculation logic affects only AreaCalculator; changing the output format affects only Outputter.

OCP - Open-Closed Principle

Software entities (classes, modules, functions, etc.) should be open for extension, but closed for modification.

Software entities should be easy to extend without modifying the entity itself.

Using the previous example, we want to add a new shape: the Triangle. First, examine the sum method in AreaCalculator.

class AreaCalculator {
  public readonly shapes: Shape[];

  constructor(shapes: Shape[]) {
    this.shapes = shapes;
  }

  public sum() {
    let sum: number = 0;

    for (let shape of this.shapes) {
      if (shape instanceof Circle) {
        sum += Math.PI * Math.pow(shape.radius, 2);
      } else if (shape instanceof Square) {
        sum += shape.side * shape.side;
      }
    }

    return sum;
  }
}

This violates the Open/Closed Principle: adding triangle support requires modifying AreaCalculator with a new else if block.

To fix this, move the area calculation to each shape class and define an interface that describes what a shape can do.

interface Shape {
  area(): number;
}

class Circle implements Shape {
  public readonly radius: number;

  constructor(radius: number) {
    this.radius = radius;
  }

  public area(): number {
    return Math.PI * Math.pow(this.radius, 2);
  }
}

Now AreaCalculator accepts any shape that implements the Shape interface:

class AreaCalculator {
  public readonly shapes: Shape[];

  constructor(shapes: Shape[]) {
    this.shapes = shapes;
  }

  public sum(): number {
    let sum: number = 0;

    for (let shape of this.shapes) {
      sum += shape.area();
    }

    return sum;
  }
}

LSP - Liskov Substitution Principle

Derived class must be substitutable for their base class.

Objects in a program should be replaceable with instances of their subtypes without altering the program's correctness. A subclass must preserve the behavior and state semantics of its parent abstraction.

Continuing with the AreaCalculator class, now we want to create a VolumeCalculator class that extends AreaCalculator:

class VolumeCalculator extends AreaCalculator {
  public readonly shapes: Shape[];

  constructor(shapes: Shape[]) {
    this.shapes = shapes;
  }

  public sum(): number[] {
    // logic to calculate the volumes and then return
    // and array of output
  }
}

A detailed Outputter class clarifies this example:

class Outputer {

  private calculator;

  constructor(calculator: AreaCalculator) {
    this.calculator = calculator;
  }

  public json(): string {
    return JSON.stringify({
      sum: this.calculator.sum();
    })
  }

  public text(): string {
    return `Sum of provided shapes: ${this.calculator.sum()}`;
  }
}

With this implementation, if we try to run a code like this:

const areas = new AreaCalculator(shapes2D);
const volumes = new VolumeCalculator(shapes3D);

console.log("Areas - ", new Ouputter(areas).text());
console.log("Volumes - ", new Ouputter(volumes).text());

The program runs but produces inconsistent output: Areas - Sum of provided shapes: 42 versus Volumes - Sum of provided shapes: 13, 15, 14. This breaks our expectations.

The Liskov Substitution Principle is violated: VolumeCalculator.sum() returns an array of numbers, while AreaCalculator.sum() returns a single number.

The fix: VolumeCalculator.sum() must return a number, not an array.

class VolumeCalculator extends AreaCalculator {

  // constructor

  public function sum(): number {
      // logic to calculate the volumes and then return
      // and array of output
      return sum;
  }
}

ISP - Interface Segregation Principle

Make fine grained interfaces that are client specific.

Keep interfaces small so clients implement only the methods they need.

{/* REVIEW: This explanation could be more detailed */}

Our shape interface now includes volume calculation:

interface Shape {
  area(): number;
  volume(): number;
}

But Square is a 2D shape with no volume, yet the interface forces it to implement a volume method.

The Interface Segregation Principle leads us to split Shape into separate interfaces for 2D and 3D shapes:

interface Shape2D {
  area(): number;
}

interface Shape3D {
  volume(): number;
}

class Cuboid implements Shape2D, Shape3D {
  public area(): number {
    // calculate the surface area of the cuboid
  }

  public volume(): number {
    // calculate the volume of the cuboid
  }
}

DIP - Dependency Inversion Principle

Depend on abstractions, not on concretions.

High-level modules should depend on abstractions, not on low-level modules.

{/* REVIEW: This explanation could be more detailed */}

This principle enables decoupling. Consider a ShapeManager class that saves shapes:

class ShapeManager {
  private database;

  constructor(database: MySQL) {
    this.database = database;
  }

  public load(name: string): Shape {}
}

ShapeManager (high-level) depends directly on MySQL (low-level), violating the Dependency Inversion Principle.

Changing databases would require editing ShapeManager, also violating the Open-Closed Principle. The solution: depend on a Database interface instead:

interface Database {
  connect(): Connection;
}

class MySQL implements Database {
  public connect(): Connetion {
    // creates a connection
  }
}

class ShapeManager {
  private database;

  constructor(database: Database) {
    this.database = database;
  }

  public load(name: string): Shape {}
}

And now our high-level and low-level modules are depending on abstractions.

Conclusion

The SOLID principles may seem difficult at first, and knowing when to apply them takes practice. But with experience, applying these principles becomes natural and intuitive.

Adaptive Media Serving using Service Workers

contact@magarcia.io — Mon, 17 Jun 2019 00:00:00 GMT

Pairing with @Ester Martí

Visiting a website over a slow network connection takes ages to load, making the experience painful or impossible.

Web developers often forget load performance while adding fancy features. But users likely browse on mid-range or low-end mobile devices with 3G connections at best--not the latest MacBook Pro on gigabit fiber.

In 2018, 52.2% of all global web pages were served to mobile phones.

Performance matters, and media delivery consumes the most resources. We'll adapt media delivery based on network connection using the Network Information API. This improves an experiment I built with @Eduardo Aquiles as a React component, similar to Max Böck's article on connection-aware components--but using service workers.

The Network Information API

The Network Information API is a draft specification exposing device connection information to JavaScript.

The interface provides several network attributes. The most relevant here:

type: The connection type that the user agent is using. (e.g. ‘wifi’, ‘cellular’, ‘ethernet’, etc.)
effectiveType The effective connection type that is determined using a combination of recently observed rtt and downlink values. (see table)
saveData Indicates when the user requested a reduced data usage.

effectiveType values

<table> <thead> <tr> <th>ECT</th> <th>Minimum RTT (ms)</th> <th>Maximum downlink (Kbps)</th> <th>Explanation</th> </tr> </thead> <tbody> <tr> <td data-column="ECT">slow‑2g</td> <td data-column="RTT">2000</td> <td data-column="Downlink">50</td> <td data-column="Explanation"> The network is suited for small transfers only such as text-only pages. </td> </tr> <tr> <td data-column="ECT">2g</td> <td data-column="RTT">1400</td> <td data-column="Downlink">70</td> <td data-column="Explanation"> The network is suited for transfers of small images. </td> </tr> <tr> <td data-column="ECT">3g</td> <td data-column="RTT">270</td> <td data-column="Downlink">700</td> <td data-column="Explanation"> The network is suited for transfers of large assets such as high resolution images, audio, and SD video. </td> </tr> <tr> <td data-column="ECT">4g</td> <td data-column="RTT">0</td> <td data-column="Downlink">∞</td> <td data-column="Explanation"> The network is suited for HD video, real-time video, etc. </td> </tr> </tbody> <caption align="bottom"> Table of{" "} <a href="http://wicg.github.io/netinfo/#dfn-effective-connection-type"> effective connection types (ECT) </a> </caption> </table>

Browser support

The API lacks full browser support but works in the most popular mobile browsers--where this technique has the greatest impact.

In fact, 70% of mobile users have this API enabled on their device.

Adaptive Media Serving

We'll serve different media resources based on effectiveType. "Different media" could mean switching between HD video, HD image, or low-quality image, as Addy Osmani suggests.

This example uses different compression levels for the same image.

First, get the proper quality based on network conditions:

function getMediaQuality() {
  const connection =
    navigator.connection ||
    navigator.mozConnection ||
    navigator.webkitConnection;

  if (!connection) {
    return "medium";
  }

  switch (connection.effectiveType) {
    case "slow-2g":
    case "2g":
      return "low";
    case "3g":
      return "medium";
    case "4g":
      return "high";
    default:
      return "low";
  }
}

Imagine an image server accepting a quality query parameter (low, medium, or high). Set the quality in the src attribute:

<img src="http://images.magarcia.io/cute_cat?quality=low" alt="Cute cat" />

const images = document.querySelectorAll("img");
images.forEach((img) => {
  img.src = img.src.replace("low", getMediaQuality());
});

The default quality is low, so devices load the low-quality image first, then upgrade on high-speed connections.

The JavaScript gets all images and replaces the quality parameter based on getMediaQuality. For low quality, no additional requests occur. For medium or high, two requests happen: one for low when parsing the img tag, another for better quality when JavaScript executes.

This improves load times on slow networks but doubles requests on fast connections, consuming extra data.

Using Service Workers

Service workers solve the double-request problem by intercepting browser requests and replacing them with the appropriate quality.

First, register the service worker:

if ("serviceWorker" in navigator) {
  window.addEventListener("load", function () {
    navigator.serviceWorker.register("/sw.js").then(
      function (registration) {
        console.log(
          "ServiceWorker registration successful with scope: ",
          registration.scope,
        );
      },
      function (err) {
        console.log("ServiceWorker registration failed: ", err);
      },
    );
  });
}

Add a fetch event listener that appends the right quality parameter to image requests:

self.addEventListener("fetch", function (event) {
  if (/\.jpg$|.png$|.webp$/.test(event.request.url)) {
    const url = event.request.url + `?quality=${getMediaQuality()}`;
    event.respondWith(fetch(url));
  }
});

Now omit the quality parameter from img tags--the service worker handles it:

<img src=“http://images.magarcia.io/cute_cat” alt=“Cute cat”/>

The code

Find the complete, cleaner code in this GitHub repo.

BLoC Pattern with React Hooks

contact@magarcia.io — Mon, 18 Feb 2019 00:00:00 GMT

The BLoC Pattern has been designed by Paolo Soares and Cong Hui, from Google and first presented during the DartConf 2018 (January 23-24, 2018). See the video on YouTube.

BLoC stands for Business Logic Component. Initially conceived to share code between Flutter and Angular Dart, it works independently of platform: web application, mobile application, or back-end.

It offers an alternative to the Redux port for flutter using Dart streams. We'll use Observables from RxJS, though xstream works equally well.

In short, the BLoC will:

contain business logic (ideally in bigger applications we will have multiple BLoCs)
rely exclusively on the use of Observables for both input (Observer) and output (Observable)
remain platform independent
remain environment independent

How BLoC works?

Others have explained BLoC better than I will here, so I'll cover just the basics.

The BLoC holds business logic; components know nothing about its internals. Components send events to the BLoC via Observers and receive notifications via Observables.

Implementing the BLoC

Here is a basic TypeScript search BLoC using RxJS:

export class SearchBloc {
  private _results$: Observable<string[]>;
  private _preamble$: Observable<string>;
  private _query$ = new BehaviorSubject<string>("");

  constructor(private api: API) {
    this._results$ = this._query$.pipe(
      switchMap((query) => {
        return observableFrom(this.api.search(query));
      }),
    );
    this._preamble$ = this.results$.pipe(
      withLatestFrom(this._query$, (_, q) => {
        return q ? `Results for ${q}` : "All results";
      }),
    );
  }

  get results$(): Observable<string[]> {
    return this._results$;
  }

  get preamble$(): Observable<string> {
    return this._preamble$;
  }

  get query(): Observer<string> {
    return this._query$;
  }

  dispose() {
    this._query$.complete();
  }
}

results$ and preamble$ expose asynchronous values that change when query changes.

query exposes an Observer<string> for components to add new values. Inside SearchBloc, _query$: BehaviorSubject<string> serves as the stream source, and the constructor declares _results$ and _preamble$ to respond to _query$.

Using it on React

To use it in React, create a BLoC instance and share it with child components via React context.

const searchBloc = new SearchBloc(new API());
const SearchContext = React.createContext(searchBloc);

Expose it using the context provider:

const App = () => {
  const searchBloc = useContext(SearchContext);

  useEffect(() => {
    return searchBloc.dispose;
  }, [searchBloc]);

  return (
    <SearchContext.Provider>
      <SearchInput />
      <ResultList />
    </SearchContext.Provider>
  );
};

The useEffect returns the dispose method, completing the observer when the component unmounts.

Publish changes to the BLoC from the SearchInput component:

const SearchInput = () => {
  const searchBloc = useContext(SearchContext);
  const [query, setQuery] = useState("");

  useEffect(() => {
    searchBloc.query.next(query);
  }, [searchBloc, query]);

  return (
    <input
      type="text"
      name="Search"
      value={query}
      onChange={({ target }) => setQuery(target.value)}
    />
  );
};

We get the BLoC via useContext, then useEffect publishes each query change to the BLoC.

Now the ResultList:

const ResultList = () => {
  const searchBloc = useContext(SearchContext);
  const [results, setResults] = useState([]);

  useEffect(() => {
    return searchBloc.results$.subscribe(setResults);
  }, [searchBloc]);

  return (
    <div>
      {results.map(({ id, name }) => (
        <div key={id}>{name}</div>
      ))}
    </div>
  );
};

We use useContext to get the BLoC, then useEffect subscribes to results$ changes to update local state. Returning the subscription unsubscribes when the component unmounts.

Final thoughts

The final code is straightforward with basic knowledge of Observables and hooks. The code is readable and keeps business logic outside components. We must remember to unsubscribe from observables and dispose the BLoC on unmount, but custom hooks like useBlocObservable and useBlocObserver could solve this. I plan to try this in a side project where I use this pattern.

Refactor TodoMVC with Redux Starter Kit

contact@magarcia.io — Sat, 26 Jan 2019 00:00:00 GMT

I've worked with React for over two years. I started on a large project that already used Redux. Jumping into so much existing code felt overwhelming, especially with an unfamiliar framework. Over time, I grew comfortable and experienced.

Recently I discovered Redux Starter Kit from the Redux team. This toolset provides utilities that simplify working with Redux. One tool, createReducer, follows a pattern I've used for a while. It reduces boilerplate and speeds up development, especially in new projects.

To learn the toolset, I migrated an existing Redux codebase. For my example, I chose the omnipresent TodoMVC, specifically the version from the Redux repository.

Starting point

The app has two main reducers: visibilityFilter and todos. Each has its own actions, action creators, and selectors.

Visibility Filter

I started with the simpler reducer, then moved to the more complex one.

Reducer

The reducer from the Redux example is already simple and clear.

// reducers/visibilityFilter.js
import { SET_VISIBILITY_FILTER } from "../constants/ActionTypes";
import { SHOW_ALL } from "../constants/TodoFilters";

export default (state = SHOW_ALL, action) => {
  switch (action.type) {
    case SET_VISIBILITY_FILTER:
      return action.filter;
    default:
      return state;
  }
};

Redux Starter Kit provides createReducer for creating reducers. As I mentioned, I already use this pattern and find it effective.

Instead of creating a reducer with a switch case statement, you pass the initial state as the first parameter and an object mapping action types to reducer functions ((state, action) => { /* reducer code */}).

It reduces boilerplate and automatically handles the default case with return state. The biggest benefit: improved readability.

Here is the visibility filter reducer using createReducer:

// reducers/visibilityFilter.js
import { createReducer } from "redux-starter-kit";
import { SET_VISIBILITY_FILTER } from "../constants/ActionTypes";
import { SHOW_ALL } from "../constants/TodoFilters";

export default createReducer(SHOW_ALL, {
  [SET_VISIBILITY_FILTER]: (state, action) => action.filter,
});

Actions creators

Now for the actions. The visibility filter has one action, SET_VISIBILITY_FILTER, with a simple creator:

// actions/index.js
import * as types from "../constants/ActionTypes";

/* ... Other actions ...*/
export const setVisibilityFilter = (filter) => ({
  type: types.SET_VISIBILITY_FILTER,
  filter,
});

The toolset provides createAction, which takes only the action type as a parameter and returns an action creator.

// actions/index.js
import * as types from "../constants/ActionTypes";

/* ... Other actions ...*/
export const setVisibilityFilter = createAction(types.SET_VISIBILITY_FILTER);

This action creator accepts optional parameters. Any argument becomes the action's payload:

const setVisibilityFilter = createAction("SET_VISIBILITY_FILTER");

let action = setVisibilityFilter();
// { type: 'SET_VISIBILITY_FILTER' }

action = setVisibilityFilter("SHOW_COMPLETED");
// returns { type: 'SET_VISIBILITY_FILTER', payload: 'SHOW_COMPLETED' }

setVisibilityFilter.toString();
// 'SET_VISIBILITY_FILTER'

Now the filter uses the payload key instead of filter. This requires a small reducer change:

// reducers/visibilityFilter.js
import { createReducer } from "redux-starter-kit";
import { SET_VISIBILITY_FILTER } from "../constants/ActionTypes";
import { SHOW_ALL } from "../constants/TodoFilters";

export default createReducer(SHOW_ALL, {
  [SET_VISIBILITY_FILTER]: (state, action) => action.payload,
});

Selectors

Selectors are one of the best choices when working with React. They let you refactor state structure without changing every component that consumes it.

The visibility filter selector is straightforward:

// selectors/index.js
const getVisibilityFilter = (state) => state.visibilityFilter;

/* ... Other selectors ...*/

Using createSelector adds a bit more code, but the payoff comes soon. Keep reading.

// selectors/index.js
import { createSelector } from "redux-starter-kit";

const getVisibilityFilter = createSelector(["visibilityFilter"]);

/* ... Other selectors ...*/

Slices

So far, we've replaced simple functions with simpler ones using various creators. Now comes the real power of the toolset: createSlice.

createSlice accepts an initial state, reducer functions, and an optional slice name. It automatically generates action creators, action types, and selectors.

Now we can discard all the previous code.

Creating a slice for the visibility filter is clean and eliminates significant boilerplate.

// ducks/visibilityFilter.js
import { createSlice } from "redux-starter-kit";

export default createSlice({
  slice: "visibilityFilter",
  initialState: SHOW_ALL,
  reducers: {
    setVisibilityFilter: (state, action) => action.payload,
  },
});

The result is a single object containing everything needed to work with Redux:

const reducer = combineReducers({
  visibilityFilter: visibilityFilter.reducer,
});

const store = createStore(reducer);

store.dispatch(visibilityFilter.actions.setVisibilityFilter(SHOW_COMPLETED));
// -> { visibilityFilter: 'SHOW_COMPLETED' }

const state = store.getState();
console.log(visibilityFilter.selectors.getVisibilityFilter(state));
// -> SHOW_COMPLETED

See all changes so far in this commit.

Todos

The todos reducer is more complex, so I'll explain the final result rather than each step. See the complete code here.

First, define the initial state:

// ducks/todos.js
const initialState = [
  {
    text: "Use Redux",
    completed: false,
    id: 0,
  },
];

To improve readability, I extracted each reducer action into its own function:

// ducks/todos.js
const addTodo = (state, action) => [
  ...state,
  {
    id: state.reduce((maxId, todo) => Math.max(todo.id, maxId), -1) + 1,
    completed: false,
    text: action.payload.text,
  },
];

const deleteTodo = (state, action) =>
  state.filter((todo) => todo.id !== action.payload.id);

const editTodo = (state, action) =>
  state.map((todo) =>
    todo.id === action.payload.id
      ? { ...todo, text: action.payload.text }
      : todo,
  );

const completeTodo = (state, action) =>
  state.map((todo) =>
    todo.id === action.payload.id
      ? { ...todo, completed: !todo.completed }
      : todo,
  );
const completeAllTodos = (state) => {
  const areAllMarked = state.every((todo) => todo.completed);
  return state.map((todo) => ({
    ...todo,
    completed: !areAllMarked,
  }));
};

const clearCompleted = (state) =>
  state.filter((todo) => todo.completed === false);

Now combine them in a slice:

// ducks/todos.js
const todos = createSlice({
  slice: "todos",
  initialState,
  reducers: {
    add: addTodo,
    delete: deleteTodo,
    edit: editTodo,
    complete: completeTodo,
    completeAll: completeAllTodos,
    clearCompleted: clearCompleted,
  },
});

By default, createSlice selectors simply return state values (e.g., todos.selectors.getTodos). This application needs more complex selectors.

For example, getVisibleTodos needs both the visibility filter and todos. createSelector takes an array of selectors (or state paths) as its first parameter and a function implementing the selection logic as its second.

// ducks/todos.js
const { getVisibilityFilter } = visibilityFilter.selectors;

todos.selectors.getVisibleTodos = createSelector(
  [getVisibilityFilter, todos.selectors.getTodos],
  (visibilityFilter, todos) => {
    switch (visibilityFilter) {
      case SHOW_ALL:
        return todos;
      case SHOW_COMPLETED:
        return todos.filter((t) => t.completed);
      case SHOW_ACTIVE:
        return todos.filter((t) => !t.completed);
      default:
        throw new Error("Unknown filter: " + visibilityFilter);
    }
  },
);

todos.selectors.getCompletedTodoCount = createSelector(
  [todos.selectors.getTodos],
  (todos) =>
    todos.reduce((count, todo) => (todo.completed ? count + 1 : count), 0),
);

I added the new selectors to the todos.selectors object, keeping all selectors in one place.

Create Store

The library also provides configureStore and getDefaultMiddleware.

configureStore wraps Redux's createStore. It offers the same functionality with a cleaner API--enabling developer tools requires just a boolean.

getDefaultMiddleware returns [immutableStateInvariant, thunk, serializableStateInvariant] in development and [thunk] in production.

redux-immutable-state-invariant: Detects mutations in reducers during dispatch and between dispatches (in selectors or components).
serializable-state-invariant-middleware: Checks state and actions for non-serializable values like functions and Promises.

// store.js
import { configureStore, getDefaultMiddleware } from "redux-starter-kit";
import { combineReducers } from "redux";
import { visibilityFilter, todos } from "./ducks";

const preloadedState = {
  todos: [
    {
      text: "Use Redux",
      completed: false,
      id: 0,
    },
  ],
};

const reducer = combineReducers({
  todos: todos.reducer,
  visibilityFilter: visibilityFilter.reducer,
});

const middleware = [...getDefaultMiddleware()];

export const store = configureStore({
  reducer,
  middleware,
  devTools: process.env.NODE_ENV !== "production",
  preloadedState,
});

Final thoughts

Redux Starter Kit reduces boilerplate, making code cleaner and easier to understand. It also speeds up development.

Source Code: https://github.com/magarcia/todomvc-redux-starter-kit

$watch with Angular 2

contact@magarcia.io — Mon, 04 Jul 2016 00:00:00 GMT

In my previous post, I was talking about how to implement events from Angular 1 in Angular 2. But in the snippet of code that I use as an example we can find another thing that not exists in Angular 2: $watch.

I start defining the problem. We can have a directive or Angular 1 component like that:

var module = angular.module("myApp");

module.directive('exampleDirective', function () {
  return {
    template: '<div>{{internalVar}}</div>',
    scope: {
      externalVar: "="
    },
    controller: function(scope, element) {
      scope.$watch('externalVar', function(newVal, oldVal) {
        if (newVal !== oldVal) {
          scope.internalVar = newVal;
        }
      });
    }
});

If we want to migrate this code to Angular 2 we find a trouble: the new Angular don't have scope, so it don't have $watch. How we can watch a directive attribute? The solution is the set syntax from ES6.

The set syntax binds an object property to a function to be called when there is an attempt to set that property.

From MDN

So we can bind the input for a component to a function that does the same as the $watch function.

import { Component, Input } from "@angular/core";

@Component({
  selector: "example-component",
})
export class ExampleComponent {
  public internalVal = null;

  constructor() {}

  @Input("externalVal")
  set updateInternalVal(externalVal) {
    this.internalVal = externalVal;
  }
}

Events in Angular2

contact@magarcia.io — Sun, 03 Jul 2016 00:00:00 GMT

During the feed component migration, I encountered code I did not know how to port to Angular 2:

if (!feed.isLocalScreen) {
  // Until this timeout is reached, the "you are muted" notification
  // will not be displayed again
  var mutedWarningTimeout = now();

  scope.$on("muted.byRequest", function () {
    mutedWarningTimeout = secondsFromNow(3);
    MuteNotifier.muted();
  });

  scope.$on("muted.byUser", function () {
    // Reset the warning timeout
    mutedWarningTimeout = now();
  });

  scope.$on("muted.Join", function () {
    mutedWarningTimeout = now();
    MuteNotifier.joinedMuted();
  });

  scope.$watch("vm.feed.isVoiceDetected()", function (newVal) {
    // Display warning only if muted (check for false, undefined means
    // still connecting) and the timeout has been reached
    if (
      newVal &&
      feed.getAudioEnabled() === false &&
      now() > mutedWarningTimeout
    ) {
      MuteNotifier.speaking();
      mutedWarningTimeout = secondsFromNow(60);
    }
  });
}

When the condition is true, the directive listens for muted.byRequest, muted.byUser, and muted.Join events. The event-handling code is straightforward (ignoring $watch for now).

But, wait a minute, I have read the documentation of Angular 2 like a hundred times and I don't remember nothing about "events" with Angular 1.X style. That's because it not exist. Angular 2 don't have a way to make events like in Angular 1, so I have to find a solution. After a search for a solution, I found this entry in laco's blog.

Broadcaster

Basically, the idea is to make a service that implements the $broadcast and $on a method as we had in $rootScope. To do this we use Observables, very importants in Angular 2, and for this case, we use a Subject.

import { Subject } from "rxjs/Subject";
import { Observable } from "rxjs/Observable";
import "rxjs/add/operator/filter";
import "rxjs/add/operator/map";

interface BroadcastEvent {
  key: any;
  data?: any;
}

export class Broadcaster {
  private _eventBus: Subject<BroadcastEvent>;

  constructor() {
    this._eventBus = new Subject<BroadcastEvent>();
  }

  broadcast(key: any, data?: any) {
    this._eventBus.next({ key, data });
  }

  on<T>(key: any): Observable<T> {
    return this._eventBus
      .asObservable()
      .filter((event) => event.key === key)
      .map((event) => <T>event.data);
  }
}

So, now we can start to use events like in the example:

// child.ts
@Component({
    selector: 'child'
})
export class ChildComponent {
  constructor(private broadcaster: Broadcaster) {
  }

  registerStringBroadcast() {
    this.broadcaster.on<string>('MyEvent')
      .subscribe(message => {
        ...
      });
  }

  emitStringBroadcast() {
    this.broadcaster.broadcast('MyEvent', 'some message');
  }
}

How I solved the problem?

I didn't. These events are only to show the user information pop-ups about when he is muted, so it's not a critical feature. By now these events are fired and listen in different components, and some of it still implemented in Angular 1.4.

This is a solution I want to share with you, but I'm not sure if this will be the way that I will use to solve the problem. Because these events probably won't be necessary when I reimplement the MuteNotifier.

Midterm

contact@magarcia.io — Wed, 29 Jun 2016 00:00:00 GMT

GSoC midterm just passed. Time to review the work since the project started. After these weeks working on Jangouts and using it regularly for follow-up meetings, I love it as if it were my own. Working on this project is rewarding: small enough to grasp, yet backed by a growing community. Jangouts remains in an early stage but has great potential.

Work done

I missed my initial timeline, but I am close and the hardest part is over. Jangouts now uses TypeScript with a new build/development process and runs as a hybrid Angular 1.x/Angular 2 application.

Jangouts is composed of different components:

browser-info
chat - Migrated
feed - Almost migrated
footer - Migrated
notifier
room
router
screen-share
user
videochat
signin

Each component migration involves conversion from Angular 1 to 2 and tests targeting near 100% coverage. The most complex components to migrate are feed and room because they handle video rendering and Janus backend communication. The router will likely require a complete rewrite for the new Angular 2 router.

Mentors

I have only good things to say about @ancorgs and @imobach. We hold daily meetings (when possible), and they give me feedback while allowing me freedom to make my own decisions (when I provide reasons).

Next steps

In the coming weeks, I will continue migrating components until Angular 1 can be removed. When migration finishes, Jangouts will be an Angular 2 project with a comprehensive test suite. My GSoC work will be complete, but I want to do more. Many things can improve:

Restructure the project by moving logic from components to services.
Leverage Observables better (probably using @ngrx/store)
Improve UI and mobile UX using progressive web app concepts.
Improve communication and community (project webpage, better contribution docs, etc.)

AngularBeers with Miško Hevery

contact@magarcia.io — Sun, 26 Jun 2016 00:00:00 GMT

Last Tuesday I attended a talk by Miško Hevery about Angular 2, organized by AngularBeers. The key takeaway: Angular is evolving from a frontend framework into a full platform.

Sara (a good coworker and better friend), Miško and me

Two upcoming features will make Angular 2 particularly powerful.

Offline compile

Templates have been error-prone since Angular 1. Even with TypeScript or lint tools, template errors remain undetected until runtime. Angular 1.X compiles templates each time they render.

Angular 2 (without offline compile) compiles templates only once. With offline compiling, templates compile to JavaScript at build time, eliminating browser compilation. The benefits: static type-checking of templates with TypeScript, no runtime compilation, and smaller library size.

Angular Universal

Universal (isomorphic) JavaScript support for Angular 2.

Angular Universal enables server-side Angular 2, providing several advantages:

Better Perceived Performance: Users instantly see a server-rendered view, improving perceived performance and user experience.
Optimized for Search Engines: Server-side pre-rendering ensures all search engines can access your content.
Site Preview: Facebook, Twitter, and other social media apps correctly display preview images. (I have struggled with this problem before---it is frustrating.)

Moving big parts to Angular 2

contact@magarcia.io — Sun, 12 Jun 2016 00:00:00 GMT

In a previous post I explained how I converted Jangouts to a hybrid Angular 1+2 application. This approach, instead of a full migration, has two objectives. First, testing functionality becomes easier since Jangouts remains runnable throughout. Second, if I cannot finish the migration, others can continue the work. I hope this fallback proves unnecessary.

With the hybrid approach in place, this week I migrated several components to Angular 2. I started with the Chat component---more complex than the Footer, but manageable for these early stages.

Migrating subcomponents

The Jangouts Chat component has three subcomponents besides the main component:

chat-message: Renders user messages.
log-entry: Renders system notifications (like "User X has joined").
chat-form: Handles message input.

These subcomponents are simple: each has a minimal component class and a template. The key change: styles moved from the main scss file to independent files for each subcomponent. This leverages Angular 2 View Encapsulation, ensuring styles apply only to their component.

During the chat-message migration, I encountered a problem with ngEmbed, the library providing a directive to render user messages. This directive enables emojis and embedded links, images, and videos. The library lacks Angular 2 support, so I tried the Angular 2 Upgrade Adapter, but encountered a strange error.

Investigation revealed that ngEmbed uses a function as its templateUrl attribute (allowed in Angular 1). However, my current Angular 2 version's upgrade adapter lacks support for function-based templateUrl. The Angular 2 master branch includes this support, but no released version incorporates it yet. After discussing with my mentors, we decided to disable this functionality and continue the migration.

I hope to re-enable it in the future.

Differentiate between component and directive

Migrating the main component proved more complex. It displays all messages (user and system) in a view that auto-scrolls when new messages arrive. In old Jangouts, one directive both rendered the message list and controlled auto-scrolling. Angular 2 requires a different approach: components always have templates and never interact with the DOM directly; directives never have templates but can interact with the DOM.

This meant splitting the main chat component into two parts:

A component to render the message list.
A directive to handle auto-scrolling.

After migration, the component renders the message list and contains the directive that handles auto-scrolling.

Putting all together

During subcomponent migration, I downgraded each one to Angular 1 compatibility using Angular 2's adapter and tested manually with the old main component. When I migrated the main component, its code became pure Angular 2 (without downgraded subcomponents). Only the main chat component needed downgrading for Angular 1 compatibility.

Applying the correct application structure

This week's changes extended beyond code. I also restructured the application following the style guide recommendations. Before migration, the structure was:

src
└── app
    ├── adapter.ts
    ├── variables.scss
    ├── index.scss
    ├── vendor.scss
    ├── index.ts
    ├── components
    │   ├── chat
    │   │   ├── chat-form.directive.html
    │   │   ├── chat-form.directive.js
    │   │   ├── chat.directive.html
    │   │   ├── chat.directive.js
    │   │   ├── chat-message.directive.html
    │   │   ├── chat-message.directive.js
    │   │   ├── log-entry.directive.html
    │   │   └── log-entry.directive.html
    │   ├── footer
    │   │   ├── footer.directive.html
    │   │   └── footer.directive.js
    │   └── [...]
    └── [...]

After the changes:

src
└── app
    ├── adapter.ts
    ├── variables.scss
    ├── index.scss
    ├── vendor.scss
    ├── index.ts
    ├── chat
    │   ├── index.ts
    │   ├── chat.component.html
    │   ├── chat.component.scss
    │   ├── chat.component.spec.ts
    │   ├── chat.component.ts
    │   ├── chat-form
    │   │   ├── chat-form.component.html
    │   │   ├── chat-form.component.spec.ts
    │   │   ├── chat-form.component.ts
    │   │   └── index.ts
    │   ├── chat-message
    │   │   ├── chat-message.component.html
    │   │   ├── chat-message.component.scss
    │   │   ├── chat-message.component.spec.ts
    │   │   ├── chat-message.component.ts
    │   │   └── index.ts
    │   ├── log-entry
    │   │   ├── index.ts
    │   │   ├── log-entry.component.html
    │   │   ├── log-entry.component.spec.ts
    │   │   └── log-entry.component.ts
    │   └── message-autoscroll.directive.ts
    ├── footer
    │   ├── footer.component.html
    │   ├── footer.component.scss
    │   ├── footer.component.spec.ts
    │   ├── footer.component.ts
    │   └── index.ts
    ├── components
    │   └──  [...] // This contains the not migrated code
    └── [...]

Currently working

I am now migrating the Feed component, one of the most complex in the application due to its many services handling video/audio streams.

I have moved all services and factories to Angular 2, but have not yet enabled Angular 1 compatibility. The reason: I want a comprehensive test suite covering these services before continuing the migration and integrating with the rest of the application.

Components migration started

contact@magarcia.io — Sun, 05 Jun 2016 00:00:00 GMT

Another week finished. Exams limited my progress this week, but the project still advanced significantly. Four key accomplishments:

Fixed the build process for production.
Added test runner.
Migrated the first component to Angular 2.
Added the first test for a migrated component.

Fixing the build process

Last week the development environment was ready, and presumably the distribution environment too. But throughout the week, I noticed the distributed build caused grid element issues inside the video chat room. After testing various Webpack configurations, I traced the problems to the uglify process.

The issue involved the video room's grid layout system, implemented with angular-gridster. The problem could stem from angular-gridster's styles or the JavaScript module. First, I tried importing the library's CSS directly without Webpack. That failed. The solution: use the source version instead of the minified version in vendors.ts.

Strange, since source and minified versions should behave identically. Regardless, the source version fixes the issue, and Webpack minifies all code anyway, including vendor.ts.

Adding test runner

Easier than expected. I used angular2-webpack-starter from @AngularClass as inspiration. After adapting their webpack.test.js and karma.conf.js files with minor changes, everything worked. Open source at its best: Don't Repeat Yourself.

Migrating the first component

I had awaited this moment since submitting my GSoC proposal. I started with the simplest component in Jangouts: the footer. It displays only a SUSE link and the Jangouts version.

In the old Jangouts (pre-migration), the footer consisted of a simple Angular 1 directive with a template and a jade template. Gulp rendered it, injecting the current version.

The new footer remains simple: a TypeScript file (component definition with an empty class) and an Angular 2 template. The key difference: nothing modifies the template to inject the version. Instead, Webpack's DefinePlugin adds the version as a global constant at build time, reading from package.json.

Two benefits: the footer is now a pure Angular component, and it's easier to test.

Adding tests

Adding tests throughout the platform is essential during the Angular 2 migration. The new footer component has its own tests. They simply verify that the version variable is defined correctly. But these tests serve a second purpose: they confirm the test runner and coverage reporter work correctly.

First coding week

contact@magarcia.io — Sun, 29 May 2016 00:00:00 GMT

The first week of GSoC 2016 coding period has ended. I started upgrading Jangouts from Angular 1.x to Angular 2. I completed all tasks within the deadline and hope to maintain this pace next week.

I'm following the upgrade guide from official Angular docs, which has two main blocks:

Preparation
Upgrading with The Upgrade Adapter

I just finished the preparation block. Fortunately, the Jangouts code is clear and already follows two key preparation requirements: the Angular style guide and component directives. This left me only two tasks: switch from <script> tags to a module loader, and migrate from JavaScript to TypeScript. I reversed the order, migrating to TypeScript first and then switching to a module loader. This sequence felt more natural for this project.

Migrating to TypeScript

Jangouts has a working gulp build system, so I did not need to worry about script loading. I focused first on migrating files to TypeScript, then leveraged the import syntax of TypeScript/ES6.

Migrating code from JavaScript to TypeScript is straightforward: change the extension from .js to .ts. The existing gulp system does not work with these changes, so run tsc --watch src/**/*.ts alongside gulp. This command shows many errors, but if the JavaScript code is correct, these errors relate only to TypeScript's type checking.

During this migration, I also made the code more modular. Jangouts had all components registered in a single Angular module janusHangouts. From previous projects, I learned this causes trouble with unit testing. I now define a separate module for each component (janusHangouts.componentName) and make it a dependency of the main module. This has two advantages: easier testing, and potentially loading components on demand with a module loader.

As mentioned earlier, compiling JavaScript code with tsc shows many errors. One common error is:

error TS7006: Parameter '$state' implicitly has an 'any' type.

The TypeScript compiler requires a type for all variables. To allow implicit any types for untyped variables, disable noImplicitAny in tsconfig.json.

Another error we can find when working with HTML elements is:

error TS2339: Property 'muted' does not exist on type 'HTMLElement'.

This error is produced from a code like that:

var video = $("video", element)[0];
video.muted = true;

TypeScript is type safe: $('video', element)[0] returns HTMLElement, which lacks the muted property. The subtype HTMLVideoElement contains muted. Cast the result to HTMLVideoElement:

var video = <HTMLVideoElement>$('video', element)[0];
video.muted = true;

Finally, another common error is:

error TS2339: Property 'id' does not exist on type '{}'.

TypeScript's type validation causes this error in code like:

var room = {};

// Some code here...

function isRoom(room) {
  return room.id == roomId;
}

Define an interface for the room object to fix this and reduce errors:

interface Room {
  id?: number; // ? makes the attribute optional
}

// Some code here ...

var room: Room = {};

// Some code here...

function isRoom(room: Room) {
  return room.id == roomId;
}

Using a Module Loader

Why use a module loader? The Angular site explains:

Using a module loader such as SystemJS, Webpack, or Browserify allows us to use the built-in module systems of the TypeScript or ES2015 languages in our apps. We can use the import and export features that explicitly specify what code can and will be shared between different parts of the application. [...]

When we then take our applications into production, module loaders also make it easier to package them all up into production bundles with batteries included.

I discarded Browserify due to past bad experiences and tried only SystemJS and Webpack.

SystemJS

SystemJS looks clean and simple. Define an entry point (typically the main application file) and the import syntax handles the rest. With correct import statements, everything works.

However, this solution requires keeping gulp since SystemJS only handles imports. This means adding the TypeScript compiler to gulp and disabling auto script injection in HTML.

Before rewriting the gulp configuration, I wanted to try Webpack first.

Webpack

Webpack configuration is more complex than SystemJS, but replaces gulp entirely. Like SystemJS, we define an entry point and specify where index.html is located for JavaScript file inclusion.

I had initial troubles, but after studying examples, I got a functional version. Exploring Webpack further, I found what made me choose it: we can import or require non-JavaScript files. We can require an Angular directive template, and the build process includes it as a string variable inside the component. Styles work the same way. This improves performance by bundling all files a component needs into its JavaScript file, without complicating development.

One more thing

This summer looks exciting with everything I will learn through GSoC. Follow my progress on this blog or through my GitHub contributions. I also published a Trello board with the project planning and tasks (still being updated).

Ending Community Bonding Period

contact@magarcia.io — Sun, 22 May 2016 00:00:00 GMT

A few weeks have passed since my last post. I have been busy.

Tomorrow the GSoC coding period begins. As mentioned previously, I have been working on Jangouts: making contributions, fixing bugs, and more. Last week I started writing tests for some components. A complete test suite would be wasted effort since the code will change significantly during the Angular 2 migration. These tests help me understand how Jangouts is structured and how it works.

During the community bonding period, I stayed in contact with my mentors (@imobach and @ancorgs). This past week we had a Jangouts call (we use Jangouts for meetings) to plan the coming weeks. We will use a Trello board to organize tasks and hold daily meetings to track progress. I also committed to writing a weekly blog post summarizing my work.

The Angular 2 migration starts in the coming days, but first I need a plan.

First Weeks at GSoC 2016

contact@magarcia.io — Sat, 07 May 2016 00:00:00 GMT

This year I was selected for the Google Summer of Code Program with my first proposal. I sought a project related to Angular, especially Angular 2, to deepen my knowledge of this framework and its new version. I was thrilled to find this idea from the OpenSuse community.

The community bonding period began April 22. I contacted my mentors and started fixing bugs in Jangouts while reporting issues to Janus-Gateway. These posts will serve as a progress journal for me and my mentors.

These weeks I explored the Jangouts codebase, experimented with Angular 2, and followed ng-conf.

magarcia

Using Claude Code Agent Teams for Incident Investigation

Agent teams: parallel Claude sessions that talk to each other

Enabling agent teams

The MCP setup that makes it useful

How I kicked it off

Four agents, one root cause

Five takeaways from a real incident

Best for multi-hypothesis problems

Getting started

Moving Shell Secrets from .zshrc to 1Password CLI

The problem with .env and .zshrc secrets

Create a vault and enable biometric unlock

Split your shell into two files

.zshenv — plain configuration, no secrets

.zshsecrets — secret references, not values

.zshrc — wire it together

Why op inject over op read

The cleanup you can't skip

Tradeoffs

A dotfiles repo you can make public

Your Test Output Is Burning Tokens: Taming Verbose Reporters for AI Agents

Detect the Environment, Choose the Reporter

What the Agent Sees

Trade-offs

The Same Fix Applies to Linters and Build Logs

AI-Native Development: When Building Is Faster Than Planning

Prototyping is Now Fast and Cheap

The Coordination Cost Now Exceeds the Execution Cost

Build First, Then React

Product and Design Need to Adapt Too

What AI-Native Companies Look Like

Build Fast, But Own What You Ship

Vibe Coding Doesn't Belong in Production

The Job Changes, But It Doesn't Disappear

Breaking the QR Limit: The Discovery of a Serverless WebRTC Protocol

The User Request I Couldn't Answer

Thursday Evening: The "Serverless" Lie

The Path I Didn't Take

The Hack That Worked

Refining the Hack

Friday Morning: The "Return Trip" Problem

The Glare Problem

The Browser State Paradox

Reconstructing the SDP

The mDNS Complication

Threat Model: The Optical Channel

The Bigger Picture: A Protocol, Not a Hack

Why Not Animated QRs?

1. Latency Kills Manual Signaling

2. UX Ceremony Tax

3. Semantic Compression Beats Transport Compression

The Final Protocol

The Compression Journey

A Note on "Serverless"

When It Fails

What I Learned

What's Next

Rubber Ducking with a Robot

Appendix: Quick Reference

Packet Structure

Flags Byte Layout

Test Vector

Why I Switched from Bun to Deno for Claude Code Skills

Why Deno Solves This

The Deno Approach

Trade-offs

Why Performance Doesn't Matter Here

Practical Example for Skills

Conclusion

References

YumML: A Human-Readable YAML Recipe Format for the AI Era

History

Motivation

Original design considerations

Why YAML in the Age of AI

The best of both worlds

Goals

Technical Details

Basic Example

The problem with `.env` and `.zshrc` secrets

`.zshenv` — plain configuration, no secrets

`.zshsecrets` — secret references, not values

`.zshrc` — wire it together

Why `op inject` over `op read`

Why `quantity` is optional and accepts strings

Approach 3: Google `zx` with `--install`