DEV Community: Umesh Malik

Agentic Browsing in PageSpeed Insights: How to Make Your Website AI-Ready (2026)

Umesh Malik — Fri, 19 Jun 2026 10:00:11 +0000

TL;DR

PageSpeed Insights now grades your site for AI agents, not just humans. Lighthouse 13.3 (May 7, 2026) added an Agentic Browsing category to the default config; PageSpeed Insights inherited it within two weeks. It sits next to Performance, Accessibility, Best Practices and SEO — and reports a ratio like 3/3, not a score out of 100.
It checks three things by default: a clean accessibility tree, a stable layout (low CLS), and a valid llms.txt at your domain root. The wider Lighthouse category also audits WebMCP — annotated forms and registered agent tools.
Google added it because agents are now real traffic. Operator, Computer Use, Project Mariner, Perplexity and ChatGPT's browse mode visit sites on a person's behalf. A growing share of requests hitting your server are software, not people.
You don't fail for lacking AI features — the category is informational. But "AI-ready" is now a measurable, public number, and it's about to become a competitive one.
Proof it's achievable: a real Lighthouse 13.4 run on my own site, umesh-malik.com, scores Agentic Browsing 3/3 and 100 on Accessibility, Best Practices and SEO — and it passes 7/7 on the isitagentready.com protocol-discovery checklist — using nothing but static files and one Cloudflare Worker. Here's exactly how, so you can copy it.

Your Website Is Now Being Graded for Robots

Open pagespeed.web.dev, run a report, and you'll see something that wasn't there a month ago: a category called Agentic Browsing, sitting right alongside Performance and SEO. It doesn't show a number out of 100. It shows a ratio — 2/3, 3/3 — and a short list of checks with names like "accessibility tree" and "llms.txt".

That ratio is not measuring how fast your page loads or whether your headings are in order. It's measuring how well an AI agent can read your page, understand it, and act on it — with no human in the loop.

This is the quiet half of a shift that's been building all year. We spent two decades optimizing for two audiences: humans who read, and crawlers that index. There's now a third, and it behaves like neither. An agent doesn't skim your hero copy or admire your animations. It wants structure it can parse, facts it can extract, and tools it can call. Google just turned "are you ready for that audience?" into a number anyone can pull up.

💡 Key insight: SEO made your site findable. GEO made it quotable. Agentic Browsing makes it usable by software. These are three different jobs, and the third one is now scored in the same tool you already use for Core Web Vitals.

What Is the Agentic Browsing Category in PageSpeed Insights?

Agentic Browsing is a Lighthouse category that scores how ready a page is for an AI agent to read it, understand it, and act on it without a human driving. It was introduced in Lighthouse 13.3 on May 7, 2026, moved straight into the default config, and PageSpeed Insights picked it up within a couple of weeks. As of mid-June 2026 it's live for everyone.

A few things make it behave differently from every other Lighthouse category:

It reports a ratio, not a score out of 100. You'll see 3/3, not 92. It's a count of passed checks, not a weighted index.
It's marked "under development." The exact audits and the way they're scored will change. Don't carve a 3/3 into your OKRs yet.
It won't fail you for having no AI features. example.com — a page with almost nothing on it — earns a perfect ratio. This is a checklist of opportunities, not a penalty box.

In PageSpeed Insights, the default result is built from three checks. The broader Lighthouse category runs four audits:

Notice what's not there: nothing about keywords, backlinks, or meta descriptions. This audit is about machine comprehension and machine action, full stop.

Why Google Added It — Agents Are Real Traffic Now

The cynical read is "Google wants another number to chase." The accurate read is simpler: a meaningful and growing share of the requests hitting public web servers are agents, not humans — and the tooling finally caught up to that reality.

Look at who's browsing on a user's behalf in 2026: OpenAI's Operator, Anthropic's Computer Use, Google's own Project Mariner, Perplexity, and ChatGPT's browse mode. These don't issue a query and read ten blue links. They get a task — "compare these three products and book the cheapest one that ships by Friday" — and they execute it across multiple sites. To do that, they have to read your page, model what's on it, and act.

When an agent hits a page built only for human eyes, three things go wrong:

Comprehension is expensive. Feeding raw HTML or a screenshot into a model burns tokens and invites mistakes. A clean accessibility tree is an order of magnitude cheaper to reason over.
Action is fragile. If your "Add to cart" is a <div> with an onclick, an agent has to guess. Annotated forms and registered tools remove the guessing.
Discovery is a coin flip. Without an llms.txt or a tool manifest, the agent has to reverse-engineer your site's structure every single visit.

The honest caveat
This category is new and explicitly "under development." llms.txt in particular isn't yet widely consumed by AI tools — even the Lighthouse team says so. None of this is a guaranteed ranking lever today. It's a low-cost bet on where the web is obviously heading, made measurable a year or two before most sites will bother. That early-mover window is the whole point.

How It Helps Developers (and Agents)

For agents, the payoff is obvious: cheaper comprehension, reliable action, less hallucination about what your site does.

For developers, the wins are quieter but real:

How to Make Any Website AI-Ready

Here's where it gets practical. The PageSpeed category is the headline, but the fuller checklist lives at isitagentready.com — a free scanner that groups agent-readiness into five categories. I've used its taxonomy to structure the work below, because it maps cleanly onto what agents actually look for.

You don't need all five. A blog needs the first four and can ignore commerce entirely. A store needs all five. Work top-down — discoverability is the cheapest and highest-leverage.

💡 Key insight: The single highest-leverage change most sites can make is also the most boring — stop rendering text and diagrams as images. An image of a table is invisible to the accessibility tree. A real <table> (or a component that renders one) is readable by screen readers, crawlers, and agents in one shot. I'll come back to this, because it's exactly how I scored my own site.

If you want to go deeper on the callable layer, I wrote a full walkthrough of building a production MCP server and deploying it on Cloudflare Workers — that's the same server backing the numbers below.

Proof: How AI-Ready Is umesh-malik.com?

Talk is cheap, so here's the receipt. I ran my own site — umesh-malik.com — through Lighthouse 13.4 (the engine behind PageSpeed Insights) and the isitagentready.com checklist. This site is a SvelteKit SSG — fully static, one Cloudflare Worker, no special infrastructure. Everything below ships from files in a public repo.

The Agentic Browsing category comes back 3/3 — every weighted check passing:

Here's the honest, category-by-category breakdown — including what the site doesn't have:

.md and /llms.txt', tone: 'neutral' }] },
{ label: 'llms.txt + llms-full.txt', cells: [{ text: 'Yes', tone: 'positive' }, { text: 'Valid H1, description, ~3,500 words, every post linked', tone: 'neutral' }] },
{ label: 'MCP server card', cells: [{ text: 'Yes', tone: 'positive' }, { text: '/.well-known/mcp/server-card.json — 4 tools, Streamable HTTP', tone: 'neutral' }] },
{ label: 'Agent Skills + API catalog + WebMCP', cells: [{ text: 'Yes', tone: 'positive' }, { text: 'agent-skills/index.json, RFC 9727 linkset, navigator.modelContext', tone: 'neutral' }] },
{ label: 'OAuth discovery + auth.md', cells: [{ text: 'Yes', tone: 'positive' }, { text: 'Honestly declares the site as public/anonymous — no fake auth server', tone: 'neutral' }] },
{ label: 'DNS-AID + Web Bot Auth', cells: [{ text: 'Not yet', tone: 'negative' }, { text: 'On the roadmap — newer, lower-leverage for a content site', tone: 'neutral' }] },
{ label: 'Commerce (x402, MPP, UCP, ACP)', cells: [{ text: 'N/A', tone: 'neutral' }, { text: 'It\'s a portfolio + blog. Nothing to sell, nothing to fake.', tone: 'neutral' }] }
]}
/>

The result: the site passes every category that applies to it and scores 7/7 on protocol discovery. The 3/3 above is a real Lighthouse run, not a mockup — and I'm not pretending DNS-AID and Web Bot Auth are done, because they aren't. (Note the three WebMCP audits show as Not Applicable in the screenshot: the site registers WebMCP tools in code, but Lighthouse's WebMCP audits are still informational and didn't score them on this page — an honest nuance of a category that's openly "under development.") That candor is the point. Agent-readiness is a real engineering state, not a vanity badge.

How I Actually Got Here (and How You Can Copy It)

None of this required a backend rewrite. The whole agent-discovery layer is one Cloudflare Worker plus a handful of static files:

The most important line in that list is the one about diagrams as DOM components. This very post is the proof: every chart, table and step list you've scrolled past is a real Svelte component rendering semantic HTML — not a PNG. That's why an agent (or a screen reader) can read all of it, and it's a large part of why the accessibility-tree check passes. One decision, paid back across three audiences.

The reusable principle
You don't need Cloudflare, SvelteKit, or my stack. The pattern generalizes: reuse the content you already publish (your feed, your Markdown, your profile) and expose it through machine-readable surfaces — robots.txt, llms.txt, Link headers, an MCP endpoint. The data already exists. Agent-readiness is mostly about presenting it in formats agents understand, not creating new content.

Common Mistakes to Avoid

Chasing the ratio instead of the readiness. example.com scores a perfect ratio with nothing real behind it. A green 3/3 on a site full of image-of-text content is a lie you're telling yourself. Optimize the underlying state, not the badge.
Faking an auth server. If your site is public, say so in auth.md and OAuth discovery. Advertising endpoints that don't exist breaks the agents that trust them. Honest "anonymous, no auth" beats a fictional token endpoint.
Treating llms.txt as a keyword dump. It's a map, not a meta-keywords tag. Give it a clear H1, a real description, and links to your genuinely best content. Stuffing it is the 2007 SEO mistake in a new file.
Shipping images of text. The single most common thing that quietly fails the accessibility-tree check. If a human needs to read words in it, it should be real text, not a screenshot.
Ignoring CLS because "it's just SEO." Layout that jumps confuses screenshot-based agents the same way it annoys users. Your Core Web Vitals work now pays an agentic dividend too.

The Bottom Line

Agentic Browsing in PageSpeed Insights is small today — a ratio, marked "under development," consumed by tools that are themselves a year young. It would be easy to dismiss. Don't.

The trajectory is unmistakable: agents are becoming a first-class audience for the web, Google just made their needs measurable, and the work to satisfy them is cheap, mostly static, and overlaps almost entirely with accessibility and good engineering you should be doing anyway. The sites that ship a clean accessibility tree, a real llms.txt, and a callable MCP endpoint now will be the ones agents reach for when the rest of the web is still serving them screenshots.

I made my own site agent-ready with a Worker and some static files, and I documented every move so you can do the same. Start with robots.txt and llms.txt this week. Then decide how deep into protocol discovery your site deserves to go.

Written for umesh-malik.com — no-fluff technical writing on AI, Web Dev, and Engineering. Curious how the callable layer works? Read How to Build a Production MCP Server next.

Originally published at umesh-malik.com

Keep reading on umesh-malik.com:

AI Agents That Run the Business in 2026: Why 77% Never Reach Production (and What the 23% Do Differently)

Umesh Malik — Sun, 14 Jun 2026 17:00:02 +0000

TL;DR

Building an AI agent is easy. Shipping one that runs your business is where roughly 77% of projects die. The demo-to-production gap is the real story of agentic AI in 2026 — not the model benchmarks.
Three things kill agents in production: compounding error across long tool chains, fuzzy accountability when the agent acts on its own, and the unglamorous integration work nobody puts in a demo.
The 23% who ship all do the same five things: pick a narrow, high-volume task; keep a human on the risky steps; scope permissions tightly; build an eval harness before scaling; and graduate from shadow mode to autonomy instead of flipping a switch.
Proof it works when it's bounded: Lassie raised $35M in June 2026 to run medical- and dental-practice back offices for 700+ businesses, reclaiming about 250,000 staff-hours a year.

Everyone Is Building AI Agents. Almost Nobody Is Shipping Them.

Lassie just raised $35 million to make small businesses run themselves. Andreessen Horowitz led the round in June 2026, and the pitch is exactly as ambitious as it sounds: autonomous AI agents that don't just help a medical practice with its back office — they run it. Payment enrollment, reconciliation, insurance appeals, follow-up. The software does the work, not the staff.

Here's the uncomfortable part. For every Lassie, there are a hundred agent projects quietly dying in a sandbox. McKinsey's 2026 numbers say it plainly: 62% of organizations are experimenting with agents, but only 23% have scaled them. Gartner expects 40% of enterprise apps to embed task-specific agents by the end of 2026 — up from less than 5% — which means the gap between "we built an agent" and "the business runs on it" is about to become the most expensive gap in software.

That funnel is the whole article. The winners aren't the teams with the smartest model — by 2026 everyone has access to roughly the same frontier models. The winners are the teams that treated autonomous as an outcome to earn, not a switch to flip. Let's break down exactly where the 77% fall out, and what the survivors do differently.

What an Autonomous AI Agent That Runs the Business Actually Means

The word "agent" got stretched into meaninglessness in 2025. Half the products calling themselves agents are chatbots with a system prompt. So let's be precise.

Definition
An autonomous AI agent is software that pursues a goal by deciding its own steps and taking real actions across tools and systems — not just answering a prompt. A copilot suggests; an agent acts. An agent that "runs the business" owns a workflow end to end, with a human in the loop by exception rather than by default.

It helps to see it as a ladder:

A chatbot answers questions. It has no hands.
A copilot drafts and suggests. You review every output and you take the action.
An autonomous agent takes the action itself — it books, files, reconciles, emails — and only escalates to a human when its own policy says to.

The jump that matters is from suggesting to acting. That single step is where reliability, trust, and accountability stop being nice-to-haves and start being the entire engineering problem. It's also why "agentic" is not the same as "automation." Classic automation follows a fixed script you wrote. An agent chooses the path at runtime — which is exactly what makes it powerful and exactly what makes it hard to ship.

Why This Is Suddenly Real in 2026

Agents aren't new as an idea. What changed in 2026 is that three curves crossed at once.

Models got good enough and cheap enough. The June 2026 release wave pushed frontier capability up and token prices down hard. Reasoning that was research-grade in 2024 is now a line item.

Integration got standardized. The Model Context Protocol turned "wire the agent into your stack" from a bespoke six-week project into a connector you can reuse. Plumbing was the silent blocker, and it got a lot less silent.

The economics finally make sense for the back office. This is the part founders underrate. The money isn't in flashy consumer demos — it's in the boring, expensive work every small business drowns in.

Andreessen Horowitz called small businesses "the next frontier for AI" for exactly this reason: a single medical practice can burn over 100 hours a month and roughly $200,000 a year on administrative work that is repetitive, rule-bound, and perfect for an agent — if you can get the agent into production. Which brings us to the hard part.

Why 77% of AI Agents Never Reach Production

The gap is not a model problem. It's a systems problem. Here are the five failure modes that kill agents between an impressive demo and a dependable deployment.

1. Compounding error is the silent killer

A demo runs three steps and looks like magic. Production runs twenty and falls apart. Reliability multiplies — it doesn't average.

An agent chaining 20 tool calls at 95% per-step reliability succeeds end to end only about 36% of the time (0.95^20 ≈ 0.36). That's not a model you can ship; that's a coin flip you'd lose two times out of three. Push per-step reliability to a heroic 99% and you're still only at 82% across 20 steps.

The fix is not a cleverer prompt. It's fewer steps, verification between steps, and retries that actually check their work. The teams that ship design short, checkpointed chains. The teams that stall keep adding steps and hoping.

2. Nobody owns the outcome

When a copilot suggests something wrong, a human catches it. When an agent files the insurance appeal, posts the transaction, or emails the customer, there is no catch — unless you built one.

Demos hide this because the person demoing is the safety net. Production has to encode the safety net as policy: approval gates on irreversible actions, reversibility where you can manage it, and an audit trail for everything. "Who is accountable when the agent is wrong?" is a question you answer in your architecture, not your marketing.

3. The integration tax nobody demos

The exciting part is reasoning. The expensive part is plumbing — connecting to the practice-management system, the payment processor, the ledger, the CRM, the half-documented internal API from 2014.

Most pilots stall here. Not because the agent can't think, but because it can't reliably act in the messy systems a real business runs on. Standardization like the Model Context Protocol made this tractable — it did not make it trivial. Budget for the integration tax or it will quietly eat your timeline.

4. No evals, no production

If you can't measure whether the agent did the job, you cannot ship it. Yet most teams still test by vibes: try a few prompts, it looks good, ship it.

Production needs an eval harness — a labeled set of real tasks, an automated grader, and a single number you can watch move as you change things. This is the same discipline behind spec-driven development: write down what "done" means before you trust a machine to do it. No harness, no honest answer to "is it good enough yet?"

5. Cost and latency at scale

A run that costs $0.40 and takes 90 seconds is delightful in a demo and brutal at 50,000 runs a day. The unit economics of the agent loop — tokens, retries, tool round-trips — decide whether the pilot survives contact with real volume.

💡 Key insight: The teams that ship treat reliability as an engineering budget to spend, not a model property to wait for.

What the 23% Do Differently

The survivors are almost boring about it. They don't chase the most autonomous agent they can build — they build the most bounded agent that solves a real problem, then earn autonomy from there.

Notice what's missing: "use a bigger model." Model choice matters, but it's table stakes. The differentiator is operating discipline.

The Autonomy Spectrum: It's a Dial, Not a Switch

The biggest framing mistake teams make is treating autonomy as binary — either the human does it or the agent does. In reality it's a spectrum, and the credible 2026 deployments cluster in the middle.

L4 makes the headlines and the funding decks. L2 and L3 make the money. A supervised agent that handles 90% of cases autonomously and escalates the weird 10% to a human is worth far more than a fully autonomous agent that's right 70% of the time and unaccountable for the other 30%. Earn your way up the ladder; don't start at the top.

The Mistakes That Keep Teams Stuck

Avoid these five traps
The same anti-patterns show up in almost every stalled agent project. If you recognize more than one, that's your roadmap.

The "run my whole company" fantasy. Broad, open-ended scope is undemoable and unshippable. Narrow until the task is boring, then ship the boring version.
Demo-driven development. Optimizing for the three-step happy path that looks great on stage and ignores the long tail that breaks in production.
Over-permissioned agents. Handing the agent god-mode credentials "to move fast." You're one prompt injection away from regret. Scope everything.
Skipping evals. Without a number, "good enough" is a feeling, and feelings don't survive a board meeting after the agent fails publicly.
Ignoring the integration tax. Treating the messy back-office plumbing as an afterthought, then discovering it is the project.

Case Study: How Lassie Actually Ships Autonomy

Lassie is a useful case study precisely because it isn't trying to do everything. It picked one vertical with a brutal admin burden and went deep.

The lesson isn't "build a Lassie." It's that their design choices are the production playbook in disguise: a narrow vertical (bounded scope), high-volume repetitive tasks (testable reliability), and a workflow with clear success criteria (eval-friendly). They didn't win by being more autonomous than everyone else. They won by being autonomous about the right, small thing — and being able to prove it worked.

Is Your Agent Actually Production-Ready?

Before you let an agent touch anything a customer or a regulator will see, run this checklist. If you can't tick the criticals, you have a demo, not a deployment.

FAQ

The Bottom Line

In 2026, building an autonomous AI agent is a weekend project. Building one your business can actually run on is a discipline — and it's a discipline most teams skip on the way to a demo that wins applause and a deployment that never arrives.

Stop trying to flip the autonomy switch. Pick one narrow, high-volume, boring task. Put a human on the dangerous steps. Scope the permissions. Build the eval harness. Run it in the shadows until the numbers earn your trust — then, and only then, let it act on its own. That's how the 23% ship while everyone else demos.

If this was useful, read how agentic AI breaks the enterprise security model next — because the moment your agent can act, security stops being optional. Then learn to build the integration layer with MCP and to pin down "done" with spec-driven development.

Written for umesh-malik.com — no-fluff technical writing on AI, Web Dev, and Engineering.

SEO Summary (unpublished)

Suggested slug: /blog/autonomous-ai-agents-production-gap-2026
Meta description: " Everyone's building autonomous AI agents in 2026 — but only 23% reach production. The demo-to-production gap, why agents fail, and the playbook the winners use."
Primary keyword: autonomous AI agents 2026
Secondary keywords: AI agents for business, AI agents in production, agentic AI 2026, why AI agents fail, human-in-the-loop agents, vertical AI agents, AI agent reliability
GEO hooks: "What an Autonomous AI Agent That Runs the Business Actually Means", "Why 77% of AI Agents Never Reach Production", "What the 23% Do Differently"
Internal links: agentic-ai-enterprise-security-model, how-to-build-mcp-server, spec-driven-development-ai-agents-addy-osmani
Featured snippet opportunity: Y — the autonomy spectrum table and the "Why 77% never reach production" list

Originally published at umesh-malik.com

Keep reading on umesh-malik.com:

How to Write a CLAUDE.md That Actually Helps

Umesh Malik — Fri, 12 Jun 2026 20:24:05 +0000

Most CLAUDE.md files are useless in one of two ways: they're empty, or they're bloated with things the agent could figure out in five seconds. Both waste the one thing the file exists to spend well — the agent's attention at the start of every session.

A good CLAUDE.md isn't documentation. It's a briefing for a senior engineer joining your team today who happens to read fast and forget nothing. You don't hand that person a file tree. You tell them how to run the thing, how the pieces fit, the conventions that aren't obvious, and the traps that already bit you.

I maintain CLAUDE.md files across my projects, and the difference between a good one and a bad one is the difference between an agent that moves like a teammate and one that re-derives your architecture every session. Here's what actually works.

TL;DR

CLAUDE.md is a context file Claude Code reads automatically — treat it as a briefing, not documentation.
Include the non-obvious: commands, big-picture architecture, cross-cutting conventions, and gotchas.
Leave out what the agent discovers instantly (file trees) or what rots (generic best-practice filler).
Use a root file for the big picture and nested files for subproject-specific rules.
Keep it alive. A CLAUDE.md that drifts from reality is worse than none — it actively misleads.

What a CLAUDE.md actually is

CLAUDE.md is a Markdown file that Claude Code loads as project context at the start of a session. Whatever you put in it becomes part of what the agent knows before it reads a single line of your code. That's the whole mechanism — and it's why the file is so easy to get wrong. Anything you write is "free" knowledge the agent starts with; anything you omit, it has to rediscover (and sometimes guess at) every time.

So the real question isn't "what could I document?" It's "what does the agent most need to know that it can't quickly find out itself?"

💡 Key insight: Optimize for the agent's first five minutes. What would a sharp new hire need to be productive — and what would they figure out on their own without being told?

What actually belongs in it

Four things earn their place. Almost nothing else does.

1. Commands

How to build, test, lint, run, and deploy — including the non-obvious incantations. If running a single test needs a specific flag, if dev mode needs two terminals, if there's a pre-commit gate, that's gold. The agent will otherwise guess, and guess wrong.

## Commands
- `pnpm dev` — main site on :5173
- `pnpm check` — typecheck; MUST pass before commit
- `pnpm build` — proves the static prerender works

2. The big-picture architecture

Not every file — the shape. How the major pieces fit, what talks to what, where the boundaries are. The things that require reading five files to understand. A short prose map or a simple diagram here saves the agent (and you) enormous time.

This is where "the analytics API is the only server-side code" or "sub-apps are built separately and copied in at build time" belongs — facts that aren't visible from any single file.

3. Cross-cutting conventions

The rules that span the codebase and that the agent would otherwise violate: "everything ships static, never introduce SSR," "use runes only, no legacy reactive syntax," "canonical domain is X, use the central config." State them as rules, with the why when it isn't obvious.

4. Gotchas and hard-won lessons

The traps. "This build step fails silently if X." "Don't edit the generated covers by hand." "Running git add from inside the subdir breaks paths." These are the highest-value lines in the file because they're the ones nobody could infer.

What to leave out

Every line that doesn't earn its place dilutes the ones that do. Cut:

Exhaustive file trees and component lists. The agent can run ls and grep faster than you can maintain a manifest. Describe structure only where it's non-obvious.
Generic best practices. "Write unit tests." "Handle errors gracefully." "Don't commit secrets." The agent already knows. These read as noise and train it to skim.
Restating the code. If a function's behavior is clear from its name and body, don't narrate it in CLAUDE.md.
Anything that rots. Version numbers, line counts, "currently we're working on X" — unless you'll actually keep them current. Stale instructions are worse than missing ones because the agent trusts them.

💡 Key insight: A CLAUDE.md that's wrong is worse than one that's empty. An empty file makes the agent investigate; a wrong file makes it confidently do the wrong thing.

A structure that works

You don't need a rigid template, but this shape covers the essentials without bloat:

# CLAUDE.md

## What This Repo Is
[One paragraph: what it is, the stack, how it's organized.]

## Architecture / How the Pieces Fit
[The big picture. A diagram or short prose map. Boundaries and data flow.]

## Common Commands
[Build, test, run, deploy — including the non-obvious ones.]

## Conventions
[Cross-cutting rules the agent must follow, with the why.]

## Gotchas
[Traps, footguns, things that bit you before.]

## Keeping This File Up To Date
[A note that this is a living map, updated as part of normal work.]

For a monorepo, go further: a root CLAUDE.md for the big picture, plus a nested CLAUDE.md inside each subproject for rules specific to it. Claude Code reads the relevant files based on where you're working, so subproject rules stay close to the code they govern. There's also a user-level ~/.claude/CLAUDE.md for personal preferences that follow you across every project.

Common mistakes

The kitchen sink. Dumping everything turns the signal-to-noise ratio against you. Be ruthless.
Write-once, never-update. The fastest way to make a CLAUDE.md harmful is to let it drift. Update it in the same change that alters what it describes.
Documenting the obvious. If the agent learns it in one grep, it doesn't belong.
No commands. The single most useful section, and the one people most often skip.
Vague rules. "Follow good practices" tells the agent nothing. "Never use transition-all; always name the exact property" tells it exactly what to do.

Best practices

Bootstrap with /init, then trim. Claude Code's /init generates a first draft from your repo. Treat it as a starting point and cut it down to the non-obvious essentials.
Write rules, not essays. Short, imperative, specific. "Do X. Never Y. Because Z."
Put rules near the code. Root file for the big picture; nested files for subproject specifics.
Make it a living document. Update it as part of the change that affects it — not as a someday chore.
Re-read it as the agent would. If a line wouldn't change what the agent does, or it could learn it instantly, delete it.
Lead with commands and gotchas. They're the highest-leverage content in the file.

Conclusion

A CLAUDE.md is the cheapest leverage you have over how well an AI agent works in your codebase — and almost everyone either skips it or stuffs it. Write it like a briefing for a sharp teammate: the commands, the architecture that isn't obvious, the conventions that matter, the traps that bite. Cut everything they'd discover on their own. Then keep it honest.

Do that, and the agent stops re-learning your project every session and starts acting like it already knows it.

Going deeper on agentic coding? See Claude Code — Guides & Deep Dives and AI Coding Agents — Agentic AI for Developers, or the official Claude Code documentation for the full feature set.

Explore more: Claude Code · AI Coding Agents · LLM Engineering

Originally published at umesh-malik.com

Keep reading on umesh-malik.com:

How to Build a Production MCP Server (I Added One to My Site)

Umesh Malik — Fri, 12 Jun 2026 20:23:33 +0000

Most sites are built for humans to read and for crawlers to scrape. But the agents showing up now — Claude, ChatGPT, Cursor — don't want your HTML. They want to call you. Parsing a page to extract three facts is wasteful and fragile; calling a typed tool that returns those three facts is neither.

That's what the Model Context Protocol (MCP) is for. And the fastest way to understand it is to build one. So I added a production MCP server to this site — it lets an agent search my posts, fetch one as clean Markdown, list my topic hubs, and read my profile — and this is exactly how I did it, with the real code.

No framework, no database, about 300 lines on a Cloudflare Worker.

TL;DR

An MCP server exposes tools (functions) that AI agents call over JSON-RPC 2.0 — turning your site from agent-readable into agent-callable.
Use the Streamable HTTP transport: one endpoint, POST /mcp, that speaks JSON-RPC. A stateless server that returns plain JSON is fully spec-compliant and the easiest to run.
You need exactly four method handlers: initialize, tools/list, tools/call, and ping — plus a no-op for notifications.
You don't need new infrastructure. Back your tools with assets you already publish (a JSON feed, your Markdown pages). One source of truth, nothing to sync.
Make it discoverable with a manifest at a well-known URL, an entry in your API catalog, and a Link header.

What is an MCP server?

An MCP server is a small service that exposes tools an AI agent can invoke over a standard protocol. The protocol is JSON-RPC 2.0; the "tools" are named functions with a JSON-Schema for their arguments. When an agent connects, it asks the server "what can you do?" (tools/list), gets back a list of tools, then calls them (tools/call) and receives structured results.

Think of it as a typed API designed specifically for language models. Where a REST API is built for your frontend, an MCP server is built for an agent's reasoning loop: the descriptions are written for a model to read, the inputs are schema-validated, and errors are reported in a way the model can recover from.

💡 Key insight: REST is for your app. MCP is for the agent. The difference isn't the wire format — it's that every field is written to be understood by a model, not a developer.

Why build one for your own site

Search and chat are moving inside agents. When someone asks Claude or ChatGPT about a topic you've written about, the model is far more likely to use you well if it can call a search_posts tool than if it has to guess your URL structure and scrape rendered HTML.

Three concrete wins:

Precision over scraping. A tool returns exactly the fields the agent needs — title, URL, summary — with no markup noise.
You control the surface. You decide what's callable and what each tool returns. That's a far stronger signal than hoping a crawler parses your page correctly.
It compounds with the rest of your AI-readiness. An MCP server sits naturally alongside llms.txt, structured data, and an API catalog as part of making your site first-class for agents.

It will not, on its own, make every agent "pick" your site — that still depends on relevance and authority. But it removes every technical reason an agent couldn't use you well.

What we're building

Four read-only tools:

Tool	What it does	Backed by
`search_posts`	Ranked search over blog posts	a JSON feed I already publish
`get_post`	Returns one post as clean Markdown	prerendered `/blog/<slug>.md`
`list_topics`	Lists curated topic hubs	a small constant
`get_profile`	Returns the author profile	my existing `llms.txt`

The whole thing runs on a Cloudflare Worker as a stateless JSON-RPC handler. Stateless matters: with no session to track, every request is self-contained, which is the simplest possible thing to host and scale.

Step 1 — The transport

MCP defines two transports. For local tools you use stdio; for a remote server you use Streamable HTTP — a single endpoint that accepts JSON-RPC messages over POST. The spec lets the server reply with either an SSE stream or a plain JSON body. A read-only server has no streaming notifications to push, so plain JSON is the right call and the simplest.

Every MCP message is JSON-RPC 2.0. Two tiny helpers cover all our responses:

function rpcResult(id: unknown, result: unknown) {
  return { jsonrpc: '2.0', id, result };
}
function rpcError(id: unknown, code: number, message: string) {
  return { jsonrpc: '2.0', id, error: { code, message } };
}

The endpoint parses the POST body, routes on method, and returns the JSON-RPC response. Requests carry an id; notifications don't — and a notification gets no response body, just a 202 Accepted.

Step 2 — Define your tools

A tool is metadata plus an input schema. The description is not for you — it's the prompt the model reads to decide whether and how to call the tool. Write it like you're briefing a smart colleague who can't see your code:

const TOOLS = [
  {
    name: 'search_posts',
    title: 'Search blog posts',
    description:
      'Full-text search across the blog (titles, summaries, tags). Returns matching ' +
      'posts with slug, title, URL, summary, tags and publish date. Use for topics ' +
      'like AI engineering, LLMs, RAG, Claude Code, or web development.',
    inputSchema: {
      type: 'object',
      properties: {
        query: { type: 'string', description: 'Search terms.' },
        limit: { type: 'integer', description: 'Max results (default 10, max 30).' }
      },
      required: ['query']
    }
  }
  // get_post, list_topics, get_profile ...
];

💡 Key insight: Tool descriptions are prompt engineering. A vague description means the model calls the wrong tool or skips it. Spell out when to use it and what it returns.

Step 3 — Back tools with data you already have

This is the part most tutorials overcomplicate. You don't need a database. I back every tool with assets the site already prerenders:

search_posts fetches my existing /feed.json (a JSON Feed of every post) and ranks it.
get_post fetches the already-generated /blog/<slug>.md Markdown variant.
get_profile returns my llms.txt.

On a Cloudflare Worker you reach those via the assets binding, so there's one source of truth and nothing to keep in sync:

async function searchPosts(assets, origin, query, limit) {
  const res = await assets.fetch(new URL('/feed.json', origin));
  if (!res.ok) throw new Error('Post index unavailable');
  const { items = [] } = await res.json();

  const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
  return items
    .map((item) => {
      const hay = `${item.title} ${(item.tags || []).join(' ')} ${item.summary}`.toLowerCase();
      // weight title hits over tags over summary
      const score = terms.reduce((s, t) => s + (item.title.toLowerCase().includes(t) ? 3 : 0)
        + ((item.tags || []).join(' ').toLowerCase().includes(t) ? 2 : 0)
        + (hay.includes(t) ? 1 : 0), 0);
      return { item, score };
    })
    .filter((x) => x.score > 0)
    .sort((a, b) => b.score - a.score)
    .slice(0, limit)
    .map(({ item }) => ({ title: item.title, url: item.url, summary: item.summary }));
}

Always validate inputs before using them. get_post takes a slug straight from the model, so it gets a strict regex check before it ever touches a path:

const SLUG_RE = /^[a-z0-9][a-z0-9-]{0,120}$/;
if (!SLUG_RE.test(slug)) {
  throw new Error(`Invalid slug "${slug}". Use a slug from search_posts.`);
}

Step 4 — Handle the protocol

The router is small. Four real methods, plus notification handling:

async function handleRpc(msg, assets, origin) {
  const { id, method, params } = msg;
  const isNotification = id === undefined || id === null;

  switch (method) {
    case 'initialize':
      return rpcResult(id, {
        protocolVersion: '2025-06-18',
        capabilities: { tools: { listChanged: false } },
        serverInfo: { name: 'my-site', version: '1.0.0' },
        instructions: 'Tools for querying my blog and profile.'
      });
    case 'ping':
      return rpcResult(id, {});
    case 'tools/list':
      return rpcResult(id, { tools: TOOLS });
    case 'tools/call': {
      const { name, arguments: args = {} } = params || {};
      try {
        const text = await callTool(assets, origin, name, args);
        return rpcResult(id, { content: [{ type: 'text', text }], isError: false });
      } catch (err) {
        // Report tool errors IN-BAND so the model can see and react to them.
        return rpcResult(id, { content: [{ type: 'text', text: err.message }], isError: true });
      }
    }
    default:
      if (isNotification) return null;            // ignore unknown notifications
      return rpcError(id, -32601, `Method not found: ${method}`);
  }
}

Three things people get wrong here, and they all live in this function:

initialize must echo a protocolVersion the client understands and declare your capabilities. Skip it and the handshake fails before any tool runs.
Tool failures are not protocol errors. A bad slug returns a normal result with isError: true and a message — so the model reads the failure and retries — not a JSON-RPC error. Reserve error (-32601, -32700, etc.) for malformed protocol.
Notifications get no response. If notifications/initialized arrives, acknowledge with 202 and an empty body. Returning a JSON-RPC object for a notification breaks strict clients.

Step 5 — Make it discoverable

A server nobody can find is useless. Advertise it three ways:

A manifest at /.well-known/mcp — name, endpoint, transport, and the tool list.
An entry in your API catalog (/.well-known/api-catalog, RFC 9727) pointing at the manifest.
A Link header on your HTML responses: Link: </.well-known/mcp>; rel="service-desc"; type="application/json".

Then point an MCP client straight at https://yoursite.com/mcp.

Testing your MCP server

You don't need a fancy client to test — curl speaks JSON-RPC fine. List the tools:

curl -s -X POST https://yoursite.com/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Call one:

curl -s -X POST https://yoursite.com/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"search_posts","arguments":{"query":"RAG","limit":3}}}'

Work through the lifecycle: initialize → tools/list → tools/call, then confirm the edges — an invalid slug returns isError: true, a notification returns 202 with no body, an unknown method returns -32601, and a GET returns 405. If all of those behave, real clients will too.

Common mistakes

Treating tool errors as protocol errors. The single most common bug. Use isError: true in the result; keep JSON-RPC error for malformed requests only.
Building stateful sessions you don't need. A read-only server should be stateless. Sessions add complexity and a scaling headache for zero benefit here.
Thin tool descriptions. "Search" tells the model nothing. Say what it searches, what it returns, and when to reach for it.
Duplicating your data. Don't copy your content into the server. Point tools at what you already publish so there's nothing to keep in sync.
Forgetting CORS. Browser-based MCP clients need it. Handle OPTIONS and allow the Mcp-Session-Id / Mcp-Protocol-Version headers.

Best practices

Stateless first. Reach for sessions only when a tool genuinely needs continuity.
Validate every argument. Treat tool inputs like any untrusted input — schema plus a guard.
Write descriptions as prompts. They're the only thing the model sees when deciding to call a tool.
Reuse existing assets. Your feed, your Markdown, your profile file — one source of truth.
Advertise it. Manifest + API catalog + Link header, so agents can find it without being told.
Test the edges, not just the happy path. Notifications, unknown methods, invalid inputs, wrong HTTP verb.

Conclusion

An MCP server is less code than you expect — a JSON-RPC router, four well-described tools, and a thin layer over content you already ship. The mental shift is the real work: stop thinking of your site as pages to be read and start thinking of it as capabilities to be called. That's the interface agents actually want.

I built mine on a Cloudflare Worker in an afternoon, and it now sits alongside the rest of this site's agent-readiness as a first-class surface. If you've already got a JSON feed and Markdown pages, you're most of the way there.

If this was useful, go deeper next: see how the pieces fit together across LLM Engineering — RAG, Fine-Tuning & Production LLMs and AI Coding Agents — Agentic AI for Developers, or read the official MCP specification for the full protocol.

Explore more: AI Coding Agents · LLM Engineering · Claude Code

Originally published at umesh-malik.com

Keep reading on umesh-malik.com:

Deploy an MCP Server on Cloudflare Workers (Free, Stateless, at the Edge)

Umesh Malik — Fri, 12 Jun 2026 20:23:32 +0000

You built an MCP server — a JSON-RPC handler with a few well-described tools. Now it has to live somewhere an agent can reach it, 24/7, without you babysitting a server. Cloudflare Workers is close to the ideal host for this, and most of the reasons come down to one property of a read-only MCP server: it's stateless.

This is the deployment half of the story. If you haven't written the server logic yet, start with How to Build a Production MCP Server — this post picks up where that one ends and gets it onto the edge, on the free tier, on your own domain.

I run exactly this setup for my own site. Here's the whole thing.

TL;DR

A read-only MCP server is stateless, which is precisely what edge runtimes do best — so Workers is a natural fit, not a compromise.
The entire deploy is a wrangler.toml, one wrangler deploy, and a route check for /mcp.
run_worker_first = true is the setting people miss — it lets your Worker intercept /mcp before the static-assets binding serves a file.
Wrangler needs Node.js 22+. This is the single most common "it works in CI but not on my machine" gotcha.
The free tier (100k requests/day) comfortably covers a personal or documentation MCP server.

Why Workers is the right host

The defining trait of a read-only MCP server — one whose tools only fetch data — is that it holds no state between requests. Every tools/call is self-contained. That single fact knocks out the usual reasons you'd reach for a long-lived Node process:

No session store, so nothing to persist between requests.
No warm-up, so cold starts don't hurt — there's no database connection pool to spin up.
Embarrassingly parallel, so horizontal scaling is automatic.

Stateless request/response at global scale is the edge-function sweet spot. Add the practical wins — runs in 300+ locations near your users, scales to zero when idle, and the free tier handles 100,000 requests/day — and Workers stops being a creative choice and becomes the obvious one.

💡 Key insight: Don't add a database or sessions to an MCP server that only reads. Statelessness isn't a limitation here — it's the feature that makes edge hosting trivial.

The whole config: wrangler.toml

Here's the real wrangler.toml running my server. It does three jobs: point at the Worker, bind the static assets, and run the Worker first.

name = "my-site"
compatibility_date = "2024-01-01"
main = "worker/index.ts"

[assets]
directory = "./build"
binding = "ASSETS"
# Run the Worker before serving static assets so our routes (like /mcp)
# are intercepted before the assets binding can short-circuit them.
run_worker_first = true

That's the core of it. main is your Worker entry. The [assets] block lets the same Worker also serve a static site from ./build — handy if, like me, your MCP server lives alongside a real website. If your server is standalone, you can drop the assets block entirely.

The setting everyone misses: run_worker_first

When you attach a static-assets binding, Cloudflare's default is to check for a matching file first and only fall through to your Worker if there's no file. That's great for a plain static site — and quietly broken for an API route.

Without run_worker_first = true, a request to /mcp can get intercepted by the assets layer before your Worker ever sees it. Set it to true and the order flips: your Worker runs first, handles /mcp, and explicitly serves static files for everything else via env.ASSETS.fetch().

If you ever see your MCP endpoint returning a 404 or an HTML page instead of JSON-RPC, this flag is the first thing to check.

Routing the endpoint

With the Worker running first, routing is a path check at the top of fetch, before the asset fallback:

export default {
  async fetch(request: Request, env: Env): Promise {
    const url = new URL(request.url);

    // MCP endpoints — handled before anything else
    if (url.pathname === '/mcp') {
      return handleMcp(request, env.ASSETS);
    }
    if (url.pathname === '/.well-known/mcp/server-card.json') {
      return mcpServerCard(request);
    }

    // Everything else: serve the static site
    return env.ASSETS.fetch(request);
  }
} satisfies ExportedHandler;

Notice handleMcp receives env.ASSETS. That's deliberate: my tools are backed by files the site already publishes (a JSON feed, Markdown pages), and the Worker reads them through the same assets binding. One source of truth, zero duplicated data — the deployment story and the data story are the same story.

// inside a tool: read an asset the site already serves
const res = await assets.fetch(new URL('/feed.json', origin));

Local development

Test before you ship. wrangler dev runs the Worker and serves the static assets locally:

npx wrangler dev
# Ready on http://localhost:8787

Then exercise it with curl — no special client needed:

curl -s -X POST http://localhost:8787/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

⚠️ The Node version gotcha: recent Wrangler (v4+) requires Node.js 22 or newer. If wrangler dev or wrangler deploy errors with a version complaint, you're on an older Node. Switch with nvm use 22 (or fnm). This is the number-one reason a deploy works in CI but fails locally.

Going live

Two ways, pick one:

Manual deploy — one command:

npx wrangler deploy

It bundles the Worker (esbuild, no config needed), uploads your ./build assets, and your server is live globally in seconds.

Git integration (what I use) — connect the repo in the Cloudflare dashboard and every push to main builds and deploys automatically. The build command runs your site build, and the Worker deploys alongside it. After that, publishing is just git push.

Either way, your MCP endpoint is live at https://yourdomain.com/mcp — on your own domain, because the Worker is serving that domain. No separate subdomain, no extra DNS.

Common mistakes

Forgetting run_worker_first. Your /mcp route returns HTML or 404 because the assets binding ate the request. The fix is one line.
Running an old Node. Wrangler v4 needs Node 22+. The error is clear once you read it, but easy to miss in CI logs.
Adding state you don't need. Durable Objects and KV are great tools — and overkill for a read-only server. Stay stateless until a tool genuinely requires continuity.
Not handling OPTIONS/CORS. Browser-based MCP clients send a preflight. Return CORS headers and handle OPTIONS, or those clients silently fail.
Hardcoding the origin. Build asset URLs from the incoming request's origin so the same code works on localhost, preview deploys, and production.

Best practices

Stay stateless. It's the whole reason Workers fits. Earn your way into KV/Durable Objects only when a tool needs memory.
Reuse the assets binding for data. If your server sits alongside a site, read the files it already publishes instead of duplicating content.
Cache where you can. Read-only tool data is cacheable — set Cache-Control on responses backed by static assets.
Pin your Node version. Document Node 22+ in your README and CI so "works on my machine" stays true everywhere.
Test the lifecycle locally. initialize → tools/list → tools/call, plus the edges, against wrangler dev before every deploy.
Use your own domain. Serving /mcp from your primary domain is a stronger trust and discovery signal than a throwaway subdomain.

Conclusion

Hosting an MCP server sounds like infrastructure work and turns out to be a config file. The reason it's that easy is the reason worth internalizing: a read-only MCP server is stateless, and stateless request/response at global scale is exactly what the edge is for. wrangler.toml, run_worker_first, one deploy, your own domain. That's it.

Build the server logic in How to Build a Production MCP Server, then ship it with this. For where MCP fits in the bigger agent picture, see AI Coding Agents — Agentic AI for Developers and LLM Engineering, or read the Cloudflare Workers docs for the platform details.

Explore more: AI Coding Agents · LLM Engineering · Claude Code

Originally published at umesh-malik.com

Keep reading on umesh-malik.com:

Cursor vs Claude Code vs Copilot (2026): Which AI Coding Tool, for What

Umesh Malik — Fri, 12 Jun 2026 20:23:00 +0000

The "best AI coding tool" question is the wrong question. Cursor, Claude Code, and GitHub Copilot aren't three versions of the same thing competing on quality — they're three different interaction models, and the right one depends entirely on what you're doing. Pick by the shape of the work, not the leaderboard.

I use all three, daily, for different jobs. Here's how they actually differ and how to choose — without the marketing.

TL;DR

GitHub Copilot — in-editor assistant. Best for fast autocomplete and lightweight chat, lowest friction, lowest price.
Cursor — AI-first editor. Best when you want agentic multi-file edits and a polished IDE with inline diffs and tab-completion.
Claude Code — terminal agent. Best for autonomous, multi-step tasks across a whole repo, plus scripting and CI.
The real axis is autonomy: Copilot accelerates your typing; Claude Code does the task. Cursor sits in between with an editor wrapped around it.
They're not exclusive. The strongest setup often runs an in-editor tool and a terminal agent.

The one distinction that matters: autonomy

Forget feature checklists for a second. The axis that actually separates these tools is how much work they do on their own:

Copilot completes the line or block you're typing and answers questions in a side panel. You are driving every keystroke; it predicts the next one.
Cursor does that too, but adds an agent that can edit multiple files from a single instruction, with diffs you approve in the editor.
Claude Code takes a goal — "add auth to these endpoints," "migrate this module," "find and fix the failing test" — and plans, edits, runs commands, and iterates across the repo until it's done.

💡 Key insight: Copilot makes you faster. Claude Code does the task for you. Cursor lets you slide between the two in one window. That's the whole comparison in one sentence.

GitHub Copilot

The original, and still the lowest-friction. It lives inside VS Code (and other editors) as inline completions plus a chat panel.

Strengths

Frictionless autocomplete. Best-in-class "finish my line/block" flow.
Deep VS Code + GitHub integration. It's right there, no context switch.
Cheapest of the three, and the easiest to adopt on a team.

Limits

It's an assistant, not an agent. Multi-file, multi-step autonomous work isn't its core model (even as it adds more agentic features).
Output is scoped to what you're editing; it reasons less about the whole repo than a dedicated agent does.

Use it when: you want speed-of-typing gains with zero workflow change.

Cursor

An AI-first fork of VS Code. You get the familiar editor, plus tab-completion, chat, and an agent mode that edits across files with inline diffs.

Strengths

Best of both modes in one place — completion and multi-file agent edits, with a real editor UI.
Inline diffs and approval make agent edits easy to review without leaving the IDE.
Strong codebase-aware context and a polished UX.

Limits

It's another editor. If you're committed to your current setup (Neovim, JetBrains, plain VS Code), switching is a real cost.
Heavier and more opinionated than a completion plugin.

Use it when: you want agentic editing but you live in a GUI editor and want diffs and tab-completion in the same window.

Claude Code

A terminal-based coding agent. You give it a goal; it explores the repo, makes a plan, edits files, runs commands and tests, and iterates — and it's scriptable, so it drops into CI and automation.

Strengths

Genuine autonomy on multi-step, repo-wide tasks: refactors, migrations, "make the tests pass," cross-cutting changes.
Editor-agnostic and scriptable — it's a CLI, so it works with any editor and runs headless in pipelines.
Whole-repo reasoning, guided by a CLAUDE.md that teaches it your project's commands, architecture, and conventions.

Limits

Terminal-first. No inline editor diffs by default; you review changes as a diff in the terminal or your git client.
The autonomy that makes it powerful also means you should scope tasks well and review output — it does a lot per step.

Use it when: the unit of work is a task, not a keystroke — and especially for large or repetitive changes you'd rather delegate.

Side by side

	GitHub Copilot	Cursor	Claude Code
Form factor	Editor plugin	AI-first editor	Terminal agent (CLI)
Interaction	Completions + chat	Completions + chat + agent	Goal → autonomous execution
Autonomy	Low (assist)	Medium (agent in editor)	High (multi-step agent)
Repo-wide reasoning	Limited	Good	Strong
Editor lock-in	None (plugin)	Yes (its own editor)	None (any editor)
Scriptable / CI	No	No	Yes
Best at	Fast autocomplete	Agentic edits + IDE UX	Autonomous tasks & automation

How to actually choose

You want minimal change and faster typing → Copilot.
You want agent power but love a GUI editor with diffs → Cursor.
You want to delegate whole tasks, work editor-agnostic, or automate in CI → Claude Code.
You're a power user → run an in-editor tool for flow and Claude Code in the terminal for the heavy lifting. That combination beats any single tool.

Common mistakes

Judging them on "which has the best model." They all use strong frontier models; the interaction model differentiates them far more than raw model quality.
Expecting Copilot to behave like an agent. Different tool for a different job — don't fault a completion engine for not doing migrations.
Refusing to combine them. Treating it as a single-winner choice leaves value on the table; the tools compose.
Skipping setup on the agentic tools. Cursor's rules and Claude Code's CLAUDE.md are what make their agents good — unconfigured, they underperform.

Conclusion

There's no single winner because they aren't playing the same game. Copilot accelerates your typing, Cursor wraps an agent in a polished editor, and Claude Code autonomously executes whole tasks across your repo. Choose by the shape of the work — and if you do a lot of different work, use more than one.

Going deeper on agentic coding? See AI Coding Agents — Agentic AI for Developers and Claude Code — Guides & Deep Dives, and if you adopt Claude Code, start with how to write a CLAUDE.md that actually helps.

Explore more: AI Coding Agents · Claude Code · LLM Engineering

Originally published at umesh-malik.com

Keep reading on umesh-malik.com:

How to Switch Between Multiple Claude Code Accounts Without Re-Logging In (claude-swap Guide)

Umesh Malik — Fri, 12 Jun 2026 20:22:26 +0000

If you use Claude Code seriously, you have hit the wall: a usage limit pops up mid-task, and the only "official" way to keep going is to /logout, open a browser, run the OAuth dance again, and pray your session state survives. Do that three times a day and it stops being a minor annoyance — it becomes a tax on your focus.

claude-swap is the open-source CLI that deletes that tax. The short answer is simple: it backs up the OAuth credentials for each of your Claude accounts and swaps them in and out of Claude Code's credential store on demand. Switching accounts goes from a 60-second browser ritual to a single command — cswap --switch.

If you searched for how to switch Claude Code accounts, using multiple Claude accounts, or getting past Claude Code rate limits without logging out, this is the practical teardown: what it is, why it exists, how it actually works under the hood, how to use it, and — just as importantly — where it falls short.

TL;DR

claude-swap (CLI: cswap) lets you keep multiple Claude accounts registered and switch the active one in seconds — no logout, no repeated browser OAuth.
It works by backing up and restoring Claude Code's OAuth tokens plus the oauthAccount block in ~/.claude/.claude.json, using OS-native secure storage (macOS Keychain, Windows Credential Manager) where available.
The killer use case is dodging usage limits: when one account taps out, cswap --switch rotates to the next so you keep working.
It is a credential swap, not a live session multiplexer — you must restart Claude Code (or the VS Code extension tab) after switching for it to pick up the new tokens.
It is unofficial, not an Anthropic product. Treat account-juggling as a personal-productivity tool and stay aware of your plan's terms.

What Is claude-swap?

💡 Key insight: claude-swap doesn't run multiple Claude sessions at once. It stores the credentials for several accounts and hot-swaps which one Claude Code sees as "logged in."

claude-swap is a multi-account switcher for Claude Code. You register each account once, and from then on you can rotate between them with a single command instead of logging out and back in through the browser. It works with both the Claude Code CLI and the official VS Code extension, because both read from the same credential store on your machine.

Under the surface it does exactly one clever thing well: it treats your OAuth tokens as a swappable asset. Claude Code keeps the active account's credentials in one place; claude-swap keeps a backup of every account's credentials in its own vault, and "switching" simply means copying the right backup back into the live store.

The tool installs as a Python package and exposes a cswap command. It's MIT-licensed, actively released (27+ releases by mid-2026), and built by the community — not Anthropic.

Why It Exists: The Problem It Solves

Claude Code's value is its flow. You get into a loop with the agent, it's editing files and running tests, and then — limit reached. On Pro and Max plans there are rolling session and weekly caps, and the moment you hit one, the native fix is brutal to your momentum:

/logout out of the current account.
Re-authenticate the second account through a browser OAuth redirect.
Re-establish your working context and hope nothing got lost.

People run into this constantly because having more than one Claude account is normal now, not exotic:

A personal account and a separate work or client-billed account.
Multiple Max subscriptions specifically to extend daily working hours.
A team setup where different accounts map to different billing buckets.

claude-swap exists because the credentials for all those accounts are just files and keychain entries. There's no technical reason switching should require a browser round-trip — so the tool removes it. You pay the OAuth cost once per account, and every switch after that is instant.

The other escape hatch when you're genuinely out of cloud capacity is to stop depending on the cloud at all and run a capable coding model locally. But if you're committed to Claude — and most of us are, for good reason — claude-swap is the pragmatic fix that keeps you in the tool you already like.

What this is — and isn't
claude-swap is a convenience layer over accounts you already own. It is not an Anthropic product, and it does not conjure "free" capacity — every account keeps its own limits and billing. It just removes the browser round-trip between accounts that are yours to begin with.

How claude-swap Works (Under the Hood)

This is where it gets interesting, because the design is refreshingly simple. Claude Code reads its credentials from one location at startup. claude-swap intercepts the backup and restore of that location.

Where the credentials live

The live store is platform-specific, and claude-swap respects each platform's conventions:

macOS — the system Keychain, under the service name Claude Code-credentials.
Linux / WSL — a plaintext file at ~/.claude/.credentials.json.
Windows — the Credential Manager, plus the oauthAccount section of ~/.claude/.claude.json.

claude-swap keeps its own backups in a vault directory (~/.local/share/claude-swap/ on Linux, ~/.claude-swap-backup/ elsewhere), with one slot per account.

claude-swap/
├── credentials/
│   ├── .creds-1-you@personal.com.enc
│   └── .creds-2-you@work.com.enc
├── configs/
│   ├── .claude-config-1-you@personal.com.json
│   └── .claude-config-2-you@work.com.json
└── sequence.json        # tracks slots + rotation order

The switch lifecycle

That rollback behavior is the part most "swap a config file" hacks get wrong. claude-swap treats the swap as a transaction with recorded steps (credentials_written, config_written, sequence_updated), so a failure halfway through reverts cleanly instead of stranding you.

The one thing it can't avoid: Claude Code only reads credentials at startup. After a switch, you have to restart the CLI or close and reopen the VS Code extension tab. It's the small price for the fact that nothing has to be patched live.

How To Use claude-swap

Installation

The recommended path is uv, but pipx works just as well:

# Recommended
uv tool install claude-swap

# Or with pipx
pipx install claude-swap

# From source
git clone https://github.com/realiti4/claude-swap
cd claude-swap
uv sync

Upgrades are equally boring (the good kind):

uv tool upgrade claude-swap      # or: pipx upgrade claude-swap
cswap --upgrade                  # self-update from PyPI

Register your accounts

You add accounts one at a time. Log into the account you want to capture first (via normal Claude Code login), then register it:

# Log into account A in Claude Code, then:
cswap --add-account

# Switch the Claude Code login to account B, then:
cswap --add-account

Each --add-account captures whoever is currently logged in. When a token later expires, re-run cswap --add-account for that account — it updates the existing slot rather than creating a duplicate.

Switch, list, and check status

cswap --switch              # rotate to the next account in sequence
cswap --switch-to 2         # switch to a specific slot number...
cswap --switch-to you@work.com   # ...or by email
cswap --list                # show accounts, usage metrics, and reset times
cswap --status              # show which account is active right now
cswap --tui                 # interactive menu with keyboard navigation

After any switch, restart Claude Code or reopen the VS Code extension tab. That's the whole loop.

Headless and CI: register by token

On a server with no browser, you can't do interactive OAuth. claude-swap lets you register an account directly from a setup token:

cswap --add-token sk-ant-oat01-...      # or pipe via stdin with: --add-token -

Move accounts between machines

Export creates a portable .cswap file; import restores it on another machine:

cswap --export backup.cswap             # all accounts
cswap --export backup.cswap --account 2 # just one
cswap --import backup.cswap             # restore (use --force to overwrite)

Export files contain live credentials
A .cswap export holds real OAuth tokens. Treat it like a password file — don't commit it, don't drop it in shared storage, and delete it once the migration is done.

Command reference

When To Use It (and When Not To)

What claude-swap Still Misses

No hype here — this is a small, focused tool, and its gaps are real. If you're deciding whether to adopt it, weigh these honestly.

💡 Key insight: The biggest missing feature is automation. claude-swap makes a switch cheap, but you still have to decide to switch. A future version that watches --list usage data and rotates on its own would close the loop.

Best Practices

How It Compares To The Alternatives

FAQ

Final Take

claude-swap is the kind of tool that shouldn't need to exist — and that's exactly why it's good. Anthropic gives you a credential store and a login flow; claude-swap notices that "switching accounts" is really just "swap two files and a keychain entry," and turns a 60-second browser ritual into one command.

It's not magic. It won't auto-rotate when you hit a limit, it makes you restart after every swap, and it centralizes real OAuth tokens on your machine — so it's a personal-productivity tool, not an enterprise credential platform. Know those edges and they won't surprise you.

But if you live in Claude Code and bounce between accounts more than once a day, the math is obvious: pay the OAuth cost once per account, then never pay it again. For a free, MIT-licensed CLI, that's a remarkably good trade.

If you found this useful, read how Anthropic Code Review fits into Claude Code next — it's the clearest signal of where the rest of the Claude Code workflow is heading, beyond the account you happen to be logged into.

Sources

Written for umesh-malik.com — no-fluff technical writing on AI, Web Dev, and Engineering.

Originally published at umesh-malik.com

Keep reading on umesh-malik.com:

Claude Code Leak 2026: What Escaped, What Stayed Locked, and the Copyright Irony No One Is Talking About

Umesh Malik — Fri, 12 Jun 2026 20:22:25 +0000

The Claude Code source-map leak on March 31, 2026 was not a Hollywood breach. It was a mundane packaging mistake that briefly put ~512k lines of TypeScript orchestration logic on the public internet. Within hours, the repo topped GitHub's trending charts and Anthropic fired off DMCA notices - accidentally hitting forks of their own official repository in the process.

The model weights and customer data never left the vault, but the architectural blueprint did. And the internet's reaction? Let's just say developers had opinions about what they found inside.

The fast version (TL;DR)

An npm publish of @anthropic-ai/claude-code@2.1.88 accidentally shipped a massive cli.js.map, exposing the full CLI/agent orchestration codebase.
The leak gives competitors architectural insight and reveals unreleased toggles (like always-on daemon mode, KAIROS flags, and a "buddy" Tamagotchi-like companion experiment). It does not give anyone Claude's model weights, safety data, or hosted inference stack.
Developers roasted the code quality online - calling it "vibe coded garbage" - but the $2.5B ARR product proves that product-market fit beats code polish.
Anthropic yanked the bad package, issued DMCA notices that briefly overreached (hitting their own repos), and is rotating internal keys plus tightening pre-publish checks.
Clean-room reimplementations in Python and Rust appeared within 48 hours, sparking debates about AI copyright that mirror the industry's own training data controversies.
For teams: clear caches of 2.1.88, upgrade, document removal for audit, and avoid touching leaked repos to stay clear of copyright and CFAA trouble.

What actually leaked vs. what did not

Leaked

TypeScript orchestration for Claude Code's CLI, tool adapters, agent lifecycle, and feature flags.
Internal naming and roadmap hints (e.g., KAIROS, daemon, "buddy" Tamagotchi-like companion experiments).
Safety-bypass affordances visible in code paths that handle prompt and tool execution order.

Not leaked

Claude model weights, safety datasets, or training recipes.
Production API keys or customer artifacts.
Hosted inference stack and scaling primitives that make Claude Code performant in production.

Why that matters
The leak is closer to blueprint theft than product theft. You can study the architecture, but you cannot run Claude Code at parity without Anthropic's hosted models and alignment stack. That is why "not everything is available for public usage" is literally true: the brains and the serving muscle stayed private.

What developers found (and what they said about it)

The code quality debate became almost as viral as the leak itself. Within hours of mirrors appearing, developers were dissecting the codebase and sharing their takes:

"Vibe coded garbage that's making $2.5B ARR. The state of software in 2026."

"This is what happens when you ship fast and iterate. It works. The code does not have to be beautiful."

"I've seen worse in production at Fortune 500s. At least this actually works."

The reactions split into two camps:

Camp 1: "This proves code quality does not matter"

The codebase appeared rapidly developed, with shortcuts and patterns that would not pass a traditional code review
Yet Claude Code captured ~$2.5B in annualized recurring revenue in under a year
The lesson: product-market fit and user experience trump architectural purity

Camp 2: "This is exactly why AI-generated code is concerning"

Critics argued the codebase reflected the output of AI-assisted development pushed too fast
The leaked source showed patterns consistent with LLM-generated code that was accepted without thorough review
The counter-argument: does it matter if it works and ships?

The uncomfortable truth
The real competitive advantage was never the code. OpenAI's Codex and Google's Gemini CLI are already open source. Claude Code dominates because of the seamless integration between the harness and Anthropic's models - not because the TypeScript is elegant.

The DMCA chaos: when Anthropic accidentally took down their own repos

Anthropic's response was swift - perhaps too swift. According to TechCrunch, the company "took down thousands of GitHub repos trying to yank its leaked source code," which they later characterized as "an accident."

What went wrong:

Anthropic issued broad DMCA takedown requests targeting any repository containing Claude Code patterns
The net caught forks of their own official github.com/anthropics/claude-code repository
Legitimate open-source contributions, examples, and tutorials were temporarily nuked
Developer backlash forced Anthropic to narrow the scope

The scale:

Initial sweep: ~8,100 repositories flagged
After correction: Focus narrowed to repos containing actual leaked source map content
Collateral damage: Unknown number of legitimate projects temporarily affected

The irony: Anthropic, a company that has been sued for training on copyrighted content, aggressively pursued copyright enforcement against developers who may have been doing nothing more than forking their public repository.

Timeline you can brief leadership with

The copyright irony nobody wants to talk about

Here is where the story gets uncomfortable. Within 48 hours of the leak, "clean-room implementations" of Claude Code started appearing - developers rewrote the functionality from scratch in Python and Rust, using the leaked code as a reference for architecture but not copying it directly.

Their argument? The same one AI companies use to justify training on copyrighted content:

"Using AI to rewrite content does not constitute derivative work. This is how learning works."

The debate:

Anthropic has been sued for training on copyrighted books, articles, and code without permission
Anthropic argues this is "transformative fair use" and "how learning works"
Developers now use the same argument to justify clean-room reimplementations of Claude Code
Critics call it "Anthropic getting a taste of their own medicine"

The legal reality:

Violating API ToS through fraudulent accounts is clearer legal ground than training data questions
But the clean-room reimplementers are not using fraudulent accounts - they are rewriting from public observation
The frameworks for both situations remain unsettled and actively litigated

The uncomfortable parallel
The AI industry built norms around training on internet content that favor their business models. Now they are upset when others apply similar logic to their outputs. Whether there is a meaningful legal distinction remains unclear - but the optics are hard to ignore.

How the leak changes the game (even without weights)

Faster Claude-like clones - Open-model teams can mirror the orchestration pattern with their own models, compressing their time-to-market for developer agents.
Better red-team playbooks - Seeing how Claude Code sequences tools and guards prompts gives attackers a richer map for prompt-injection and tool-escape tests.
Enterprise procurement friction - Security and legal teams will now ask for stronger SBOMs, pre-publish gates, and attestation from any agent toolchain vendor, not just Anthropic.
Legal chill for builders - Using the leaked code directly risks DMCA/CFAA exposure; clean-room reimplementation or open alternatives (e.g., bespoke SvelteKit/Vite agents) are safer paths.
Architectural commoditization - The leak confirms that agent harnesses are largely interchangeable; the model is the moat.

What to do if you run Claude Code (or ship agents like it)

Purge and upgrade: Delete caches and lockfiles pointing to @anthropic-ai/claude-code@2.1.88; install the latest fixed release.
Rotate anyway: Even though no secrets leaked, rotate CLI tokens and workstation credentials as a hygiene move.
Gate your own publishes: Add CI checks that block source maps or unusually large artifacts from going to npm/registries.
Document removal: Keep an audit trail (ticket + commit) noting removal of the leaked artifact to prove non-use in case of legal scrutiny.
Monitor copycats: Set GitHub/npm alerts for packages mimicking Claude Code behaviors; add detection rules for suspicious agent execution patterns.

Legal line to keep clear
Downloading or reusing the leaked repository is still copyright infringement. If you need to study the architecture, do it through reporting, decompiled snippets in news coverage, or by reconstructing patterns from your own builds - not by hosting the leaked zip.

Reader-friendly checklist: is this "free Claude Code"?

Can you run Claude locally now? No. You still need Claude model weights and Anthropic's hosted inference; neither leaked.
Can you strip safeguards? You can study how safeguards are wired, which helps red-teamers, but production Claude safety lives in weights + policies you do not have.
Is there sensitive customer data? Anthropic says no customer or key material was inside the source map.
Is Anthropic's reputation hurt? Yes - supply-chain trust took a hit - but capability control remains intact.

FAQ

The bigger picture

This leak is a window into three truths the AI industry does not like to discuss:

Code quality is overrated - A "vibe coded" codebase is powering one of the fastest-growing AI products in history. Product-market fit and user experience beat architectural elegance every time.
The real moat is the model - Claude Code's source is now public knowledge, but competitors cannot replicate the experience without Anthropic's models. The harness is commodity; the AI is the product.
Copyright norms cut both ways - AI companies have spent years arguing that learning from copyrighted content is fair use. They cannot be surprised when others apply that logic to their outputs.

Closing

The leak hands the world a blueprint, not a working product. If you are a builder, treat it as a reminder to harden your own release pipelines. If you are an enterprise buyer, update your SBOM and publishing checks. And if you are tempted to grab the code from a mirror - do not. The parts you want most never left Anthropic's servers.

The official github.com/anthropics/claude-code repository remains active with 104k stars and 16.4k forks. That is where the legitimate skills, tutorials, and examples live. Everything else is legal risk without the actual value.

Sources: Axios reporting on the March 31 leak, TechCrunch on the DMCA overreach, build.ms analysis of code quality observations, GitHub trending data, and community discussions on Hacker News and Twitter/X.

Originally published at umesh-malik.com

Keep reading on umesh-malik.com:

ChatGPT Now Teaches Math and Science With Interactive Visuals — What You Need to Know

Umesh Malik — Fri, 12 Jun 2026 20:21:54 +0000

OpenAI launched interactive math and science visuals in ChatGPT on March 10, 2026, and this is exactly the kind of AI update that normal people will care about immediately.

Not because it wins another benchmark. Not because it adds a new model name. But because it changes one of the most common real-world uses of ChatGPT: trying to understand something hard.

The short answer is simple: ChatGPT is moving from "explaining a concept" to "letting you explore a concept." Instead of only reading a paragraph about slope, pressure, or the Pythagorean theorem, users can now manipulate variables, see relationships update, and build intuition visually.

That matters everywhere, but it is especially relevant in the United States. Gallup found that 60% of U.S. adults feel challenged by doing math, and parents who feel better about math are far more confident helping their children with it. At the same time, OpenAI already has a free ChatGPT for Teachers plan for verified U.S. K-12 educators through June 2027. So this is not just a product update. It is an education-distribution story with a clear U.S. audience from day one.

TL;DR

OpenAI launched interactive math and science visuals in ChatGPT on March 10, 2026.
OpenAI says more than 140 million people already use ChatGPT for math and science each week.
The feature starts with 70+ core concepts and lets users interact with ideas visually instead of only reading text explanations.
OpenAI’s examples include topics like the Pythagorean theorem, slope-intercept form, ideal gas law, Charles' law, Hooke's law, kinetic energy, lens equation, compound interest, and exponential decay.
As of March 12, 2026, OpenAI says rollout is going to all logged-in ChatGPT users across plans.
This is especially relevant in the U.S., where Gallup found 60% of adults feel challenged by math and OpenAI already offers ChatGPT for Teachers free through June 2027 for verified U.S. K-12 educators.
The biggest shift is conceptual: ChatGPT is becoming more exploratory and less purely answer-based.
The biggest limitation is also obvious: interactive visuals do not remove the need for teachers, verification, or real understanding.

What OpenAI Actually Launched on March 10, 2026

The official OpenAI framing is straightforward.

ChatGPT can now generate interactive learning visuals for math and science topics. Instead of explaining everything in static text, the product can show relationships visually and let the learner change inputs to see what happens.

That sounds simple, but it changes the experience in an important way:

text answers tell you what a concept is
interactive visuals help you feel how a concept behaves

For learning, that difference is huge.

If a student changes the slope in a line equation and sees the line rotate, or changes pressure and temperature in a gas law example and watches the relationship update, the concept stops being just another memorized statement. It becomes something they can inspect.

Availability note
OpenAI says rollout started on March 10, 2026 for logged-in ChatGPT users across plans. If you do not see the new experience on a given topic yet, that can be topic coverage or rollout timing rather than a plan limitation.

Why This Story Is Bigger in the U.S.

This is where the audience targeting matters.

If you write this as generic AI product news, it looks like another feature release. If you write it from the perspective of the people most likely to care, it becomes much more interesting:

students who already use ChatGPT for homework and test prep
parents trying to help with math or science at home
teachers deciding what productive AI use should actually look like

The U.S. angle is especially strong for two reasons.

First, Gallup found that 60% of U.S. adults feel challenged by doing math, and parents with more positive math feelings are much more confident helping their children. That means a tool that can make concepts clearer is not just a student story. It is a family story.

Second, OpenAI has already built a specific U.S. education distribution path. In November 2025, it launched ChatGPT for Teachers, free through June 2027 for verified U.S. K-12 educators. That means the new student-facing visual layer and the U.S.-teacher product story now reinforce each other.

This is why the launch has real mainstream-read potential. It is AI, but it is also:

homework help
parent confidence
classroom workflow
education anxiety
a familiar consumer product people already use

That combination is stronger than a typical model release.

OpenAI’s Education Stack Is Getting Clearer

The easiest way to understand this launch is to stop treating it as a random feature and start treating it as another layer in OpenAI’s education strategy.

That stack makes strategic sense.

study mode helps with pedagogy
interactive visuals help with conceptual intuition
teacher workspaces help with real classroom adoption

Individually, each feature is useful. Together, they suggest OpenAI is serious about being part of the learning workflow, not just a generic chatbot students occasionally visit.

What Topics Matter Most at Launch

OpenAI’s examples are revealing.

This is not a launch built around obscure graduate-level edge cases. The emphasis is on concepts that are:

common in school
visually teachable
painful to explain with text alone
familiar enough that parents and teachers immediately understand the value

Examples OpenAI highlighted include:

Pythagorean theorem
slope-intercept form
difference of squares
area of a circle
surface area of a cone
ideal gas law
Charles' law
Coulomb's law
Hooke's law
kinetic energy
lens equation
compound interest
exponential decay

That list is the real clue.

OpenAI is not trying to start with “everything.” It is starting with concepts that sit at the intersection of:

high student demand
high parent-recognition value
strong visual payoff
clear classroom relevance

How To Get the Most Useful Experience Tonight

Most people will get more value from this feature if they use it like a learning tool, not like a shortcut machine.

Where This Still Falls Short

This launch is strong, but the wrong expectations will ruin it.

The biggest mistake would be to frame this as “AI solves education now.”

That is not what happened.

What happened is more useful and more believable: OpenAI made ChatGPT better at helping people build intuition in subjects that often feel abstract, intimidating, or hard to explain with words alone.

Final Take

This is one of the most readable, mainstream AI stories of March 2026 because the value is instantly legible.

People do not need to understand model architecture to care about this. They only need to recognize one of these situations:

“My child is stuck on math homework.”
“I never felt confident in math myself.”
“I teach students who need a better visual explanation.”
“I want ChatGPT to help me understand, not just answer.”

That is why this update matters.

OpenAI is clearly pushing ChatGPT toward a broader learning role:

study mode for guided thinking
teacher tools for classroom adoption
interactive visuals for concept exploration

For U.S. readers in particular, that combination is compelling because it lands right where the pain already is: homework stress, math anxiety, parent confidence, and teacher workload.

If OpenAI executes this well, the long-term win is not that ChatGPT becomes a better cheat sheet. The long-term win is that it becomes a more usable bridge between confusion and understanding.

That is a much more important product story.

FAQ

Sources

Originally published at umesh-malik.com

Keep reading on umesh-malik.com:

ChatGPT \"Adult Mode\": What OpenAI's Delayed Feature Means for U.S. Adults, Parents, and Privacy

Umesh Malik — Fri, 12 Jun 2026 20:21:53 +0000

OpenAI's reported ChatGPT "adult mode" is one of those AI stories that sounds narrow until you translate it into normal human terms.

This is not really a niche feature story. It is a mass-market internet policy story about what happens when a product used by hundreds of millions of people tries to give adults more conversational freedom without making life less safe for teenagers.

The first fact to keep straight is the most important one: as of March 16, 2026, ChatGPT adult mode is not live. What exists right now is a mix of public reporting about the planned feature and official OpenAI documents about age prediction, teen experiences, and parental controls.

For U.S. readers, that combination matters more than the headline alone suggests. Adults care about whether ChatGPT should stop acting overly paternalistic. Parents care about whether under-18 users could slip into the wrong experience. Privacy-sensitive users care about whether age checks turn into selfie or ID verification. That is why this story is drawing attention well beyond tech circles.

Important status check
As of March 16, 2026, OpenAI has not launched adult mode and has not announced a new public release date. The product shape below is based on official OpenAI safety materials plus reporting from Axios, TechCrunch, and The Verge.

TL;DR

ChatGPT adult mode is still delayed as of March 16, 2026.
On March 6, 2026, Axios and TechCrunch reported that OpenAI delayed the feature again because it needed more time to get it right.
On March 16, 2026, The Verge reported that the expected launch version was text-only, not an all-media adult product.
The reporting suggests the feature is aimed at verified adults, not general users and not minors.
OpenAI's own safety roadmap already includes age prediction for suspected teens, more restrictive under-18 experiences, and parental controls.
The real public-interest question is not "Will ChatGPT get more explicit?" It is whether a mass-market AI product can give adults more latitude without weakening youth safety or pushing users into invasive age checks.
For U.S. readers, this is especially relevant because it intersects with family use, college-age users, online safety, privacy expectations, and mainstream platform policy.

Is ChatGPT adult mode live right now?

No.

That point matters because a lot of social chatter makes this sound like a launch. It is not. The cleanest way to describe the situation on March 16, 2026 is this:

the feature has been reported publicly
the product direction is fairly clear
the launch is still delayed

Axios reported on March 6, 2026 that OpenAI pushed the feature back again. TechCrunch separately reported the same delay. Then on March 16, 2026, The Verge added more detail about the planned shape of the rollout, saying the first version was expected to focus on adult text conversations, not images, voice, or video.

That means the story people should read is not "OpenAI launched porn in ChatGPT." The story is closer to this:

OpenAI appears to be building a more permissive adult conversational mode, but it still does not think the safety, age-gating, and policy edges are ready enough to ship publicly.

What would ChatGPT adult mode actually allow?

Based on the reporting available as of March 16, 2026, the likely launch direction is narrower than many people assume.

The feature is being discussed as an adult text experience, not a full adult-content platform. The Verge reported that the planned rollout was expected to be text-only at first. That is a very different proposition from enabling adult images, live visual generation, or voice-first erotic roleplay.

That distinction matters because it changes how readers should evaluate the story:

this is about conversational permissiveness
not an immediate shift into all-format explicit media

The strategic shift underneath all of this is simple.

OpenAI has been moving toward the idea that adults should get a more adult-appropriate experience, while under-18 users should get a tighter one. "Adult mode" is just the most attention-grabbing version of that policy direction.

Why did OpenAI delay it?

This is where the story becomes more important than the headline.

If OpenAI were only optimizing for adult-user demand, it likely would have shipped sooner. The fact that it did not tells you that the company thinks the downside risk is real.

The public reporting points to a cluster of concerns:

whether under-18 users could still slip through
whether age prediction is reliable enough for a high-risk feature
whether adult users would accept stronger verification when the system is uncertain
whether OpenAI can defend the product decision politically if something goes wrong

The Verge's March 16 report, citing Wall Street Journal reporting, described internal concern around child-safety implications. That lines up with OpenAI's own official materials, which already show a clear policy hierarchy: when there is tension between adult freedom, teen safety, and verification accuracy, the company is willing to add friction rather than move fast.

The takeaway is not "OpenAI changed its mind."

The takeaway is that OpenAI seems to believe the product idea is directionally right, while the deployment conditions are still fragile.

Why this matters so much to U.S. adults, parents, and college-age users

This is where the audience targeting really matters.

If you write this story as generic AI gossip, it looks unserious. If you write it from the standpoint of the people most likely to care, it becomes obviously mainstream:

adult ChatGPT users who want a less restrictive assistant
parents who do not want teens routed into adult experiences by mistake
college-age users who sit near the adult threshold but still care about privacy and identity checks
households where ChatGPT is already a shared, familiar product

The U.S. angle is especially strong because OpenAI's parental-control rollout was built with organizations and regulators that U.S. families instantly recognize, including Common Sense Media and the attorneys general of California and Delaware. That makes this more than an internal platform experiment. It is part of a broader public-facing trust strategy.

OpenAI also now says ChatGPT reaches 900 million weekly users, which changes the stakes. Once a product is that mainstream, an adult-content policy debate is no longer about edge-case users. It becomes a platform-governance question that ordinary adults, parents, and students understand immediately.

The real tension: adult freedom, teen safety, and verification privacy

This is the part most headlines flatten.

OpenAI is trying to satisfy three groups that do not want the same thing:

Adults who want the model to stop refusing every mature topic by default.
Parents and safety advocates who want strong barriers around teen access.
Privacy-sensitive users who do not want a casual chatbot turning into an ID-check funnel.

Those goals can conflict quickly.

If you make the adult experience too easy to reach, critics will say teens can slip through. If you make it too hard to reach, adults will say the product is infantilizing them. If you solve the problem with aggressive verification, another set of users will object that the privacy cost is too high.

That is why this story matters. It is not only about sexual content. It is about how mainstream AI products decide who gets what kind of freedom, under what level of certainty, with what amount of personal-data friction.

What to watch before OpenAI ships it

This is the practical section.

If you want to know whether OpenAI is actually ready to launch adult mode, ignore the loudest hot takes and watch for concrete implementation details.

Those details will tell you more than any headline ever will.

Final take

The most useful way to understand ChatGPT adult mode is not as "OpenAI wants erotica in ChatGPT."

The more accurate read is this:

OpenAI is trying to draw a sharper line between what adults can do, what teens cannot do, and how confidently the product can tell the difference.

That is why the story has traction. It touches several instincts at once:

adult autonomy
parenting anxiety
teen online safety
privacy around age verification
trust in a chatbot that now operates at mass-market scale

For U.S. readers especially, that is a highly clickable and highly relevant combination. It is about the kind of AI platform ChatGPT is becoming inside ordinary households, campuses, and daily life.

If OpenAI eventually ships this well, the long-term story will not just be "adult mode exists." The long-term story will be that ChatGPT became more explicitly age-tiered, and that a mainstream AI company finally had to show how adult freedom, child safety, and privacy can coexist in one product.

That is the real story worth following.

FAQ

Sources

Originally published at umesh-malik.com

Keep reading on umesh-malik.com:

Nvidia OpenClaw Explained: What It Means for Your AI Agent Strategy (GTC 2026)

Umesh Malik — Fri, 12 Jun 2026 20:20:11 +0000

On March 17, 2026, Business Insider reported that Jensen Huang told GTC attendees every company "needs to have an OpenClaw strategy."

That line sounds like classic conference theater until you translate it into plain English.

Nvidia is saying the next enterprise AI decision is not just which model or which chip you buy. It is whether your company has a plan for AI agents that can actually do work, plus the control layer that keeps those agents from becoming a governance nightmare.

That is the real story.

If you searched for Nvidia OpenClaw strategy, what NemoClaw means, or why Nvidia cares about AI agents now, the short answer is this: Nvidia thinks AI is moving from answering questions to completing tasks, and it wants to own more of that stack than GPUs alone.

Important status check
The phrase "OpenClaw strategy" comes from current reporting around GTC 2026. Nvidia's wider GTC materials clearly emphasize agentic AI, but some of the more detailed OpenClaw and NemoClaw framing is still coming through reporting from Business Insider, The Wall Street Journal, WIRED, and Ars Technica rather than one single Nvidia product page.

TL;DR

On March 17, 2026, Business Insider reported that Jensen Huang told GTC attendees every company "needs to have an OpenClaw strategy."
Nvidia's own GTC 2026 materials already make the broader context clear: the company is centering agentic AI, AI factories, and physical AI.
The practical meaning is simple: Nvidia thinks the next AI wave is about agents that complete work, not only chatbots that answer prompts.
Reporting from Business Insider, The Wall Street Journal, WIRED, and Ars Technica suggests Nvidia is pairing that OpenClaw push with NemoClaw, a more secure enterprise layer around agent execution.
The strategic bet is that companies will need a plan for where agents act, what tools they can touch, how they are observed, and how they are stopped when something goes wrong.
That makes this more than another silicon story. It is Nvidia pushing upward from chips into runtime, governance, and enterprise software control.
For U.S. enterprises, the immediate relevance is strongest in regulated, high-trust workflows where "agentic AI" only matters if it can be deployed safely.

What does Jensen Huang mean by an OpenClaw strategy?

The most useful way to read the line is not as product branding but as a strategic instruction.

An OpenClaw strategy means your company needs a point of view on all of the following:

which business tasks AI agents should actually perform
which tools and systems those agents can access
what approval, monitoring, and rollback model surrounds them
how you keep agents useful without letting them become an enterprise liability

That is the real leap from chatbot thinking to agent thinking.

In the chatbot era, the core question was: Which model gives us the best answer?

In the agent era, the better question is: Which system can safely take action inside our workflow?

That shift is why the phrase matters.

Why Nvidia thinks AI is moving from queries to tasks

This is the key learning inside the story.

The old mental model of AI was mostly prompt in, answer out. That model is still useful, but it is increasingly incomplete for enterprise work.

Nvidia is clearly pushing a new framing:

a user or system assigns a goal
the agent plans a sequence of actions
the runtime manages tool access and execution
the company audits what happened and decides how much autonomy is acceptable

That is a much bigger systems problem than autocomplete or chat.

My inference from the current sources is that Nvidia is trying to make this mental shift feel inevitable. It wants companies to think: if cloud strategy became mandatory, and mobile strategy became mandatory, then agent strategy will become mandatory too.

Where NemoClaw fits, and why it matters

This is where the story becomes more interesting than a slogan.

Reporting from Business Insider, The Wall Street Journal, WIRED, and Ars Technica suggests Nvidia is also advancing NemoClaw, which reads less like a flashy public phrase and more like the answer to the real enterprise question:

How do you let AI agents do useful work without giving them unsafe freedom?

That is the part CIOs, CISOs, and platform teams actually care about.

If OpenClaw is the ambition, NemoClaw appears to be the control layer around that ambition.

Why this is bigger than another chip story

If you only read this as Nvidia hype, you will miss the deeper signal.

The official Nvidia GTC framing and the recent reporting point in the same direction: Nvidia is trying to extend its relevance upward through the stack.

The point is not that Nvidia suddenly stopped caring about chips.

The point is that chips alone are no longer enough to define the strategic narrative. The next fight is around how agents are deployed, how safe they are, and which company becomes the trusted layer between the model and the enterprise workflow.

That is a much more durable market position.

Why this matters so much to U.S. companies right now

This is where the audience targeting matters.

For a broad U.S. business audience, the relevance is immediate because the story sits at the overlap of:

enterprise productivity pressure
AI automation ambition
regulatory and legal caution
security and data-governance reality

My inference from Nvidia's framing and the surrounding reporting is that the company is speaking directly to the people who approve enterprise AI budgets in the United States:

CTOs deciding where agents are allowed to act
CIOs trying to standardize enterprise AI stacks
CISOs worried about tool abuse and data leakage
product and ops leaders looking for cost-effective automation that does not blow up governance

That is why this story is more teachable than a normal conference recap. It gives readers a practical new lens:

The real bottleneck in enterprise AI is no longer only intelligence. It is controlled execution.

If your company agrees with Nvidia, the next move is operational

This is the step most teams skip.

They hear the strategic message, buy into the future, and then fail to translate it into a controlled rollout model. If you actually think OpenClaw-style planning matters, the right response is not "launch more agents." It is to narrow the scope and raise the discipline.

What teams should ask before adopting an OpenClaw strategy

If the phrase sticks, a lot of teams will repeat it without translating it into operational questions.

That would be a mistake.

That is the difference between having a buzzword and having a strategy.

Final take

The most useful reading of Nvidia's OpenClaw strategy line is not "Jensen Huang said something catchy at GTC."

It is this:

Nvidia is trying to convince the market that AI agents are becoming a first-class enterprise planning problem, and that the winning companies will need a secure runtime around those agents, not just a smart model and fast hardware.

That is a meaningful shift.

It tells you where the AI market is going:

from copilots to agents
from prompts to tasks
from model choice to runtime control
from demo intelligence to enterprise trust

For U.S. companies, that is a timely message because the next wave of AI adoption will be judged less by how impressive the model sounds and more by whether the system can safely act inside real workflows.

That is why this is worth paying attention to.

FAQ

Sources

Originally published at umesh-malik.com

Keep reading on umesh-malik.com:

Build a RAG Pipeline From Scratch (Production Patterns That Actually Matter)

Umesh Malik — Fri, 12 Jun 2026 20:19:37 +0000

Most RAG tutorials stop at "embed your docs, do a similarity search, stuff the results in a prompt." That gets you a demo. It does not get you something that gives correct, grounded answers on real data — and the gap between those two is where all the actual engineering lives.

A RAG pipeline is a series of stages, and a weak link in any one of them caps the quality of the whole thing. You can have a frontier model and a beautiful prompt, and still ship garbage if your chunking is wrong. So this is the pipeline end to end, with the production patterns that decide whether it works — not just the happy-path demo.

If you're still deciding whether RAG is even the right tool versus fine-tuning, read RAG vs Fine-Tuning for LLMs first. This post assumes you've decided to retrieve.

TL;DR

RAG is a pipeline: ingest → chunk → embed → store → retrieve → generate. The output is only as good as the weakest stage.
Retrieval quality is everything. Most "the LLM hallucinated" bugs are actually "the right chunk never got retrieved" bugs.
Chunk on meaning, not character counts. Semantic boundaries plus light overlap beat fixed-size splits.
Don't rely on vector search alone. Hybrid (keyword + vector) retrieval with a reranker is the production default.
Ground the generation. Pass only retrieved context, require citations, and refuse when context is thin.
You can't improve what you don't measure. Build a retrieval eval before you tune anything.

The pipeline, stage by stage

1. Ingestion

Load your sources and clean them before anything else. Strip boilerplate, nav chrome, and duplicated headers/footers. Garbage in here propagates through every downstream stage and you'll never trace the bad answer back to it. Preserve structure — headings, lists, tables — because that structure is what makes good chunking possible.

2. Chunking — where most pipelines quietly fail

Chunking is the highest-leverage, most-underrated stage. The naive move is to split every document into fixed 500-character windows. Don't. Fixed-size splitting severs sentences and merges unrelated ideas, and then retrieval surfaces fragments that don't mean anything on their own.

Instead:

Split on semantic boundaries — headings, paragraphs, list items. Respect the document's own structure.
One idea per chunk. A chunk should be retrievable and self-contained.
Add light overlap so context isn't cut mid-thought between adjacent chunks.
Attach metadata to every chunk: source, title, section, date, URL. You'll use it for filtering and citations.

chunk = {
  id, text,
  metadata: { source, title, section, url, date }
}

💡 Key insight: If retrieval is bad, fix chunking before you touch the model or the prompt. The retriever can only find what chunking made findable.

3. Embedding

Turn each chunk into a vector with an embedding model. Two rules that save pain later:

Embed the same way at index time and query time. Same model, same preprocessing. A mismatch silently wrecks relevance.
Version your embeddings. When you change the embedding model, you must re-embed the whole corpus. Track which model produced which vectors so you know when a reindex is due.

4. Storage

Store vectors in an index that does fast similarity search with metadata filtering. You don't necessarily need a dedicated vector database — pgvector on the Postgres you already run handles a surprising amount before a specialized store (Qdrant, Weaviate, Pinecone) earns its keep.

What actually matters: filtering. "Search only this customer's docs" or "only documents from the last year" is a metadata WHERE clause combined with vector similarity. Without it, retrieval leaks across boundaries it shouldn't.

5. Retrieval — go hybrid, then rerank

This is the stage that most separates a demo from a product.

Vector search alone is not enough. Embeddings are great at semantic similarity and bad at exact matches — error codes, product SKUs, proper nouns, acronyms. Keyword search (BM25) is the opposite. Hybrid retrieval runs both and merges the results, so you catch both "what they meant" and "the exact term they typed."

Then rerank. Initial retrieval optimizes for recall — pull a generous candidate set (say, top 20). A cross-encoder reranker then scores those candidates against the query far more precisely and keeps the top handful you'll actually pass to the model. Retrieve broad, rerank narrow.

candidates = vectorSearch(q, k=20) ∪ keywordSearch(q, k=20)
top = rerank(q, candidates)[:5]

6. Grounded generation

Now — and only now — the LLM. The job here is to keep it honest:

Pass only the retrieved context. Don't let the model fall back on parametric memory for facts it should be reading.
Require citations. Ask it to cite the chunk/source for each claim. Citations are both a UX feature and a hallucination check.
Give it permission to say "I don't know." If the retrieved context doesn't answer the question, the correct output is a refusal, not a confident guess. Tell it that explicitly.

System: Answer ONLY from the context below. Cite sources by id.
If the context doesn't contain the answer, say you don't know.

Context:
[1] {chunk_1}
[2] {chunk_2}
...

Question: {user_query}

The patterns that separate prod from demo

Hybrid + rerank, not bare vector search. The single biggest quality jump.
Metadata filtering for security and scoping — never retrieve across tenant or permission boundaries.
Citations and refusal wired into the prompt, so wrong answers become "I don't know" instead of confident fiction.
Caching. Cache embeddings (don't re-embed unchanged chunks) and cache answers to repeated queries.
A retrieval eval set. A fixed set of question → expected-source pairs you can score on every change.

Common mistakes

Fixed-size chunking. The default that quietly caps your ceiling. Chunk on meaning.
Vector-only retrieval. You'll miss exact-match queries every time. Add keyword search.
No reranking. Stuffing the raw top-k into the prompt wastes context on near-misses.
Tuning the prompt to fix a retrieval problem. If the right chunk isn't retrieved, the prompt is irrelevant. Diagnose retrieval first.
No evaluation. "It looks better" isn't a metric. Without an eval set you're guessing, and you'll regress silently.

Best practices

Measure retrieval separately from generation. Most failures are retrieval failures; isolate them. Track recall on your eval set.
Chunk on structure, then iterate. Start with semantic boundaries and light overlap; adjust based on retrieval scores.
Default to hybrid + rerank. Treat it as the baseline, not an optimization.
Filter by metadata for scope and security. Especially in multi-tenant systems.
Force grounding and citations. Answer only from context; cite; allow "I don't know."
Re-embed on model change. Version vectors so you know when a reindex is required.

Conclusion

RAG isn't one trick — it's a pipeline, and quality is set by its weakest stage. Get chunking right, retrieve hybrid and rerank, ground the generation, and measure retrieval so you're improving the right thing. Do that and you cross the line from impressive demo to a system people can trust with real questions.

Skip the engineering — relying on naive chunking and bare vector search — and you'll ship something that demos well and fails the moment real users ask real questions.

Go deeper across LLM Engineering — RAG, Fine-Tuning & Production LLMs, revisit the RAG vs Fine-Tuning decision framework, or explore AI Coding Agents for the agentic side of LLM systems.

Explore more: LLM Engineering · AI Coding Agents · Claude Code

Originally published at umesh-malik.com

Keep reading on umesh-malik.com: