DEV Community: Joan Comadran

Vercel CI vs GitHub Actions for Next.js: which to use

Joan Comadran — Mon, 02 Nov 2026 10:49:50 +0000

Vercel CI is worth trying if your Next.js repo is private, already on Vercel, and your checks are slow because they rerun everything on every push. It reads your Turborepo task graph, runs only what a change affects, and bills per CPU minute. GitHub Actions is still the general-purpose tool: any trigger, any OS, deploys, schedules, and free on public repos. For most teams the answer for now is both, with GitHub Actions keeping the jobs Vercel CI can't do.

Everything below was checked against Vercel's and GitHub's own docs and pricing pages on 2 November 2026. Vercel CI is a beta from 28 October, so treat the numbers as a snapshot, not a contract.

What Vercel launched on 28 October 2026

Vercel announced Vercel CI in beta on 28 October 2026 (also in the changelog). The pitch is aimed squarely at people whose coding agents open more pull requests than humans can wait for: most CI reruns the whole workflow for a one-line change, and that gets expensive when agents push all day.

How it works, according to the Vercel CI docs:

You tag Turborepo tasks with "tags": ["ci"] in turbo.json.
On every git push, Turborepo works out which tagged tasks the change affects.
Tasks whose inputs haven't changed come back from Vercel Remote Cache, on by default.
The rest run in dependency order, each on its own isolated machine.
Vercel posts a check to the pull request, so branch protection can block merges as it does today.

{
  "tasks": {
    "lint": { "tags": ["ci"] },
    "typecheck": { "tags": ["ci"] },
    "build": { "tags": ["ci"], "outputs": [".next/**", "!.next/cache/**"] }
  }
}

That's the whole config. No workflow YAML. Vercel's claim is that push-to-green in its own repos got 2 to 6 times faster, and that the system has run nearly 8 million tasks across its repos and the private beta. Those are Vercel's numbers about Vercel's repos; I haven't reproduced them.

Vercel CI vs GitHub Actions: the comparison table

	Vercel CI (beta)	GitHub Actions
Status	Beta since 28 Oct 2026; "features and configuration may change"	Generally available
Config	`ci` tags in `turbo.json`	YAML in `.github/workflows/`
What runs	Only tagged Turborepo tasks the change affects, plus their dependencies	Whatever the workflow says, every time, unless you add filters
Triggers	`git push` only	Push, pull request, schedule, manual, issues, labels, releases and more
Operating systems	Linux only (Amazon Linux 2023 by default, Ubuntu image optional)	Linux, Windows, macOS
Repo support	GitHub only, private repos only	GitHub, public and private
Compute	2 CPUs / 4 GB per task by default, up to 32 CPUs	2-core Linux standard runner; larger runners on Team and Enterprise
Caching	Vercel Remote Cache, zero config	`actions/cache`, or Remote Cache with `TURBO_TOKEN` secrets
Free allowance	Hobby: 200 CPU minutes/month	Free: $12/month of compute on private repos; standard runners free on public repos
Paid rate	Pro: $0.0035 per CPU minute, billed per second	2-core Linux: $0.006 per minute, rounded up per job
Logs and reruns	Dashboard CI tab, `vercel ci` CLI, Vercel MCP, REST API	Actions tab, `gh` CLI, REST API

Sources: Vercel CI docs, Vercel's migration guide, Vercel CI pricing, Vercel pricing, GitHub Actions billing and runner pricing, all as of 2 November 2026.

Pricing, with the arithmetic

The units differ, which is where comparisons usually go wrong.

Vercel CI bills CPU minutes: CPUs requested multiplied by run time, rounded up to the second. Each run pays for bootstrapping (cloning and installing dependencies, 4 CPUs by default) plus each task that actually runs (2 CPUs by default). Cached and skipped tasks cost nothing.

GitHub Actions deducts a dollar amount from your plan's included compute. The standard 2-core Linux runner costs $0.006 a minute, and each job is rounded up to the whole minute. GitHub Free includes $12 a month, which is 2,000 minutes on that runner. Public repos on standard runners don't count at all.

A made-up but realistic Next.js run, to show the shape (the durations are mine, not measured):

Step	Vercel CI	GitHub Actions (one job)
Install deps, 1 min	4 CPUs × 1 = 4 CPU min	1 min
Lint, 1 min	2 × 1 = 2 CPU min	1 min
Type check, 1 min	2 × 1 = 2 CPU min	1 min
`next build`, 3 min	2 × 3 = 6 CPU min	3 min
Total, cold	14 CPU min ≈ $0.049 on Pro	6 min = $0.036

On a cold run Vercel CI is not cheaper. It wins when most tasks come from cache, for example a docs-only change where only lint is affected. Then the bill is bootstrap plus one small task, and the wall clock is shorter because tasks run in parallel on separate machines.

The free tiers are where the difference is stark. Vercel Hobby's 200 CPU minutes is about 14 cold runs of the example above. GitHub Free's $12 covers about 333 of them on a private repo. If you're a solo developer pushing all day, do that maths before you migrate.

The limits that decide it for most people

Straight from Vercel's docs, as of 2 November 2026:

Public repositories aren't supported. Open-source projects stay on GitHub Actions, where standard runners are free.
GitHub only. No GitLab or Bitbucket.
git push is the only trigger. No cron, no manual dispatch, no "run when someone adds a label".
Linux only. macOS and Windows test jobs stay where they are.
Turborepo 2.11.7+ and Vercel CLI 64.3.1+. Older Turborepo rejects the tags key.
Node.js 24 image. Vercel's guide says Vercel CI currently provides Node.js 24; if you pin Node 22 in your workflow, test that first.
One Vercel team per repo. A repo linked to projects on two teams won't enable.
It tests the pushed commit, not GitHub's merge commit. A pull_request workflow in Actions tests the merge result by default, so the two can disagree on a branch that's behind main.

One beta-shaped caveat: on Vercel's community forum a user reported cache misses across Git refs with identical task hashes (29 October). When I checked on 2 November the thread had no reply from Vercel, so I'd treat cross-branch cache reuse as "verify on your repo".

What GitHub Actions still does that Vercel CI doesn't

Vercel's own migration guide says to keep these in GitHub Actions:

Deploys and package publishing
Scheduled jobs
Workflows triggered by issues or labels
Anything that needs macOS or Windows
Commands that aren't Turborepo tasks (or turn them into package.json scripts and tasks first)

Add security scanning, release automation and anything that comments on PRs with a custom bot, and most real repos keep at least one workflow file. Vercel CI covers the checks, not the automation.

Running a Next.js product where CI time or agent pull requests are piling up and you want the checks, caching and merge gates set up properly?

What this site actually runs

For context, not as a benchmark: this site is a single Next.js 16 app deployed on Vercel. Its repo has no .github/workflows folder and no turbo.json, and the only checks on its commits are Vercel's deployment and a GitGuardian secret scan. The gate before merging is that the preview build passes and the preview renders. Vercel's own GitHub Actions guide is blunt that a Vercel build doesn't run your tests, so "the deploy went green" proves the site builds and nothing more.

So for a repo like this one, the honest choice isn't between Vercel CI and GitHub Actions. It's whether to add a lint and type-check step at all. If I add one, Vercel CI is a few lines (turbo as a dev dependency, a turbo.json, vercel ci enable), but the beta label, and the fact that nothing here runs tests yet, are why I'd not move anything important onto it yet.

Which one to pick

Private Turborepo monorepo on Vercel, slow PR checks, lots of agent PRs: try Vercel CI. Run it side by side with your workflow, as Vercel's guide suggests, then switch the required check.
Single Next.js app, few checks, Hobby plan: GitHub Actions. On private repos the free allowance is around 20 times larger for this kind of workload and the workflow file is one copy-paste.
Public or open-source repo: GitHub Actions. Vercel CI doesn't support it yet.
Scheduled jobs, releases, deploy gates, cross-OS tests: GitHub Actions, whatever you pick for checks.
Most teams in practice: both. Vercel CI for lint, types and tests; GitHub Actions for everything with a trigger that isn't a push.

If agents are what's filling your queue, the CI speed-up only helps if review keeps pace too: see how to review AI-generated code for the tiering I'd put in front of it, and Claude Code vs Codex if you're picking the agent that opens those PRs.

About the author

I'm Joan Comadran, an industrial engineer turned AI engineer and full-stack developer in Barcelona. I build and deploy Next.js products on Vercel, this site included. This comparison comes from Vercel's and GitHub's documentation and pricing pages checked on 2 November 2026 and from what this site's own repo runs, not from a long production history with a beta that's five days old. If you want CI, previews and merge gates set up on a real product, that's what I do.

FAQ

Is Vercel CI a replacement for GitHub Actions?

Only for part of it. Vercel CI runs Turborepo tasks tagged ci (lint, type checks, tests, builds) on every git push and posts a check to your pull request. It has no schedules, no issue or label triggers, no macOS or Windows runners and no deploy or publish steps, and Vercel's own migration guide says to keep those jobs in GitHub Actions. As of 2 November 2026 it is also in beta.

How much does Vercel CI cost?

As of 2 November 2026, Vercel's pricing page lists 200 CPU minutes a month included on Hobby and $0.0035 per CPU minute on Pro, with custom pricing on Enterprise. Each run bills the dependency install (4 CPUs by default) plus every task that actually runs (2 CPUs by default). Tasks restored from cache or skipped as unaffected use no CPU minutes.

Do I need Turborepo to use Vercel CI?

Yes. Vercel CI reads turbo.json to decide what to run, and needs Turborepo 2.11.7 or later plus Vercel CLI 64.3.1 or later. Vercel says it also works in single-package repos, so a plain Next.js app can add turbo and a turbo.json with lint, typecheck or build tasks tagged ci.

Does Vercel CI work with public GitHub repositories?

Not yet. As of 2 November 2026 the Vercel CI documentation lists public repositories as unsupported, along with any forge other than GitHub and any trigger other than git push. For open-source Next.js projects, GitHub Actions on standard runners remains free and is the practical choice.

Originally published on joancomadran.dev. I'm Joan, an AI engineer in Barcelona — work with me.

How to review AI-generated code: a risk-tier checklist

Joan Comadran — Fri, 30 Oct 2026 10:39:11 +0000

To review AI-generated code without drowning in it, stop treating every pull request the same. Sort each change by risk, let machines do the first read (tests, types, an AI reviewer, a security scan), and spend human attention only where a missed bug is expensive: auth, money, data, CI and releases. Then cap how many rounds an agent and a reviewer can bounce a PR between them, because left alone they won't stop.

That's the short version. The rest is the data behind it and a checklist you can copy into a small team's repo this afternoon.

Why code review is now the bottleneck

Two things landed in October 2026 that say the same thing from opposite ends.

The first is a Harvard paper by Fiona Chen and James Stratton, Artificial Intelligence in the Firm: Bottlenecks in Software Production, built on Jellyfish analytics data: 445 million work events from 720,542 workers at 655 firms. The version I read (dated 28 October 2026, accessed 30 October) finds that after a firm adopts AI coding agents:

Metric (after AI agent adoption)	Change
Lines of code added per worker	+44.0%
Pull requests opened	+35.7%
Jira issues resolved	+13.7% (borderline significant)
Time from pull request to merge	+56.1% (baseline 3.56 days)
Review comments per pull request	+38.6%

Their words: "Code review becomes the bottleneck." Code waits longer for a reviewer (+59.9% time in backlog) and spends longer in active review (+58.5%), which the authors read as both too little review capacity and lower quality code coming in. AI review tools don't fix it on their own: 79.1% of firms had used one by July 2026, but AI wrote only 23.3% of review comments.

If you saw Ars Technica's coverage on 9 October, its numbers (+30% lines of code, +23% pull requests, +49% review time) match an earlier version of the paper (first posted in January and revised since; the current one is dated 28 October). Same direction, different decimals. I've used the current version.

The second is the other end: a team that writes most of its code with agents and made review work anyway. On 15 October the Claude Code team published How the Claude Code team does code review (Addy Osmani, Morgan Westlee Lunt and Qing Wang). Claude writes about 90% of Claude Code's own code. From June to September, merged pull requests in that codebase more than doubled while the share that had to be reverted fell by more than 40%. They didn't do it by reading harder. They moved most of the reading to machines and made mistakes cheap to undo.

You are probably not Anthropic. But the parts that matter scale down to a team of two.

The idea: the change sets the risk tier, not the author

Anthropic's rule is that "the change sets the tier, not the author." A docs fix and an auto-updater change get different review, whoever (or whatever) wrote them. Their table:

Risk	Examples	Human approvals
Low	Docs, copy, internal-only features, additive changes behind a flag	None, once automated review and security checks are green
Medium	Ordinary product changes, plus sensitive areas like caching, the auto-updater, system prompts	One
High	The riskiest code, plus paths that always need two people	Two

They use a classifier to pick the tier. A small team doesn't need one: a CODEOWNERS file and a list of paths does 90% of the job.

A risk-tier checklist for small teams

Here is how I'd translate it for a team of one to five people shipping a typical web app (Next.js, Postgres, a payment provider, a few agents). Treat it as a starting point, then tighten or loosen it with evidence.

Tier 0: can auto-merge

Docs, README, blog content, copy changes.
Dependency patch bumps with a clean lockfile diff.
New code behind a feature flag that's off in production.
Tests that only add coverage (no edited assertions).

Gate: green CI (lint, types, tests, build), AI review with no open findings, a preview deploy that renders.

Tier 1: one human

Ordinary product features and bug fixes.
UI changes, new endpoints that reuse existing auth helpers.
Refactors inside one module.

Gate: everything in Tier 0, plus one human approval. On an agent-written PR, the person who prompted the agent can be that human, which is exactly Anthropic's rule: they count as a required reviewer, "the same as if they'd typed the code themselves".

Tier 2: the owner, and a second pair of eyes if you have one

Auth, sessions, permissions, row-level security policies.
Payments, billing, anything that moves money.
Database migrations and data deletion.
CI workflows, deploy config, secrets handling.
Agent instructions and system prompts that change what production agents do.

Gate: CODEOWNERS approval from whoever knows that area, plus a written rollback plan. If you're a team of one, this is the tier where you sleep on it and read the diff yourself the next morning. For Supabase apps, my pre-launch security checklist lists most of the paths that belong here.

What to read in every tier

The current top results for this keyword are long lists of AI failure modes. They're right, but you don't need 24 checks on a typo fix. These are the ones worth doing on every human-reviewed PR:

Scope. Does the diff match the task? Unrelated "cleanups" go in another PR.
Tests first. Read the test diff before the code. A deleted assertion, a new skip or a looser matcher is the agent making the test pass, not the code work.
Invented things. Every new import, function, config key and package must exist in the version you actually run.
Failure paths. What happens when the lookup returns nothing or the call times out? Look for fallbacks that let a request through.
Evidence. Ask for the command that ran and what it returned, or a screenshot. Anthropic asks its agents to "show the output instead of saying it's done".

Two rules that keep humans honest

An agent's approval never counts as a person's. Automated review can clear a Tier 0 change. It can't fill a slot that calls for a human.
Approvals belong to a commit. If an agent pushes after you approved, the approval is stale. On GitHub that's the "Dismiss stale pull request approvals when new commits are pushed" option in branch protection or rulesets. Turn it on.

Cap the loops between agents and reviewers

This one only shows up when both sides are machines. A human waves off a nitpick in two seconds; an agent fixes it, pushes, and triggers another review. Anthropic reports one CLI PR that went through more than fifty rounds of review and fixes overnight before its author stopped it. When they ran git blame on what the reviewer kept flagging, about 59% was code that had been there since the first pass: old bugs, found a few at a time.

Their fixes, which you can copy as-is:

Hard cap at three rounds. After that, the reviewer asks the author to step back and rethink the approach.
Diff-only re-review after the first passes.
Flag the class of bug, so the author fixes every instance, not one line.
No repeated findings.

If you run agents in CI, put the cap in the harness, not in a prompt. The same logic as budgets and turn limits in durable AI agents: a loop with no ceiling is a bill with no ceiling, and Claude Code cost per month is already hard enough to predict.

Write a REVIEW.md

CLAUDE.md (or AGENTS.md, see Claude Code vs Codex for using both) tells the agent what the project is. REVIEW.md tells the reviewer what matters. Anthropic's good ones are short and do five things: say what failure looks like in this repo, cap the nitpicks, list paths to skip, ask for a file and line as evidence, and ask for a summary that starts with a count and says plainly when there's nothing to fix.

A starting point:

# REVIEW.md

## What failure looks like here
- A user can read or change another user's data.
- A payment is charged twice or not recorded.
- A migration can't be rolled back.

## Rules
- Every finding needs a file and line. No guesses from names.
- Max 3 nits per review. Style is the linter's job.
- Skip: content/**, *.md, generated types, lockfiles.
- Start the summary with the number of real issues. If it's 0, say so.

When the reviewer keeps flagging the same thing, move it into REVIEW.md, a lint rule or a test. That's how the noise goes down instead of up.

Small-team setup on GitHub

Branch protection or a ruleset on main: required checks, required review, stale approvals dismissed.
CODEOWNERS for Tier 2 paths, including .github/workflows/.
A PR template with three headings: Testing, Risk, How to revert.
One AI reviewer on one repo first. Tune REVIEW.md for a few weeks, then widen. Code Review for Claude Code is generally available on Team and Enterprise plans, and /code-review and /security-review run locally.
Previews, feature flags and one-click rollback, so a bad merge costs minutes. On Vercel, preview deployments and instant rollback are built in.

One caution from InfoQ's write-up: the open-source Claude security review GitHub Action says in its README that it "is not hardened against prompt injection attacks and should only be used to review trusted PRs". Don't point it at PRs from strangers.

Shipping with coding agents and want review tiers, CI gates and rollback set up before the PR queue gets away from you?

What this doesn't solve

Anthropic is candid that it doesn't yet have circuit breakers that tighten approval when revert or incident numbers rise. Neither will you. Watch two numbers instead: how long PRs wait on a person, and how often you revert. If the first drops and the second climbs, you didn't save review time, you moved it to incident time.

And some PRs shouldn't land at all. Agents make starting things cheap, which also makes closing a PR cheap. "Should we build this?" is still a human question, and no reviewer, human or not, answers it by reading the diff. If you're designing the agents themselves, single agent vs multi-agent covers where the boundaries go.

I'm Joan Comadran, an AI engineer and full-stack developer in Barcelona (industrial engineering background). This guide is built from the Harvard paper and Anthropic's write-up, both checked on 30 October 2026, not from a review process I'm claiming to run at Anthropic's scale. If you want someone to set up the tiers, gates and rollback on a real product, that's what I do.

FAQ

How do you review AI-generated code?

Sort each pull request by risk before anyone reads it. Low-risk changes (docs, copy, additive code behind a flag) can merge on green CI plus an AI review. Ordinary product changes need one human. Auth, billing, data access, CI workflows and release code need a human who knows that area, ideally two. In every tier, read the tests before the code, check for invented APIs and dependencies, and confirm the change does what the task asked and nothing else.

Can AI review AI-generated code?

It can do most of the reading, but it should not approve. Anthropic's Claude Code team runs an AI review on every pull request and lets low-risk changes merge on automated checks, yet an agent's approval never counts as a person's, and the person who prompted the agent counts as a required reviewer. Use the AI reviewer to find issues and the human to own the decision.

What is a REVIEW.md file?

REVIEW.md is a short file, written by the people who own the code, that tells an AI reviewer what matters in that repository: what failure looks like, which paths to skip, how many nitpicks to allow, and that every finding needs a file and line as evidence. Anthropic's Code Review for Claude Code reads it; with other tools you can point the reviewer at it in its prompt.

Why is code review the bottleneck with AI coding agents?

Agents speed up writing, not reviewing. In Chen and Stratton's Harvard study of Jellyfish data (655 firms, version of 28 October 2026), adopting AI agents raised lines of code by 44% and pull requests opened by 35.7%, while time from pull request to merge rose 56.1% and review comments per pull request rose 38.6%. Issues resolved grew far less than code did.

Originally published on joancomadran.dev. I'm Joan, an AI engineer in Barcelona — work with me.

Single agent vs multi-agent: when subagents are worth it

Joan Comadran — Wed, 28 Oct 2026 23:07:15 +0000

Single agent vs multi-agent is a trade-off between one shared context and several isolated ones. For many production setups in late 2026, Anthropic's Applied AI team now recommends defaulting to one agent loop with skills and tools loaded on demand, and keeping a subagent only when evals show it still beats the folded version — or when it truly needs its own context window, parallel runs, or permission isolation. That is the practical answer; the rest of this post is how to decide for your stack.

On 22 October 2026 Anthropic published Building agents: When to fold subagents into your main agent loop, arguing that enterprise agents with routers, planners and a subagent per team often lose quality, voice and speed to handoffs and "Frankenprompt" system prompts. The same week they shipped the single-agent-loop-kit on GitHub (Apache 2.0; README: reference implementation, not maintained, not accepting contributions). THE DECODER summarised the piece on 25 October, including Anthropic's note that one customer saw roughly 2× faster runtime on a single-agent loop than on their multi-agent harness in an internal comparison.

None of that means subagents are dead. It means the bar moved: newer models (Anthropic cites Opus 4.5 onward, plus Opus 5.5 and Fable 5.1) can carry more planning inside one loop, so a lot of harness code and org-chart architecture may be doing work the model no longer needs.

What changed in the single agent vs multi-agent debate

Multi-agent designs looked rational for a long time. Each team ships a specialist subagent; a central orchestrator routes intent; evals live next to each specialist. Conway's law, but for tokens.

Anthropic's write-up lists what that buys you in pain:

Context loss at every handoff between agents.
Subagent sprawl — hundreds of overlapping agents with no shared owner.
Conflicting system prompts when every team adds a sentence.
Local evals that optimise subtasks but dilute end-to-end quality.
Latency from nested model loops; the ~2× runtime figure above is one datapoint from their customer comparison, not a guarantee for your workload.

Their counter-pattern is a single agent loop: one model, one context window, batched tool calls per turn, turn and cost budgets in the harness, and the model revising its own plan as tool results arrive — instead of a planner agent handing a lossy summary to a worker agent.

Progressive disclosure is the mechanism: short descriptions of skills and tools in context, full content only when the model selects them. Anthropic says that pattern let them cut Claude Code's system prompt for newer models by over 80%, partly by moving procedure into skills and actions into tools.

A single agent with skills and MCP tools

Skills and tools answer different questions. Anthropic's article is explicit:

Skills — how a team does work: steps, rules, tone, edge cases. That is what used to sit in a subagent's long system prompt.
Tools — what the agent can do: fetch live data, write with guardrails, call an API, or temporarily wrap a subagent you have not folded yet.

MCP fits on the tool side when the same integrations must work across hosts (Claude, ChatGPT, Cursor, your product). The model still chooses tools through ordinary function calling; MCP standardises discovery and execution. I wrote the layer cake in MCP vs function calling; the short version is that MCP does not replace tool use — it packages tools for reuse.

Anthropic also warns that tool choice degrades beyond roughly 30–50 tool definitions in the prompt at once. Mitigate with tool search, grouping tools by user intent, and preconditions inside the tool so the model gets a readable refusal.

One open-ended loop, procedure in skills, side effects in tools, and a small central team on the system prompt plus shared end-to-end eval — domain teams ship skills and tools with their own small evals, vetted before merge. Without that ownership, you get skill sprawl instead of subagent sprawl.

When a subagent still earns its place

Anthropic keeps subagents on the table when:

Context bloat is measurable — the single loop's quality drops as history and tool output accumulate, and trimming or summarising is not enough.
True parallelism — several heavy tasks need fresh context windows at the same time, then discard them.
Tool or instruction conflict — one prompt cannot reliably pick among overlapping tools, or teams have written incompatible rules.

They also use subagents for verification, parallel research paths, and modular permissioning in their own multi-agent research system. The guidance is not "never subagent"; it is "stop giving every team a subagent by default."

Even when you keep one, the article prefers calling it as a tool from the main loop so the primary agent keeps the user thread. Full handoff is for when the specialist must talk to the user directly.

Single agent vs multi-agent at a glance

	Single agent loop	Multi-agent (orchestrator + subagents)
Context	One window; shared history across steps	Separate windows; summaries passed between agents
Instructions	One system prompt + skills loaded on demand	Many prompts; risk of contradiction
Latency	One nested loop; parallel tools per turn	Often nested loops per subagent call
Parallelism	Parallel tool calls; sequential reasoning	Natural fit for parallel agents
Ownership	Central team on prompt + E2E eval	Easy to mirror teams; hard to maintain voice
Migration	Fold specialists into skills/tools incrementally	Already sunk cost in many prompts and evals
Best when	Most customer-facing and ops agents	Deep research, parallel paths, strict isolation

Decision checklist: fold or keep?

Use this before you add another subagent — or when Anthropic's migration story lands on your roadmap:

Does this work need its own context window? Deep research, long independent branches, or contexts you must discard after one task → subagent candidate. Everything else → try a skill first.
Is the work truly parallel? If tasks must run at the same time with separate token budgets, subagents (or separate loop invocations) still make sense. If work is sequential but owned by different teams, that is not automatically parallel.
Isolation or compliance handoff? Separate credentials, audit boundaries, or a verifier that must not see draft content → consider a dedicated loop or tool-gated subagent.
Otherwise, fold it. Turn the subagent prompt into a skill, wire APIs as tools (MCP where reuse matters), run the shared eval, and keep the subagent only if scores drop.

Anthropic's support-desk example in the kit is instructive in the negative direction: folding one subagent lowered latency but broke a process that had been passing — the main agent answered shipping questions without calling the specialist. Their fix is boring and essential: eval tasks for every production chain and every rule that must not break, run more than once per task.

How to migrate one subagent at a time

You do not rewrite the fleet in a weekend. Anthropic's staged path:

Task-completion evals — shared end-to-end set plus per-skill sets; ten golden tasks beats zero.
Combine subagents that always run back-to-back on the same data.
Subagents as tools — baseline on the eval before rewriting.
Fold — prompt → skill, APIs → tools; compare scores; keep the subagent if the folded version loses.

The single-agent-loop-kit chains eval build, prompt audit, hillclimb and cost-optimize skills. README: reference implementation, not maintained.

Folding does not replace caps, idempotency or replay rules — see durable AI agents. For coding harnesses, Claude Code vs Codex is the parallel "one loop vs delegated queue" question.

Designing an agent architecture and want the eval set, tool boundaries and cost caps settled before you ship?

Costs and latency

Multi-agent setups pay nested model rounds and lossy handoffs — extra latency and input tokens even when the final answer looks fine. A single loop still needs good skill and tool descriptions and tool search; it is not automatic savings.

For build budgets see AI agent development cost; for token spend inside one loop, keeping Claude's token bill under control.

FAQ

What is the difference between a single agent and a multi-agent system?

A single agent is one model in one context window running an open-ended tool loop: it loads skills and tools on demand and keeps intermediate results in the same thread. A multi-agent system adds subagents — separate loops with their own prompts, tools and context — usually coordinated by a router or orchestrator. Multi-agent setups can parallelise work and isolate permissions; they also add handoffs, latency and duplicated instructions unless each subagent earns its place.

When should I use subagents?

Anthropic's guidance (October 2026) keeps subagents when a single loop shows measurable degradation from context bloat, when several tasks must run in parallel with fresh context windows, or when one agent cannot reliably choose tools or follow conflicting instructions in one prompt. If none of those apply, prefer folding specialist prompts into skills and their API calls into tools in the main loop, then compare on the same eval.

Are agent skills the same as MCP tools?

No. Skills hold procedural knowledge — steps, rules and judgment calls that used to live in a subagent's system prompt — and load when the model needs them. MCP tools (or plain function tools) are how the agent acts: read live data, call APIs, enforce permissions, or invoke a subagent you have not folded yet. Anthropic recommends skills for how a team works and tools grouped by user intent for what the agent can do.

How do I migrate from multi-agent to single agent without breaking production?

Build or reuse a shared end-to-end eval, then change one subagent at a time: turn its prompt into a skill and its integrations into tools, run the eval before and after, and keep the subagent only if the folded version scores worse. Anthropic's single-agent-loop-kit chains Claude API skills for evals, prompt audit and hillclimbing; it is Apache 2.0 and labelled a reference implementation that is not maintained.

I'm Joan Comadran, an AI engineer and full-stack developer in Barcelona (industrial engineering background). I write guides like this from vendor docs and shipped agent work — not from a fictional subagent migration on this site. If you want someone to draw the single-loop vs subagent line on a real product, that's what I do.

Originally published on joancomadran.dev. I'm Joan, an AI engineer in Barcelona — work with me.

Claude Code vs Codex: pick by task, then set up both

Joan Comadran — Fri, 23 Oct 2026 18:47:58 +0000

On October 19, Theo Browne posted that over the previous two weeks, more than 60% of T3 Code users who used Codex also used Claude Code. By October 23 the post had 2,511 likes and about 118,000 views. T3 Code is his open-source control surface for coding agents (MIT, roughly 29,600 GitHub stars as of today). You bring your own Claude Code, Codex, Cursor, Grok Build, OpenCode or Antigravity login and drive them from one desktop, web or mobile app.

One caveat before anyone puts that number in a slide. People who install a tool built for switching agents are, unsurprisingly, people who switch agents. The 60% says very little about developers in general.

What it does show is that "Claude Code vs Codex" is turning into the wrong question for a lot of people. The better question is which jobs go to which agent, what that costs, and how to stop maintaining two sets of instructions. That's what this post covers.

What actually differs

Both are coding agents. You describe a task, and the agent reads the repo, edits files, runs commands and shows you the diff. Both have a CLI, an IDE extension, a desktop app and MCP support. Each vendor keeps shipping the other's features, so any feature table goes stale fast.

The difference that lasts is the default working style:

Claude Code is built around steering. It works in your terminal and your repo, shows its plan, asks before risky actions, and expects you to interrupt. You shape it with CLAUDE.md, skills, subagents and hooks. A PreToolUse hook is the way to block something, because Anthropic's own memory docs say CLAUDE.md is context, not enforced configuration.
Codex is built around delegation. It runs locally too, but its strength is handing off a task: cloud tasks in a sandbox, @codex on a GitHub issue or PR, codex exec in scripts, and several tasks at once. You shape it with AGENTS.md and its sandbox and approval settings.

Roughly, Claude Code feels like pairing and Codex feels like assigning a ticket. Both can do either; that's just what each one is designed for.

The benchmark numbers

Artificial Analysis runs both harnesses on the same three benchmarks. Their figures, checked October 23, 2026:

	Claude Code (Opus 5.5, max)	Codex (GPT-6 Astra, max)	Codex (GPT-6.1 Sol, max)
Coding Agent Index	62	55	54
API cost per task	$11.42	$7.04	$1.50
Time per task	1.0 h	24.8 min	23.7 min
Tokens per task	14.5M	3.2M	3.9M

Two things stand out. Claude Code scores higher and spends a lot more to get there: more turns, more tokens, more wall time. And Codex on GPT-6.1 Sol gets within a point of Astra at about a fifth of the cost, which says more about model choice than about harnesses.

Note what "cost per task" means here: pay-per-token API cost, not what you pay on a subscription. On a flat plan, those tokens turn into how fast you hit your limit.

What they cost (October 23, 2026)

Neither one is sold on its own. You get it through a plan.

Claude Code (pricing):

Pro: $20/month, or $17/month billed annually
Max: from $100/month, at 5x or 20x Pro's usage per five-hour session
Team and Enterprise seats, plus pay-per-token through a Console account

Limits reset on a rolling five-hour window, paid plans add weekly limits on top, and Claude Code shares one pool with your Claude chats. One gotcha from Anthropic's help center: if ANTHROPIC_API_KEY is set in your shell, Claude Code bills that key instead of your subscription. That's one more reason to keep keys out of global env, which I covered in securing your API keys.

Codex (pricing):

Free and Go ($8): GPT-6 Luna in the desktop app, subject to rollout
Plus: $20/month
Pro: $100, $200 or $500/month. Only Pro 500 gets Ultrafast mode
Business: $20/user/month billed annually, $25 monthly
API key: pay per token, but no cloud features (no GitHub reviews, no Slack)

On Plus, OpenAI estimates 15–160 local messages per five hours on GPT-6.1 Sol and 5–45 on GPT-6 Astra. Fast mode burns that allowance 2.5x faster. Pro plans currently have no five-hour limit, though weekly limits apply. Type /status in the CLI to see what's left.

Something to know this week if you're on Pro 200: according to OpenAI's Pro tiers article, subscribers who were on Pro 200 between September 22 and 29 keep the old, larger allowance only through October 29, 2026. After that they move to the new, smaller one, still at $200. If Codex has been your workhorse at that tier, expect to hit limits sooner from next Friday.

For budgeting either one at team scale, the logic in Claude Code cost per month applies to Codex too: measure cost per finished task, not cost per seat.

Which job goes to which

Choose by how well you can define the task and how closely you need to watch it.

Claude Code for:

Exploring a codebase you didn't write, when you don't know yet what the change should be.
Multi-file refactors and migrations that need decisions along the way.
Anything where you want to stop the agent the moment it goes the wrong way.

Codex for:

Small, clear, testable tasks: a bug with a repro, a dependency bump, a missing test.
A queue of those, where reviewing five diffs beats typing through five sessions.
Work where a failing test already defines done, so you don't have to watch it.

Neither, unsupervised, for auth, payments, secrets and data migrations you can't verify yourself. That isn't a limitation of either tool, it's a limitation of reviewing code you didn't read.

If you'd rather have one vendor and one bill, that works fine. The split above is a default, not a law. For the model side of the same decision, see Claude vs GPT for AI agents.

Setting up coding agents across a team and want the instructions, limits and review rules right from the start?

One repo, two agents: the AGENTS.md setup

This is where most two-agent setups quietly break.

Codex reads AGENTS.md. It starts with a global file in ~/.codex, then walks from the repo root down to your working directory, taking at most one file per directory. In each one, AGENTS.override.md wins over AGENTS.md. It stops at 32 KiB combined by default (project_doc_max_bytes).

Claude Code reads CLAUDE.md. Since v2.1.277 it can also read AGENTS.md, but by default only when there's no CLAUDE.md in your working directory or above it. If both exist, it reads CLAUDE.md only, unless CLAUDE.md imports the other file. It never reads AGENTS.override.md.

Next.js 16.2+ already sets this up: create-next-app writes an AGENTS.md with a managed block pointing agents to the docs bundled in node_modules/next/dist/docs/, plus a CLAUDE.md containing @AGENTS.md.

Here's the trap, and this site's repo has it. Its CLAUDE.md starts with @AGENTS.md, exactly as scaffolded, followed by 173 lines of real project rules: stack, design tokens, blog frontmatter, image rules, SEO setup. Its AGENTS.md is the 5-line Next.js block. Claude Code sees everything. Codex, opening the same repo, would see five lines telling it to read the Next.js docs, and nothing about the project. My other Next.js repos follow the same pattern.

The fix is to flip which file holds the content:

<!-- AGENTS.md: the shared rules, read by both agents -->
<!-- BEGIN:nextjs-agent-rules -->
...managed by Next.js, leave it alone...
<!-- END:nextjs-agent-rules -->

## Stack
## Commands
npm run build   # also runs the TS check
## Conventions

<!-- CLAUDE.md: import, then only Claude-specific extras -->
@AGENTS.md

## Claude Code
Use plan mode for changes under src/app/(site)/blog/.

Then check that each agent actually loaded it. In Claude Code, /memory or /context lists the loaded files. In Codex, run codex --ask-for-approval never "Summarize the current instructions." from the repo root.

Two more habits help:

Keep the shared file short. Anthropic says long instruction files get followed less and suggests under 200 lines. OpenAI lists a smaller AGENTS.md as a way to make Codex limits last longer, and truncates at 32 KiB anyway. Put procedures in skills and folder-specific rules in nested files.
Put the done condition in the file. "Run npm run build before you say you're finished" works for both agents, and it matters most for the one you aren't watching.

If you also share tools between them, the same idea applies to MCP servers: one server, two clients. That's covered in MCP vs function calling. Every MCP server adds context to each message, though, so connect only the ones the task needs. And if you start running agents for hours unattended, what happens when an agent dies mid-task becomes your problem too.

FAQ

Is Claude Code better than Codex?

On Artificial Analysis's Coding Agent Index (checked October 23, 2026), Claude Code with Opus 5.5 scores 62 and Codex with GPT-6 Astra scores 55. Codex finished tasks in about 25 minutes versus an hour, with fewer tokens and lower API cost per task. So Claude Code scores higher on hard tasks and Codex is faster and cheaper. Which matters more depends on the job.

How much do Claude Code and Codex cost?

As of October 23, 2026, both start at $20 a month. Claude Code comes with Claude Pro ($20, or $17 billed annually) and Max (from $100, at 5x or 20x Pro's usage). Codex comes with ChatGPT Plus ($20) and Pro ($100, $200 or $500). Both can also run on an API key and bill per token.

Can Claude Code and Codex share the same instructions file?

Yes. Codex reads AGENTS.md. Claude Code reads AGENTS.md only when there's no CLAUDE.md, so if you have both files, put the shared rules in AGENTS.md and start CLAUDE.md with the line @AGENTS.md. Claude Code then imports it, and Codex reads the same rules.

Should I pay for both Claude Code and Codex?

Only if you keep hitting one plan's limits, or you have two kinds of work: interactive changes you want to steer, and a queue of small, testable tasks you'd rather delegate. Two $20 plans cost the same as one plan doubled, and each one has its own five-hour and weekly limits.

The agent you pick matters less than whether it knows your repo's rules and whether you check its work. If you want help building that around AI coding agents, or the software they're writing, here's how I work.

Originally published on joancomadran.dev. I'm Joan, an AI engineer in Barcelona — work with me.

Durable AI agents: what happens when your agent dies mid-task

Joan Comadran — Wed, 21 Oct 2026 09:45:17 +0000

On October 19, Vercel published Making every harness durable and open-sourced durable-harness, a package that keeps coding-agent harnesses (Pi, OpenCode, fx, Claude Code and Codex) running through crashes, function timeouts and redeploys. The fine print first, because it matters: the README calls it experimental, it's on 0.0.x (0.0.1-beta.6 on npm as of October 21, 2026), and the API may change between releases. The Claude Code and Codex adapters are labelled experimental on top of that.

So don't rebuild your stack on it this week. But the problem it solves is old and boring and will outlive the package: an agent is a loop that keeps its progress in memory, and memory dies with the process. Durable AI agents are the fix for that, and you can apply the idea with or without Vercel.

What a durable AI agent actually is

A durable agent records what it has done somewhere other than the process doing it. Vercel's durable agents guide puts the distinction well: conversation history preserves model context, execution records establish which operations completed.

That second part is the one people skip. A saved transcript lets the agent remember what was said. It doesn't tell you whether the refund went through or the email left before the function got killed. An agent restarting with only its transcript can redo everything (paying for the tokens again, sending the email again) or guess. Both are bad.

How agents actually die

Nothing exotic. A function hits its maxDuration, the instance runs out of memory, you deploy mid-turn, or the browser tab closes and takes the stream with it. The longer the turn, the sooner it meets one of these.

I hit the cheap version of this with Claient, my WhatsApp bot. Its webhook runs on a serverless function with maxDuration = 60, and one incoming message can trigger several Claude calls. When the function got killed after sending the reply but before marking the message as handled, Meta retried the webhook and the lead got the same answer twice. I wrote up the fix, a time budget plus idempotency per message, in the WhatsApp bot post. That's a 60-second turn. Coding agents run for minutes or hours and wait on CI, so they get the same bug with more zeros.

The pattern: intent, outcome, queue

Here's how durable-harness does it, per Vercel's harness docs as of October 21, 2026. It's the same shape Inngest, Restate and Temporal use for their durable agents, so it's worth understanding once.

Before each model call or tool call, write an intent to a durable log.
After the call finishes, write the outcome.
Back the whole turn with a queue message. If the function dies, the queue hands the turn to a new function, which reads the log and continues.

After a crash, the log tells you three things: what finished, what was running, and what never started. Finished calls are read back from the log and never run again, which is why you aren't billed twice for a model call that already completed. A model call that was running just runs again. Between calls, nothing repeats.

The interesting case is the tool that was running. The docs are honest about an edge you should design for: a call that finished just before the crash may not be in the log yet, and then it counts as running. In other words, "running" means "maybe done". That's the whole reason replay rules exist.

The replay rule is the actual decision

In durable-harness, every tool you give the agent declares what happens if a crash interrupts it. 'safe' means it can run again. 'never' means it won't run twice: the model gets told the call may or may not have happened, and it decides whether to check first. Here's what that looks like for an agent that publishes blog posts, where a duplicate is embarrassing rather than expensive:

import { pi } from 'durable-harness/pi';
import type { HostTool } from 'durable-harness';
import { findPostBySlug, publishPost } from './cms'; // your own code

const tools: HostTool[] = [
  {
    name: 'find_post',
    description: 'Checks whether a post with this slug already exists',
    replay: 'safe', // a read: running it twice costs nothing
    inputSchema: { type: 'object', properties: { slug: { type: 'string' } }, required: ['slug'] },
    execute: async ({ slug }) => JSON.stringify(await findPostBySlug(slug)),
  },
  {
    name: 'publish_post',
    description: 'Publishes a post. Call find_post first if unsure.',
    replay: 'never', // a write: never rerun automatically
    inputSchema: { type: 'object', properties: { slug: { type: 'string' } }, required: ['slug'] },
    execute: async ({ slug }) => JSON.stringify(await publishPost(slug)),
  },
];

export const agent = pi({ model: 'anthropic/claude-sonnet-5.5', tools });

Notice the pair. A 'never' tool without a 'safe' way to check its effect leaves the model with "possibly ran" and nothing to do about it, so it either retries blindly or gives up. Give every write a matching read.

Then admit that 'never' isn't exactly-once. It means the harness won't rerun the call on its own. It can't un-send something that left the building half a second before the crash. Vercel's guide answers its own FAQ "Does durable execution prevent duplicate tool actions?" with "No", and recommends an idempotency key the receiving service enforces. Its Workflow SDK example uses the step ID, which stays stable across retries of the same step:

import { getStepMetadata } from 'workflow';

export async function sendInvoice(invoiceId: string) {
  'use step';
  const { stepId } = getStepMetadata();

  const res = await fetch(BILLING_API, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'Idempotency-Key': `invoice:${stepId}` },
    body: JSON.stringify({ invoiceId }),
  });
  if (!res.ok) throw new Error(`Billing failed: ${res.status}`);
  return res.json();
}

Step IDs differ between runs, so to dedupe across separate runs you need a business identifier or a unique constraint in your database. Claient does the latter: each WhatsApp message ID is claimed atomically in Postgres before processing, with a cap of three attempts so a message that always fails gets abandoned instead of retried forever. It's also one more argument for what I wrote in MCP vs function calling: tools that write to your own systems are easier to make replay-safe when they live in your own code.

Where durable-harness runs each harness

Harness	Runs in
Pi, OpenCode, fx	Your function, with files in a virtual workspace or a Vercel Sandbox
Claude Code, Codex (experimental)	Only a Vercel Sandbox
eve	Its own app, durable by default

The log lives behind a World, the storage-and-queue interface of the open-source Workflow SDK: Vercel's on Vercel, files on disk locally, or Postgres if you self-host, which per the blog post takes two environment variables. Claude Code and Codex are kept out of shared functions because they expect a real shell and filesystem and aren't safe for multi-tenant use. The virtual workspace is a bash-compatible shell with no network and no real binaries, and the docs say it holds about 500 files, so it's for small tasks, not your monorepo.

One documented limitation worth reading before you trust it with builds: with Pi and OpenCode, a turn starts in the chat route's own request, which drives it for up to 60 seconds before the queue route takes over, and a command still running at that handover is stopped, not rerun. A long npm install early in a turn can get cut off. The workaround in the docs is drive: 'queue' on agent.chatRoute(), and Vercel says a fix is on the way.

If you're writing your own agent loop rather than wrapping a coding harness, the same ideas come as 'use workflow' and 'use step' in the Workflow SDK, with WorkflowAgent from @ai-sdk/workflow for the AI SDK loop. Or Inngest, Restate or Temporal if you're not on Vercel. The rule that carries over everywhere: one step boundary per model call and per tool call. Wrapping the whole loop in a single step records nothing until the loop ends, which is durability in name only.

Building an agent that writes to real systems and need the retries, idempotency and caps right before it ships?

When you don't need any of this

Plenty of agents are request-response: a message comes in, a few model calls and tools run, an answer goes out, all in seconds. For those, a queue plus a step log is infrastructure you'll maintain for a failure you could handle with a retry. Claient's webhook doesn't use a workflow engine. Its 60-second webhook gets a time budget, an iteration cap on the tool loop and message-level idempotency, and the project notes list a queue as the next step only if load grows.

You need durability when a turn can outlive its process: tasks measured in minutes or hours, waits on CI or on a human approval, or crashes that would burn real money in repeated tokens. Idempotent side effects you need either way. That part isn't optional at any size.

Checklist before an agent gets write access

List every tool and mark it safe or never. Reads are safe; anything that sends, charges, publishes or appends is never.
Give every never-tool a safe tool that checks whether its effect already happened.
Push dedup to the receiver: an idempotency key, or a unique constraint on a business ID.
One step boundary per model call and tool call.
Cap iterations and spend, because a resumed agent can still loop. I covered caps in Claude Code cost per month and keeping Claude's token bill under control.
Kill it on purpose. Vercel's guide suggests interrupting a run between steps and retrying an external action to confirm nothing duplicates. If you've never seen your agent recover, you don't know that it does.
Plan for deploys. On Vercel, existing runs stay pinned to the deployment that started them, so your database schema has to stay compatible with code that may resume later.

FAQ

What is a durable AI agent?

An agent whose progress is recorded outside the process running it. Each model call and tool call goes to a log, so after a crash, timeout or redeploy another process reuses the finished results and continues from the first unfinished call. Chat history alone isn't durability: it records what was said, not what actually ran.

Does durable execution prevent duplicate tool calls?

Not on its own. It stops completed steps from running again, but a call in flight when the process died may already have reached the outside world. For emails, payments or publishing you still need an idempotency key or a unique constraint on the receiving side, and a way for the agent to check.

What is Vercel durable-harness?

An experimental open-source package from Vercel (Apache 2.0, 0.0.1-beta.6 on npm as of October 21, 2026) that makes Pi, OpenCode, fx, Claude Code and Codex durable. It logs every call to a Workflow SDK World (Vercel, local files or Postgres), backs each turn with a queue message, and lets each tool be marked safe or never to replay.

Do I need durable execution for my AI agent?

Only if a turn can outlive its process: tasks that take minutes or hours, waits for CI or a human, or crashes that would cost real money in repeated tokens. A request-response agent that finishes in seconds usually needs a time budget, an iteration cap and idempotent side effects, not a workflow engine.

Durable execution is one of those things that sounds like a framework feature and is really a discipline: write down what you did before you claim you did it, and never trust "probably ran". It's also why every write-action shows up in what an AI agent costs to build. If you want an agent built that way from day one, here's how I work.

Originally published on joancomadran.dev. I'm Joan, an AI engineer in Barcelona — work with me.

MCP vs function calling: which one your AI agent actually needs (2026)

Joan Comadran — Wed, 21 Oct 2026 08:27:59 +0000

The verdict first: MCP vs function calling is the wrong fight, because MCP runs on top of function calling. Function calling is how a model asks for a tool. MCP is how tools get packaged so that many apps can find and run them. If you're building one agent whose tools are your own product's logic, plain function calling is the right default in October 2026: fewer moving parts, and your code keeps control of identity, tenancy and side effects. Add an MCP server when the same tools need to live in several hosts, when a vendor already ships an MCP server for the system you need, or when another team owns the tools.

The disclosure comparison posts usually skip: every agent I ship to production uses plain tool use through @anthropic-ai/sdk, with the tool definitions sitting in my own code. I use MCP every day, but as a consumer: coding agents and my personal assistants reach Supabase, Gmail, Google Calendar and Notion through MCP servers. I have not shipped an MCP server to production. So the function-calling column below comes from code I can show you, and the MCP column comes from the spec, the vendor docs, and the receiving end.

MCP vs function calling at a glance (as of October 2026)

	Function calling (tool use)	MCP (Model Context Protocol)
What it is	A feature of the model API	An open client-server protocol (JSON-RPC 2.0)
Where tool definitions live	In your app's code, sent with every request	Published by a server, fetched by the client with `tools/list`
Who runs the tool	Your code, in your process	The MCP server: a local subprocess (stdio) or a remote service (Streamable HTTP)
Format	Provider-specific: Claude `tool_use` / `tool_result` blocks, OpenAI `function_call` / `function_call_output` items	One format for every MCP-capable host
Identity and auth	Whatever your app already knows (session, tenant, API keys)	The server's own: env vars for local servers, OAuth 2.1 for remote ones
Beyond tools	Tools only	Tools, resources and prompts, plus opt-in extensions
Reuse across apps	Copy the code	Point another host at the same server
Extra infrastructure	None	A server to run, or a hosted one to trust
Token cost	The tools you define	Every tool the server exposes, unless you filter them
Best fit	Tools that are part of one product	Tools that many hosts or agents share

The short version of the table: function calling is a call inside your app; MCP is an integration boundary. Boundaries are useful when there's actually something on the other side.

They're layers, not alternatives

Here's a tool from Claient's booking flow, defined for Claude's API. Field names are in Spanish because the product is:

{
  name: "consultar_disponibilidad",
  description: "Returns the free slots for a given date (YYYY-MM-DD)...",
  input_schema: {
    type: "object",
    properties: { fecha: { type: "string", description: "Day to check, YYYY-MM-DD." } },
    required: ["fecha"],
  },
}

The same tool published by an MCP server shows up in tools/list looking almost the same:

{
  "name": "consultar_disponibilidad",
  "description": "Returns the free slots for a given date (YYYY-MM-DD)...",
  "inputSchema": {
    "type": "object",
    "properties": { "fecha": { "type": "string" } },
    "required": ["fecha"]
  }
}

That's no accident. An MCP host (Claude Code, Cursor, ChatGPT, your own client) takes those definitions, passes them to the model as ordinary tools, and when the model returns a tool call, forwards it to the server as tools/call. The model never "speaks MCP". So the real question isn't which one to use. It's where should this tool's definition and execution live: inside my app, or behind a protocol boundary that other apps can also cross?

What changed in MCP this year

If the last time you read about MCP was 2025, the protocol has moved. The current spec revision is 2026-07-28, and the changes matter for anyone deploying a server:

It's stateless now. The initialize handshake and the Mcp-Session-Id header are gone. Every request carries its protocol version and client capabilities in _meta, and servers must implement server/discover to advertise what they support. That makes remote MCP servers much friendlier to serverless hosting and load balancers.
Roots, Sampling and Logging are deprecated (eligible for removal from the first revision on or after 2027-07-28). The suggested migration for Sampling is literally "integrate directly with LLM provider APIs".
Tasks moved to an official extension, alongside others like MCP Apps for interactive UI.
Servers should return tools/list in a deterministic order so clients get better prompt-cache hit rates, and list results now carry ttlMs and cacheScope hints.
The old HTTP+SSE transport is deprecated in favour of Streamable HTTP.

The prompt-cache point is a nice tell. Tool definitions sit at the front of every request, so if a server reshuffles them, everything after them misses the cache. If you've read how I keep Claude's token bill under control, you'll know why that's worth a line in the spec.

Using MCP straight from the model APIs

You don't need to write an MCP client to use a remote MCP server any more. Both big providers will act as the client for you, with caveats worth reading before you ship.

Anthropic's MCP connector (beta header mcp-client-2025-11-20 as of October 2026) takes an mcp_servers array in the Messages API and an mcp_toolset entry in tools. You can allowlist or denylist tools per server and set defer_loading so definitions are only loaded through the tool search tool. The limits: tool calls only (no resources or prompts), the server must be reachable over public HTTP (no local stdio servers), and the feature is not eligible for zero data retention. A newer beta, mcp-client-2026-09-15, lets you pin a server's tool list so the API doesn't fetch it on every request.

OpenAI's MCP tool in the Responses API is a tools entry with type: "mcp", a server_url, an optional allowed_tools filter and require_approval. By default OpenAI asks for your approval before sharing data with a remote MCP server. There's no per-call fee; you pay for the tokens of the imported tool definitions and the calls. For private servers there's Secure MCP Tunnel.

Both docs say the same thing in different words: an MCP server with dozens of tools gets expensive and slow if you expose all of them, so filter. And both are explicit that you should only connect servers you trust.

Why my production agent uses plain function calling

Claient answers and qualifies WhatsApp leads for small businesses, many of them on one deployment (the build story). It has three booking tools (check availability, book, reschedule) and one forced extraction tool. None of that is MCP, for reasons that have nothing to do with fashion.

Tenant scoping happens outside the model. The model never sees or chooses which business it's booking for. The webhook resolves the tenant from the WhatsApp number that received the message, and the executor gets that context from my code:

// The model only sends { fecha } or { inicio_iso }.
// Who the booking is for comes from the webhook, never from the model.
export interface ToolContext {
  accountId: string;
  leadId: string;
}

ejecutarTool: (name, input) =>
  ejecutarTool(name, input, { accountId: tenant.accountId, leadId: lead.id }, efectos),

That's the most important line in the agent. If the account id were a tool argument, a cleverly worded message could try to steer it. With MCP you can get the same guarantee, but the server now needs a per-tenant identity, which means OAuth or minted tokens, which means another service to secure. For tools that only exist inside one product, that's cost without benefit.

Side effects flow back into the app. When the model books a slot, the executor records it in efectos, and after the turn the webhook marks the lead as booked and sends a calendar invite. Keeping that in one process is a function call. Across an MCP boundary it's a result you have to parse and trust.

The time budget is mine. The tool loop runs inside a serverless function with a hard cap of five iterations and a deadline, because a function killed mid-turn means Meta retries the webhook and the lead gets a duplicate message. Every network hop to a tool server eats that budget.

Three tools don't need discovery. Discovery solves "which tools exist?". In Claient I wrote all of them, they ship with the code, and they're versioned with git.

None of this is a knock on MCP. It's what happens when the tool and the agent are the same product.

Where MCP earns its place

The other side is just as concrete. The assistants I use every day are connected to Gmail, Google Calendar, Notion and Supabase through MCP servers. Nobody at those companies wrote a tool for my assistant, and I didn't write one for theirs. That's the problem MCP solves, and it solves it well: one server, many hosts.

It also showed me the failure mode. In one personal project, the Supabase MCP server my coding agent had was authenticated against a different organisation than the one that owned the project, so every call came back permission denied. The fix wasn't clever: a note in the repo's CLAUDE.md telling the agent not to use those MCP tools there, and a small script that goes through Supabase's Management API with an access token for the right account. The lesson generalises: an MCP server brings its own identity. Whatever it authenticated as is what your agent can touch, which is fine in a dev tool with a human watching and something to design deliberately in a product.

Treat MCP servers the way the spec tells hosts to: tools are arbitrary code execution, and tool descriptions from a server you don't trust are untrusted input. Approvals, allowlists and scoped credentials aren't optional extras. For the credential side, the same rules as securing your API keys apply.

When to use which

Use plain function calling when:

The tools are part of your product and only your agent calls them.
Identity, tenancy or permissions come from your app's session, and the model shouldn't be able to choose them.
Tool results trigger side effects your app needs to act on in the same request.
You run on serverless with a tight time budget.
You have a handful of tools you'd version with your code anyway.

Use MCP when:

You want the same tools available in several hosts: Claude, ChatGPT, Cursor, Claude Code, your own agent.
A vendor already publishes an MCP server for the system you need, and building your own integration would just duplicate it.
Another team owns the tools and needs to ship changes without redeploying every agent.
You're exposing your product to other people's agents. That's a real distribution channel now, and an MCP server is how you show up in it.

Either way:

Expose as few tools as the job needs. Filter MCP servers with allowlists; don't hand the model forty tools to use three.
Keep anything that decides who or which account out of the model's arguments.
Cap the loop and the spend from day one. Neither the protocol nor the provider will do it for you.

Most production agents I'd design today end up with mostly function calling plus, at most, a couple of MCP servers for third-party systems. If you need an agent that touches real systems, and you want someone who's shipped them to draw that line with you, that's what I do. If budget is the next question, read what AI agent development actually costs; if you're still choosing the model, Claude vs GPT for AI agents.

FAQ

What is the difference between MCP and function calling?

Function calling (tool use) is a feature of a model's API: you send tool definitions with the request, the model replies with a tool name and JSON arguments, and your code runs the tool and sends the result back. MCP (Model Context Protocol) is an open client-server protocol that lets an application discover tools published by a separate server (tools/list) and invoke them (tools/call). An MCP client still hands those tools to the model through function calling, so MCP sits one layer above it rather than replacing it.

Should I use MCP or function calling for my AI agent?

If the tools belong to your product and only your agent calls them, use plain function calling: no extra server, and your code keeps control of identity, tenancy and side effects. Use MCP when the same tools must be reused across several agents or hosts (Claude, ChatGPT, Cursor, Claude Code), when a third party already publishes an MCP server for the system you need, or when another team owns the tools. Most production agents end up with mostly function calling and, at most, a couple of MCP servers.

Does MCP replace function calling?

No. MCP standardises how tools are packaged, discovered, authorised and executed; the model still selects them through its provider's function-calling mechanism. Anthropic's MCP connector turns MCP tools into mcp_tool_use blocks in the Messages API, and OpenAI's mcp tool type imports them into the Responses API, but in both cases the model is doing ordinary tool use underneath.

Can I call an MCP server directly from the Claude or OpenAI API?

Yes, for remote servers. As of October 2026, Anthropic's MCP connector (beta header mcp-client-2025-11-20) connects the Messages API to MCP servers exposed over HTTP; it supports tool calls only, not local stdio servers, and is not eligible for zero data retention. OpenAI's Responses API has an mcp tool type with server_url, allowed_tools and require_approval, plus Secure MCP Tunnel for private servers, and charges no per-call fee beyond the tokens of the imported tool definitions and calls. On both, every tool you import takes up context, so filter.

What changed in the MCP spec in 2026?

The current revision, 2026-07-28, made MCP stateless: the initialize handshake and the Mcp-Session-Id header are gone, every request carries its protocol version and client capabilities in _meta, and servers must implement server/discover. It also deprecated Roots, Sampling and Logging, moved tasks into an official extension, and asks servers to return tools/list in a deterministic order so clients get better prompt-cache hit rates.

Does Joan Comadran use MCP in production agents?

No. The agents he ships to clients and his own products, such as Claient, the WhatsApp lead agent, use plain tool use through the Anthropic TypeScript SDK, with tool definitions in code and tenant scoping enforced by the executor. He uses MCP as a consumer: coding agents and personal assistants connected to services like Supabase, Gmail, Google Calendar and Notion. He has not shipped an MCP server to production.

Originally published on joancomadran.dev. I'm Joan, an AI engineer in Barcelona — work with me.

Secure your OpenAI API key (and your Claude and Gemini keys): a checklist

Joan Comadran — Mon, 19 Oct 2026 09:48:21 +0000

On October 17, OpenCode posted on X that it "had a security breach last night" affecting 1.4% of OpenCode Console users, "a subset of users who had external providers linked", and that it was working with Anthropic, OpenAI and Google to remediate. The email those users received, as reported by The Hacker News, says provider keys saved in Console workspaces may have been exposed. Within hours, Anthropic's Lydia Hallie said Anthropic had revoked the Claude API keys it believes were affected, and Google's Evan Otero said Google had blocked the exposed Gemini keys. As of October 19, 2026, OpenCode calls the incident ongoing and hasn't said how it happened. I'm not going to guess.

What matters for the rest of us is simpler. An LLM API key is a bearer credential: whoever has the string can spend your money until the provider revokes it. Securing it means fewer places where the string lives, and less damage when one of them leaks anyway.

The checklist, short version

One key per tool, project and environment.
Keys that expire, and a rotation you've actually rehearsed.
Hard spend limits per project, not just alerts.
Keys only on the server: route handlers, server actions, environment variables. Never NEXT_PUBLIC_.
A separate, capped, short-lived key for any hosted tool you paste a key into.
A first-hour plan for when one leaks.

Provider details below come from OpenAI's, Anthropic's and Google's own docs as of October 19, 2026. They change often.

One key per tool, project and environment

If every script, agent and SaaS shares one key, any leak means revoking the key production runs on. With one key per consumer you revoke one thing, and the usage page tells you which consumer was abused.

OpenAI. Keys live in projects. OpenAI's key safety article says sharing keys is against the Terms of Use and that you can assign permissions to individual keys.
Anthropic. Workspaces separate environments and spend. New keys are either personal keys, which act as you, or service account keys, and either can be scoped to a single workspace. Personal keys die when their owner leaves the organization, which is what you want. Workspace keys are now documented as legacy.
Google. Every Gemini key belongs to a Google Cloud project, and usage from all its keys counts toward the project's spend cap (billing docs). Separate caps per tool means separate projects.

Keys that expire, and a rotation you've rehearsed

A key that never expires stays valid for as long as anyone has a copy.

OpenAI project keys can be created with an expiration date, and admins can enforce a maximum key lifetime at organization or project level.
Anthropic asks for an expiration when you create a key: 3 hours, 1 day, 7 days, 30 days, a custom duration, or Never. It can't be changed afterwards, an organization policy can remove Never, and Anthropic emails the creator 7 days before expiry for keys that live at least 14 days.
Google's Gemini key docs don't mention expiry. They tighten keys another way: since May 28, 2026, new AI Studio keys are bound to a service account and restricted to the Gemini API by default, and unrestricted standard keys are rejected.

OpenAI and Google describe the same rotation order: create the replacement, deploy it, verify it works, then revoke the old one. Rehearse it on a quiet day to learn where the key actually lives (production, previews, CI, that cron job) before you have to do it under pressure. OpenAI and Anthropic also document workload identity federation, which swaps the stored key for short-lived tokens on supported cloud workloads: rotation with nothing to rotate.

Hard spend limits, not just alerts

OpenAI's article says it plainly: "Spend alerts alone don't stop API traffic." An email at 3 a.m. is a receipt for money that's already gone.

Provider	Hard cap	What the docs warn about
OpenAI	Monthly spend limits per organization or project, with hard enforcement	Enforcement isn't instantaneous; hard limits can also block legitimate requests
Anthropic	Monthly spend limit per workspace, below the organization limit	Can't be set on the Default Workspace
Google	Monthly project spend cap in AI Studio, plus tier caps per billing account	Experimental, around 10 minutes of latency; batch jobs and agent sessions can overshoot

Same for auto-reload: Anthropic's key best practices treat auto-reload limits as a safeguard against leaked keys, and Google's Prepay plan has a monthly auto-charge limit. Uncapped auto-reload is an uncapped card.

For agents you build yourself, add a cap in code too. In Claient, when an account uses the platform's key, the webhook reserves budget atomically before each turn and stops replying when the monthly cap is hit. I described the same kill-switch idea in keeping Claude's token bill from ruining your month, and how to set caps for coding agents in Claude Code cost per month.

Keys stay on the server

OpenAI and Google both say it: no keys in browser or mobile code, route calls through your backend. In Next.js the line is the NEXT_PUBLIC_ prefix. Next.js inlines those values into the JavaScript bundle at build time, so an LLM key with that prefix is a published key.

// lib/llm.ts
import 'server-only'; // importing this from a Client Component fails the build
import Anthropic from '@anthropic-ai/sdk';

export const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

// app/api/chat/route.ts
import { anthropic } from '@/lib/llm';

export async function POST(req: Request) {
  // Authenticate and rate-limit first: a public route that proxies
  // your key is still your key.
  const { message } = await req.json();
  const res = await anthropic.messages.create({
    model: MODEL, // whatever you pin in config
    max_tokens: 512,
    messages: [{ role: 'user', content: message }],
  });
  return Response.json(res.content);
}

That's the pattern in Claient: the platform's key is read from ANTHROPIC_API_KEY in the server-side engine config, and the only key with a NEXT_PUBLIC_ prefix is Supabase's anon key, which is meant to be public. More on that split in the Next.js + Supabase pre-launch security checklist and in shipping an AI product in a weekend.

If your backend has fixed egress IPs, restrict by IP too. OpenAI's IP allowlist works per organization or project for all API customers and rejects other IPs with a 401 ip_not_authorized, valid key or not. Google lets you restrict a key to IP addresses under Application restrictions in the Cloud console. Anthropic's help center lists IP allowlisting for Enterprise plans, set up through support.

Think twice before pasting a key into a hosted dashboard

Anthropic's help center has the most honest sentence on this: when you upload your API key to a third-party tool, "you are giving the developer of that tool access to your Claude Console account." That isn't a comment on OpenCode. It's how every hosted tool that calls a model with your key works, including the one I build. And deleting a key inside the tool doesn't revoke it. Only the provider can.

Claient accepts customers' own Claude keys (BYOK), so I'm on the other side of this. In its code the key goes into Supabase Vault and the settings table keeps only the secret's id. The function that returns the decrypted key can only be executed by the service_role the webhook uses, so no dashboard user, owner included, can read it back, and the UI never shows it again. If a customer's key gets revoked, the bot falls back to the platform key and notifies the business instead of going quiet. That limits what a dashboard bug can leak. It doesn't make a key unstealable from a compromised server; nothing does.

So on the customer side: give each hosted tool a dedicated key in its own project or workspace, with a low cap and an expiry, and ask the vendor where the key is stored, whether it's encrypted, and what can decrypt it.

Building an agent that holds customer API keys and want the storage, caps and fallbacks right from day one?

The first hour after a key leaks

Kill it at the provider, not in the tool. OpenAI says to rotate immediately from the API keys page; in the Claude Console, Disable is reversible and Delete is permanent. If the key is being abused right now, revoke first and accept a few minutes of downtime. Create-then-revoke is for planned rotations.
Issue the replacement properly. Right project or workspace, with an expiry, and deploy it everywhere the old one lived.
Check usage per key back to the earliest date the key could have leaked, not just today.
Lower the spend limit while you investigate.
Find the leak, then fix it. Git history (deleting the file in a later commit doesn't remove it), CI and error logs, any tool you pasted it into.
Contact billing support with the key ID, the dates and what happened. OpenAI's article points to help.openai.com.

FAQ

How do I secure my OpenAI API key?

Keep it on the server (environment variables or a secrets manager, never in client code or git), use one key per tool and project, create project keys with an expiration date, set a monthly spend limit with hard enforcement, and use IP allowlisting if your backend has fixed IPs. All of it is in OpenAI's key safety article as of October 2026.

How do I rotate an Anthropic API key?

Create a new key in the Claude Console with an expiration, deploy it everywhere the old one is used, confirm it works, then disable (reversible) or delete (permanent) the old key. Expiration is chosen at creation and can't be changed later.

Do spend alerts protect me if my API key leaks?

No. An alert tells you money is being spent; it doesn't stop it. Use hard caps: OpenAI spend limits with hard enforcement, Anthropic workspace spend limits, Google AI Studio project spend caps. None are instant, but a cap turns an open-ended bill into a bounded one.

Is it safe to paste my API key into a third-party tool?

Only if you'd trust that vendor with your provider account, because that's what you're giving them. If you do, give the tool its own key in its own project or workspace, with a low cap and an expiry. Deleting the key inside the tool doesn't revoke it; only the provider can.

None of this is exciting, which is the point: the boring setup is what keeps a breach somebody else's headline instead of your invoice. If you want an AI product built that way from the start, here's how I work.

Originally published on joancomadran.dev. I'm Joan, an AI engineer in Barcelona — work with me.

Supabase email confirmation not working in Next.js: every cause and the fix

Joan Comadran — Mon, 19 Oct 2026 08:05:32 +0000

If Supabase email confirmation isn't working in your Next.js app, the most likely cause is PKCE: the default link ends in exchangeCodeForSession, which only works in the browser where the user signed up. Open the email on a phone and you get PKCE code verifier not found in storage. The fix is to change the Confirm signup template to link to your own route and verify the token_hash there:

<a href="{{ .SiteURL }}/auth/confirm?token_hash={{ .TokenHash }}&type=email&next=/onboarding">
  Confirm your email
</a>

// app/auth/confirm/route.ts
const { error } = await supabase.auth.verifyOtp({ token_hash, type: 'email' });

If that's not your symptom, the table below maps the other ones. All of this comes from the sign-up flow of Claient, a multi-tenant WhatsApp lead agent on Next.js and Supabase, where I hit most of these between June and July 2026. Facts about Supabase defaults are as of October 2026.

Which one do you have?

Symptom	Likely cause	Fix
`PKCE code verifier not found in storage`	Link opened in another browser, app or device	`token_hash` + `verifyOtp` route
`Email link is invalid or has expired` / `otp_expired`	Link already used, older than 1 hour, or opened by a mail scanner	Resend flow; click-to-confirm page for corporate mail
Link lands on `localhost:3000`	Site URL never changed, or `emailRedirectTo` not on the allow list or relative	Fix URL Configuration, absolute URLs
No email at all	Built-in sender's 2 emails/hour limit, or the address is already confirmed	Custom SMTP; check `identities`
Clicked the link, still `email_not_confirmed`	Confirm route behind auth middleware, or a trigger on `auth.users` failing	Make the route public, debug the trigger

Why does the confirmation link fail in another browser?

With @supabase/ssr, a Next.js app uses the PKCE flow. When the user signs up, the client stores a code verifier in a cookie. The default {{ .ConfirmationURL }} goes to Supabase's /verify endpoint, which redirects back to your app with ?code=..., and exchangeCodeForSession(code) sends the code plus that verifier to get a session.

No verifier, no session. That happens whenever the click doesn't come from the sign-up browser: the Gmail app's in-app browser, a phone when the user signed up on a laptop, a private window. The auth code also expires after 5 minutes and works once.

My first version of the Claient callback (commit 5cf4697, June 2026) was exactly the textbook PKCE handler:

// The first version: works only in the sign-up browser
if (code) {
  const { error } = await supabaseServer().auth.exchangeCodeForSession(code);
  if (!error) return NextResponse.redirect(`${origin}${next}`);
}
return NextResponse.redirect(`${origin}/login?error=Could not confirm the account`);

It works as long as the click comes from the sign-up browser, which is exactly what you do when you test it yourself. Two days later (436f7d0) it learned the token_hash path, which doesn't depend on cookies at all. verifyOtp sends the hashed token to Supabase and gets a session back, so it works from any device. That's why Supabase's own Next.js examples use an /auth/confirm route with verifyOtp for email links.

The route I run in production

This is the Claient route, translated and trimmed (in Claient it lives at /auth/callback). It handles both link shapes, because which one arrives depends on the template, and it reads the error Supabase attaches when its own /verify step fails:

// app/auth/confirm/route.ts
import { NextRequest, NextResponse } from 'next/server';
import type { EmailOtpType } from '@supabase/supabase-js';
import { createClient } from '@/lib/supabase/server';

export async function GET(req: NextRequest) {
  const { searchParams, origin } = req.nextUrl;
  const tokenHash = searchParams.get('token_hash');
  const type = searchParams.get('type') as EmailOtpType | null;
  const code = searchParams.get('code');
  const next = internalPath(searchParams.get('next'), '/onboarding');

  const fail = (msg: string) =>
    NextResponse.redirect(`${origin}/login?error=${encodeURIComponent(msg)}`);

  // Supabase redirects with ?error_description=... when the link was expired or used
  const supabaseError = searchParams.get('error_description') || searchParams.get('error');
  if (supabaseError) return fail(friendly(supabaseError));

  const supabase = await createClient();

  // token_hash: stateless, works on any device
  if (tokenHash && type) {
    const { error } = await supabase.auth.verifyOtp({ type, token_hash: tokenHash });
    return error ? fail(friendly(error.message)) : NextResponse.redirect(`${origin}${next}`);
  }

  // code: PKCE, only works in the browser that started the flow
  if (code) {
    const { error } = await supabase.auth.exchangeCodeForSession(code);
    return error ? fail(friendly(error.message)) : NextResponse.redirect(`${origin}${next}`);
  }

  return fail('This confirmation link is not valid.');
}

// `next` comes from the URL: only allow internal paths ('//evil.com' is an open redirect)
function internalPath(raw: string | null, fallback: string) {
  if (raw?.startsWith('/') && !raw.startsWith('//') && !raw.startsWith('/\\')) return raw;
  return fallback;
}

function friendly(raw: string) {
  const m = raw.toLowerCase();
  if (m.includes('expired')) return 'This link has expired. Sign in and we will send a new one.';
  if (m.includes('invalid') || m.includes('used')) return 'This link was already used. If you confirmed, just sign in.';
  return 'Could not confirm the account. Please sign in.';
}

Three details that each cost me a commit:

The next guard. A ?next= parameter you redirect to is an open redirect unless you check it. Claient's callback has had this guard since the audit fixes, and 03f1753 moved it into one shared helper after a code review found the same protocol-relative hole (//other-site.com) in another redirect. I wrote about the same trap in the pre-launch security checklist.
Async client. On Next.js 15 and later cookies() is async, so the server client factory is await createClient(). Claient predates that and its helper is synchronous.
Same route for password recovery. resetPasswordForEmail points at it with next=/reset-password, so one route verifies every email link.

How do I fix "Email link is invalid or has expired"?

This one (otp_expired, a 403 on /verify) is about the token, not your code. Three causes:

It was already used. Users double-click, or click the second of two emails after the first one already confirmed them.
It expired. Email links last 1 hour by default. You can raise it under Authentication > Sign In / Providers > Email > Email OTP expiration, but Supabase discourages anything over a day.
A scanner opened it first. Corporate mail security (Microsoft Defender Safe Links is the usual example in Supabase's docs) fetches every link to check it. With a link that confirms on GET, the scanner confirms for you and the user's click fails. Your own /auth/confirm route has the same problem, since it verifies on GET too. If your users are on corporate email, link to a page with a "Confirm" button that does the verifyOtp call, or send the 6-digit {{ .Token }} code and verify it with verifyOtp({ email, token, type: 'email' }).

The fix that mattered more for Claient was the dead end. The login page used to say "confirm your account, check your email", and if that email was expired there was no way to get another one. Since d8f1009, signing in with an unconfirmed account resends the email on the spot:

const { error } = await supabase.auth.signInWithPassword({ email, password });

if (error?.code === 'email_not_confirmed') {
  const { error: resendError } = await supabase.auth.resend({
    type: 'signup',
    email,
    options: { emailRedirectTo: `${appUrl()}/auth/confirm` },
  });
  // tell the user it was resent, or to wait a minute if resend was rate limited
}

Before that, Claient showed the same "wrong email or password" message for both cases (18678b9 split them). Telling users their account exists but isn't confirmed, and handing them a fresh link, is the difference between a stuck user and a signed-in one.

Why does the confirmation email redirect to localhost?

Supabase uses emailRedirectTo only if it matches an entry in the Redirect URLs allow list. Otherwise it falls back to the Site URL, and a new project's Site URL is http://localhost:3000. So:

Set the Site URL to your production domain in Authentication > URL Configuration.
Add each redirect you use. Matching is exact unless you use wildcards: https://example.com/** for a whole domain, a Vercel preview pattern if you test confirmation on previews.
Always send an absolute URL. Claient originally built the redirect from NEXT_PUBLIC_APP_URL with an empty-string fallback, so without the variable it became a relative /auth/callback. Supabase ignores relative redirects, and the password recovery flow broke silently. 03f1753 replaced it with an appUrl() helper that always returns an absolute URL.

If your template uses {{ .SiteURL }}, the link goes to the Site URL no matter what you pass. Use {{ .RedirectTo }} in the template if you need per-environment links.

Why is the Supabase confirmation email not arriving?

The built-in sender is for testing. As of October 2026 it allows 2 emails per hour per project. Two test sign-ups and you're done for the hour. Set up custom SMTP before you launch; the limit becomes configurable after that.
Per-user cooldown. The same address has to wait 60 seconds between confirmation requests, so a quick "resend" gets rate limited.
The address is already confirmed. To avoid revealing which emails have accounts, signUp on a confirmed address returns a fake user with an empty identities array and no session. Claient checks data.user.identities.length and shows the same neutral "check your email" screen, with links to sign in or reset the password.
Spam folder. Default sender, default template, no custom domain: it happens. Custom SMTP on your own domain helps here too.

The user clicked, but still gets "Email not confirmed"

Then the verify step didn't succeed. Check in this order:

Is the confirm route public? If your middleware.ts (renamed proxy.ts in Next.js 16) redirects signed-out users to /login, and its matcher covers /auth/confirm, the user is bounced before anything verifies. Claient's matcher only covers /dashboard/:path*; in pollitics.es the proxy matcher lists the few routes that need the session and nothing else.
Does a trigger on auth.users fail? A function that creates a profile on sign-up or confirmation and throws (a renamed column, a text-to-uuid cast) makes the confirmation fail with a database error. Supabase's GitHub issues are full of this one. Claient avoids the trigger: the sign-up server action runs an idempotent account setup with the service key instead, which is easier to debug and retry.
Is it the right project? A preview deployment pointing at a different Supabase project than the one that sent the email. Boring, but worth ruling out.
Read the Auth logs. The /verify request and its error code tell you which of the sections above you're in.

A 60-second checklist

Confirm signup template links to your route with token_hash and type=email, not {{ .ConfirmationURL }} plus exchangeCodeForSession.
The route calls verifyOtp, validates next, and turns Supabase's errors into messages users understand.
Site URL is production; every emailRedirectTo is absolute and on the allow list.
Custom SMTP before launch.
Sign-in with email_not_confirmed resends the email instead of leaving users stuck.
The confirm route isn't behind your auth middleware or proxy.

Once confirmation works, the next Supabase error people hit is usually the first insert right after sign-up. That's new row violates row-level security policy. If you're putting Claude behind that login, building a WhatsApp bot with Claude covers the part of Claient after onboarding.

FAQ

Why is Supabase email confirmation not working in my Next.js app?

Usually because a Next.js app using @supabase/ssr runs the PKCE flow, and the default confirmation link ends in exchangeCodeForSession, which needs a code verifier cookie stored in the browser where the user signed up. If the email is opened in another browser, app or device, the exchange fails with "PKCE code verifier not found in storage". Point the Confirm signup email template at your own route with token_hash and type, and call supabase.auth.verifyOtp({ token_hash, type: 'email' }) there. That works on any device.

How do I fix "Email link is invalid or has expired" in Supabase?

The token was already used, has expired (email links last 1 hour by default, configurable under Email OTP expiration), or was consumed by an email security scanner that opened the link before the user did. Check the Auth logs for otp_expired. Give users a way to request a new email, for example by calling supabase.auth.resend({ type: 'signup', email }) when sign-in returns email_not_confirmed, and if your users are on corporate mail, make the link land on a page that only verifies after a button click, or send the 6-digit {{ .Token }} code instead.

Why does my Supabase confirmation email redirect to localhost?

Supabase falls back to the Site URL when no valid redirect is provided, and new projects start with http://localhost:3000. Set the Site URL to your production domain under Authentication > URL Configuration, add every emailRedirectTo you use to the Redirect URLs allow list (it is an exact match unless you use wildcards), and always pass an absolute URL. A relative emailRedirectTo is ignored.

Why is the Supabase confirmation email not arriving?

As of October 2026, the built-in email provider is limited to 2 emails per hour per project and is meant for testing, and the same user has to wait 60 seconds between confirmation requests. Configure custom SMTP before launch. Also check whether the address was already confirmed: in that case signUp returns an obfuscated user with an empty identities array and there is nothing to confirm.

Should I use verifyOtp or exchangeCodeForSession for email confirmation?

For email links in a server-rendered Next.js app, verifyOtp with token_hash. It is stateless and does not depend on cookies from the sign-up browser. exchangeCodeForSession is for flows that start and finish in the same browser, such as OAuth sign-in, and its auth code is valid for 5 minutes and single use.

The user confirmed but still gets "Email not confirmed". Why?

The verify step never succeeded. Common reasons: the confirm route is behind your auth middleware or proxy and redirects to login before verifying, a trigger on auth.users throws during confirmation, or the user clicked an old link. Check the Auth logs for the /verify request, make sure the route is public, and test the trigger by inserting into the tables it writes.

Auth is the unglamorous part of every product I build, and the part users notice first when it breaks. If you want a sign-up flow like this one built into your product, here's how I work.

Originally published on joancomadran.dev. I'm Joan, an AI engineer in Barcelona — work with me.

Claude Code cost per month: how to budget it before finance does

Joan Comadran — Fri, 16 Oct 2026 21:53:48 +0000

On October 15, 404 Media reported that Accenture told many employees it will now spend only $29 a month per person on Claude. Some of those people had been spending as much as $1,000 a month, and are now, in the article's words, scrambling to keep the same level of usage. Joseph Cox's post about it went past two million impressions on X, which tells you how many people looked at their own bill and felt something.

The article also points out the irony: Accenture has spent years telling clients to invest heavily in AI. Fine. Irony is free. Tokens aren't.

I'm not going to argue about whether $29 is the right number for a consultancy. The useful question is the boring one: what does Claude Code actually cost per month, and how do you budget it so the cap is a decision instead of a reaction?

What Claude Code costs in October 2026

Claude Code doesn't have its own price tag. It comes with Anthropic's paid plans, and it shares the usage pool with regular Claude chat. From Anthropic's pricing page, checked on October 16, 2026:

Option	Price	What you're really buying
Free	$0	No Claude Code
Pro	$20/month, or $17/month billed annually	Claude Code with usage limits
Max	From $100/month	5x or 20x Pro's usage per session, plus monthly API credits
Team	Per seat	Admin, central billing, user and org spend controls
Enterprise	$20/seat/month + usage at API rates	Everything in Team, billed annually
Console (API)	Per token	No plan limits, no ceiling unless you set one

Two details matter more than the headline prices.

First, subscription limits reset on a rolling five-hour window, with weekly limits on top, and Anthropic doesn't publish a fixed message count. How far a plan goes depends on the model, the length of the context and what the agent is doing. So "Pro is $20" is true and also only half the answer.

Second, the API has no ceiling by default. For reference, the same page lists Opus 5.5 at $4 input / $20 output per million tokens, Sonnet 5.5 at $2 / $10, and Haiku 5.5 at $0.10 / $0.50 for prompts up to 100K tokens ($0.50 / $2.50 above that). Claude Code's fast mode for Opus 5.5 is listed at $8 / $40. Those look like small numbers until an agent rereads your repo forty times in an afternoon.

That second point is probably how somebody gets to $1,000.

Why coding agents burn more than chat

A chat costs what you type plus what you read. An agent costs what it reads to decide what to do, over and over, and you don't see most of it.

I wrote about the same mechanics on the API side in Keeping Claude's token bill from ruining your month: LLMs are stateless, so every turn resends the whole conversation. A coding agent makes that worse in three ways:

Context is big by default. Files, diffs, test output, tool definitions. The agent pulls them in because that's its job.
Loops. Run the tests, read the failure, edit, run again. Each lap resends the growing context.
Model choice is sticky. If the default is the most capable model, every trivial rename gets frontier pricing.

None of that is a bug. It's the product working as designed, which is exactly why it's easy to stop noticing the meter.

How to budget it: start from the work, not the price list

A per-seat number like $29 is a budget built from the price list. It's simple to administer and it will be wrong for almost everyone: too much for people who open Claude twice a week, far too little for the person whose whole job is now reviewing what an agent wrote.

A better order:

Measure two normal weeks. Not a demo week. Normal. On Team and Enterprise there's usage analytics; on the API every response tells you the tokens it used.
Group people by how they work, not by title. Occasional users, daily users, "the agent is my pair programmer" users. You'll usually find a long tail and a small heavy group.
Give each group the cheapest option that doesn't interrupt them. Occasional users on Pro. Heavy users on Max or a premium seat, because a fixed monthly price is easier to defend than an open-ended API bill. Automated pipelines on the API, with a hard limit.
Re-check monthly. Models and prices move. A budget you set once is a budget you'll get surprised by.

If you're solo, the same logic applies with smaller numbers: if you keep hitting the five-hour limit on Pro, that's the signal to try Max for a month and compare, not to quietly add API credits on top and forget about them.

How to measure it

You can't cap what you don't measure, and "the invoice" is not a measurement, it's a post-mortem.

For agents I build on the API, the cost comes straight off the response: input tokens, output tokens, cache reads and writes. Log those per call, tag them with the user or tenant and the task, and "who is expensive and why" stops being a guess and becomes a GROUP BY. That's the setup I described in the token bill post, and it works just as well for internal tools as for products.

The useful metric isn't cost per user. It's cost per finished task: per merged PR, per fixed bug, per qualified lead. $1,000 a month is expensive if it buys a lot of rerun test loops. It's cheap if it replaces a week of someone's time. Accenture's cap treats both cases the same, which is the part I'd question if I worked there.

How to cap it without killing the useful part

Caps work best in layers, each set where the money is actually spent:

Plan limits. Subscriptions already cap you; the five-hour window is a budget whether you like it or not.
Admin spend controls. Team and Enterprise plans list user and organization-level spend controls. Use them per group, not one flat number for everyone.
API hard limits. For anything on Console keys, set a workspace limit. An automation with an uncapped key is how a typo becomes an invoice.
In-code limits for your own agents. A daily budget check before each call and an iteration cap on tool loops. In my WhatsApp bot, an iteration cap of five on the tool loop is what stops a runaway loop from turning into a runaway bill. I wrote that up in the Claude token post as "a kill switch".

Building an agent and want the cost controls in from day one instead of after the first scary invoice?

The cheap wins before anyone caps anything

Most of the savings come from not paying for the same tokens twice:

Prompt caching for the static part of the context. Cache reads are a small fraction of the input price on every model on Anthropic's list.
Right model per task. Classification, renames and boilerplate don't need the top model. Route them to Haiku or Sonnet.
Shorter context. Point the agent at the files that matter instead of letting it rediscover the repo every session.
Batch what isn't urgent. Anthropic's Batch tier exists for exactly the work nobody's waiting on.

If you're estimating the full cost of an agent you're building, not just the coding tool you use, I broke the build and run costs down in AI agent development cost.

So, is $29 a month enough?

For someone who uses Claude occasionally to draft or explain things, probably yes. Pro alone is $20. For someone running Claude Code as a daily coding agent, no, and the 404 Media piece suggests the people affected already know that.

The lesson isn't "AI is too expensive" or "companies are cheap". It's that usage-based tools need a budget built from usage. Measure for two weeks, split people by how they actually work, cap in layers, and track cost per finished task. That's less dramatic than a memo, and it doesn't leave your best people scrambling for tokens on a Tuesday.

FAQ

How much does Claude Code cost per month?

As of October 2026, Claude Code has no standalone price. It's included in Anthropic's paid plans: Pro at $20/month ($17/month billed annually), Max from $100/month (5x Pro usage) up to the 20x tier, plus Team and Enterprise seats. Enterprise is listed at $20 per seat per month plus usage at API rates. You can also run Claude Code with a Console account and pay per token at API prices, with no monthly ceiling unless you set one.

Is a subscription or the API cheaper for Claude Code?

For one person coding most days, a subscription is usually the predictable option: a fixed price with usage limits that reset on a rolling five-hour window plus weekly caps. The API is cheaper for light or bursty use and is the only option where the ceiling is entirely yours to set, which also means nobody sets it for you. Measure a couple of weeks of real usage before deciding.

Why did Accenture cap Claude at $29 a month?

According to 404 Media (October 15, 2026), Accenture told many employees it would now spend only $29 a month per person on Claude, after some had been spending as much as $1,000 a month. The article frames it as part of a wider trend of companies curbing AI tool spend once usage outgrew budgets. It doesn't publish an internal rationale beyond that.

How do I stop an AI coding agent from blowing the budget?

Set the cap where the money is spent, not in a spreadsheet: per-user or per-org spend limits in the Team/Enterprise admin, a hard limit on the API workspace, and in your own agents a per-day budget check and an iteration cap on tool loops. Then log cost per task so you know which work is worth the tokens.

Originally published on joancomadran.dev. I'm Joan, an AI engineer in Barcelona — work with me.

Supabase "new row violates row-level security policy": every cause and the fix

Joan Comadran — Wed, 14 Oct 2026 13:48:04 +0000

If Supabase is throwing new row violates row-level security policy for table "your_table" (code 42501, HTTP 403), Row Level Security is on and the row you're writing didn't pass any policy's WITH CHECK. Nine times out of ten the fix is one of these two:

-- 1. The table has no INSERT policy. Add one:
create policy "insert own rows" on public.notes
  for insert to authenticated
  with check ((select auth.uid()) = user_id);

-- 2. The row doesn't carry the user's id. Let the database fill it:
alter table public.notes
  alter column user_id set default auth.uid();

If that didn't do it, one of the other four causes below is yours. I'll show how to tell which, with the SQL for each. The examples come from the RLS I've written for two production Supabase apps: Claient, a multi-tenant WhatsApp lead agent where every row belongs to an account, and pollitics.es, a public polling site.

What the error actually means

RLS is default-deny per command. Enabling it on a table without policies blocks everything for anon and authenticated. A SELECT policy lets people read, but it says nothing about INSERT, UPDATE or DELETE. Each of those needs its own policy, or a for all policy.

Two clauses matter:

USING: which existing rows you can see, update or delete.
WITH CHECK: which new row values you're allowed to write (inserts, and the after-image of updates).

"new row violates…" always means a WITH CHECK evaluated to false or null for your row. It never means "the table doesn't exist" or "your key is wrong".

Cause 1: there is no INSERT policy

The classic one. You enabled RLS, added "Enable read access for authenticated users", and reads work, so you assume writes will too. They won't.

Check what you have:

select policyname, cmd, roles, qual, with_check
from pg_policies
where schemaname = 'public' and tablename = 'notes';

If no row has cmd = INSERT or ALL, add the policy from the top of this post. If you want one policy per table, for all with both clauses is fine. This is how every tenant table in Claient is written:

create policy leads_all on public.leads
  for all using (public.is_account_member(account_id))
  with check (public.is_account_member(account_id));

Cause 2: user_id is null or not the caller

Your policy says with check (auth.uid() = user_id), but the client inserted { title } without user_id. Then auth.uid() = null is null, not true, and the row is rejected.

Don't make the client responsible for sending its own id. Set a default so it can omit the column:

alter table public.notes alter column user_id set default auth.uid();

Keep the WITH CHECK anyway. A default only applies when the column is omitted, so the policy is what stops a client sending someone else's id.

Cause 3: the request isn't authenticated (auth.uid() is null)

The policy and the column are right, and it still fails. The usual culprit is that the request reached Postgres as anon, so auth.uid() is null and every auth.uid() = … check fails. That happens when:

a Server Action or Route Handler uses a client created with createClient(url, anonKey) and no session;
in Next.js with @supabase/ssr, the server client isn't reading the request cookies, or the session cookie expired and was never refreshed by middleware;
the insert runs before the session exists, e.g. right after signUp() with email confirmation still pending.

Quick test: run select auth.uid(), auth.role(); through the same client (as an RPC), or log await supabase.auth.getUser() right before the insert. If it's null or anon, fix the client, not the policy. On the server, build the client with createServerClient from @supabase/ssr and pass it the request cookies. That's how the dashboard in Claient does it.

If you're creating a profile row right after sign-up, don't insert from the client at all. Use a trigger on auth.users with a security definer function, which runs regardless of the session.

Cause 4: insert().select() without a SELECT policy

const { data, error } = await supabase.from('notes').insert({ title }).select();

.select() turns the statement into INSERT … RETURNING *. Postgres must let you read the row you just wrote, so a table with an INSERT policy but no matching SELECT policy fails with the same "new row violates" message. It's confusing because the insert is the part that's allowed.

Fix: add a SELECT policy that covers the new row, or drop .select() if you don't need the row back.

The same thing explains the famous Storage version of the error. Uploads do an INSERT … RETURNING on storage.objects, so you need a SELECT policy on storage.objects for that bucket and path, not just an INSERT one. Supabase's troubleshooting note confirms it.

Cause 5: an UPDATE whose new row fails WITH CHECK

Updates are checked twice: USING on the old row, and WITH CHECK on the new one. If the UPDATE policy has no WITH CHECK, Postgres reuses the USING expression for it. So an update that changes a column your policy depends on, like moving a row to another account or user, is rejected with "new row violates…".

Usually that's exactly what you want: it stops users from writing a row into someone else's tenant. If it's blocking a legitimate update, look at which column in your SET the policy reads, and write an explicit WITH CHECK for the state the row is allowed to end up in. Don't reach for with check (true) unless you've thought through what it lets through.

Cause 6: a policy that can't see what it needs

Multi-tenant policies often check membership in another table:

using (exists (select 1 from account_members m
               where m.account_id = leads.account_id and m.user_id = auth.uid()))

If account_members has RLS too, that subquery runs under the caller's policies. It can come back empty, making the check false, or recurse into itself if account_members' own policy does the same lookup. The fix I use in Claient is one security definer function that every policy calls:

create or replace function public.is_account_member(target_account uuid)
returns boolean
language sql
stable
security definer
set search_path = public
as $$
  select exists (
    select 1 from public.account_members m
    where m.account_id = target_account
      and m.user_id = auth.uid()
  );
$$;

security definer makes the lookup run as the function's owner, so it doesn't depend on account_members' own policies and can't recurse. set search_path stops anyone from shadowing the table with their own. I go deeper into this pattern, including wrapping calls as (select fn()) so they run once per query instead of once per row, in the pre-launch security checklist for Next.js + Supabase.

Not this error: "permission denied for table"

Same 42501 code, different problem. permission denied for table notes (or for column status) means the role lacks a GRANT, which Postgres checks before RLS. No policy will fix it.

I hit this deliberately in Claient. Users could update their own feature request, and the RLS policy limited that to their own row. But RLS can't limit which columns you change, so someone could call PostgREST directly and mark their own request as "done". The fix was column-level grants:

revoke update on public.feature_requests from authenticated;
grant update (title, description) on public.feature_requests to authenticated;

Now updating status as a user returns "permission denied for column", while the admin path still works.

When the service_role key is the right answer (and when it isn't)

The fastest way to make the error go away is the service_role (secret) key, which bypasses RLS completely. That's correct for server code that legitimately acts across users. In Claient, the WhatsApp webhook writes messages and leads for whichever tenant the message belongs to, and the Stripe webhook writes subscriptions. Those tables deliberately have no write policy for users, so only the server can write them. Some internal tables have RLS on with zero policies, which is deny-all for everyone but service_role.

It's the wrong answer in user-facing code. The key must stay server-only (never NEXT_PUBLIC_), and swapping it in to silence an error means that request no longer has any data isolation.

A 60-second checklist

select * from pg_policies where tablename = 'x': is there an INSERT/UPDATE/ALL policy for the right role?
Does it have a WITH CHECK, and does your row satisfy it? Is user_id actually set?
Is auth.uid() non-null for this request? Check the client and session first.
Are you calling .select() after the insert, or uploading to Storage? Then you need a SELECT policy too.
Is it an UPDATE changing a column the policy depends on?
Does the policy query another RLS table? Move the lookup into a security definer function.
Does the message say "permission denied"? That's a GRANT, not RLS.

I build Supabase and AI products end to end, and RLS for multi-tenant apps is a recurring part of that. If you'd rather have someone get it right the first time, here's how I work.

FAQ

What does "new row violates row-level security policy" mean in Supabase?

It is Postgres error 42501, returned by Supabase as HTTP 403. Row Level Security is enabled on the table and the row you are writing did not pass any policy's WITH CHECK expression for that operation. Because RLS is default-deny per command, the most common reason is simply that the table has no INSERT (or UPDATE) policy for the role making the request.

How do I fix new row violates row-level security policy on insert?

Add an INSERT policy for the authenticated role with a WITH CHECK clause, for example: create policy "insert own rows" on public.notes for insert to authenticated with check ((select auth.uid()) = user_id). Then make sure the row actually carries the signed-in user's id, ideally with a column default of auth.uid(), and that the request is made with the user's session rather than only the anon key.

Why do I get the RLS error when I call insert().select()?

insert().select() runs INSERT ... RETURNING, and returning the row requires that the caller can also SELECT it. If the table has an INSERT policy but no SELECT policy that covers the new row, the whole statement fails with the same RLS error. Add a matching SELECT policy or drop the .select().

Should I use the service_role key to get around RLS errors?

Only on the server, and only for code that legitimately acts across users, such as webhooks or background workers. The service_role key bypasses RLS entirely, so it must never reach the browser. Using it to silence an RLS error in user-facing code removes your data isolation instead of fixing the policy.

Is "permission denied for table" the same as the RLS error?

No. Both use SQLSTATE 42501, but "permission denied for table" (or "for column") comes from missing GRANT privileges, which Postgres checks before RLS. "new row violates row-level security policy" means the grant was fine and a policy rejected the row. Fix the first with GRANT, the second with a policy.

Originally published on joancomadran.dev. I'm Joan, an AI engineer in Barcelona — work with me.

Shipping shareable poll results with Next.js ImageResponse

Joan Comadran — Wed, 14 Oct 2026 13:42:41 +0000

I've been building pollitics.es: a Spanish citizen thermometer for vote intention, wellbeing, and political mapping. The product lives or dies on whether people actually spread the aggregate. Screenshots of a responsive layout crop wrong, leak UI chrome, and — worse — sometimes include someone's personal ballot if they voted before sharing. So last week I shipped a dedicated shareable results image: one PNG, same for everyone, generated with next/og, handed to the native share sheet on mobile.

This is the version that survived the quirks. Not the happy-path demo.

Why a route beats "just screenshot it"

Open Graph meta tags (og:image) are for link previews when someone pastes a URL. That is not the same product as "tap Share and attach a chart to WhatsApp / Instagram Stories / X". Meta cards are landscape-ish, often cached for days, and you don't control the crop once the client app decides to be clever. Instagram and WhatsApp Stories want a tall frame. Voters want a button that feels like sharing a result, not sharing a browser tab.

So the shape is two pieces:

A GET route that returns a PNG built with ImageResponse from next/og.
A client button that fetches that PNG as a File, then either navigator.share({ files }) or falls back to a download.

The URL on pollitics is /intencion-de-voto/imagen. Revalidate every 15 minutes — same cadence as the public results ISR — so the image and the page don't disagree for long.

The image: public aggregate only

The hard product rule: the image never carries the viewer's vote. It is the latest public snapshot, identical for every downloader. No "you voted X" badge, no personalised colour flash, no N in the corner that would let someone reverse-engineer a tiny sample. We even strip the "Basado en N respuestas" line and the snapshot date from the PNG (decided 2026-10-04) so a viral share doesn't become a forensic artefact.

Dimensions are 1080 × 1350 — the vertical that Instagram, X, and WhatsApp leave alone without cropping the bars. Monochrome chrome, party colours only on the bars, Inter subset for Latin glyphs. If there aren't enough votes yet, or Spain's electoral blackout is on, the route still returns an image: it just shows a freeze message instead of percentages. Diffusing polls during the LOREG blackout is illegal; the share UI is hidden on the page in that window, and the image route refuses to paint numbers even if someone hits the URL directly.

Rough shape of the route:

// app/intencion-de-voto/imagen/route.tsx
import { ImageResponse } from "next/og";
import { readFile } from "node:fs/promises";
import { join } from "node:path";

export const revalidate = 900;

const WIDTH = 1080;
const HEIGHT = 1350;

export async function GET() {
  const results = await getPublicResults(/* supabase public client */);
  const blackout = results?.blackoutActive;
  const ready = /* snapshot exists && votesToPublish(results) === 0 */;

  return new ImageResponse(
    (
      <div
        style={{
          width: "100%",
          height: "100%",
          display: "flex",
          flexDirection: "column",
          justifyContent: "space-between",
          background: "#ffffff",
          padding: 72,
          fontFamily: "Inter",
        }}
      >
        <div style={{ display: "flex", flexDirection: "column" }}>
          <div style={{ fontSize: 28, color: "#595959" }}>
            Intención de voto · Elecciones generales
          </div>
          <div style={{ fontSize: 64, lineHeight: 1.08, marginTop: 16 }}>
            Si mañana hubiera elecciones
          </div>
        </div>

        {ready && !blackout ? (
          /* bar rows from snapshot.decided — acronym, colour, pct */
          <Bars rows={toRows(results.snapshot.decided)} />
        ) : (
          <div style={{ display: "flex", fontSize: 44, lineHeight: 1.2 }}>
            {blackout
              ? "Periodo electoral: resultados congelados."
              : "Todavía no hay votos suficientes para publicar resultados."}
          </div>
        )}

        <div
          style={{
            display: "flex",
            justifyContent: "space-between",
            fontSize: 30,
            borderTop: "2px solid #000",
            paddingTop: 24,
          }}
        >
          <span>¿Y tú qué votarías?</span>
          <span>pollitics.es</span>
        </div>
      </div>
    ),
    {
      width: WIDTH,
      height: HEIGHT,
      fonts: [
        {
          name: "Inter",
          data: await readFile(join(process.cwd(), "assets/fonts/Inter-Regular.ttf")),
          weight: 400,
        },
      ],
    },
  );
}

Two details that matter in production:

Load the font from disk, not from a CDN fetch inside the handler. Cold starts and font CDNs love to race each other; bundling Inter under assets/fonts made the route boringly reliable.
Cap the rows. Spanish ballots are long. We show at most 12 bars and fold the rest into "Otros", otherwise the type collapses and Stories crop the bottom parties.

The button: Safari will punish you

navigator.share({ files: [png] }) is the right API on mobile. Desktop browsers often don't support file shares, so you need a download path. The nasty part is Safari's user-gesture requirement: if you await fetch(image) inside the click handler before calling share(), Safari decides the gesture expired and throws NotAllowedError.

The fix is to start the fetch on pointerdown / focus, stash the Promise<File>, and resolve it on click:

"use client";

const IMAGE_URL = "/intencion-de-voto/imagen";

export function ShareImage() {
  const pending = useRef<Promise<File> | null>(null);
  const fileName = `pollitics-intencion-de-voto-${new Date()
    .toISOString()
    .slice(0, 10)}.png`;

  function prepare() {
    pending.current ??= fetch(IMAGE_URL)
      .then(async (res) => {
        if (!res.ok) throw new Error(String(res.status));
        return new File([await res.blob()], fileName, { type: "image/png" });
      })
      .catch((e) => {
        pending.current = null;
        throw e;
      });
    return pending.current;
  }

  function download(file: File) {
    const url = URL.createObjectURL(file);
    Object.assign(document.createElement("a"), {
      href: url,
      download: fileName,
    }).click();
    URL.revokeObjectURL(url);
  }

  async function share() {
    let file: File | null = null;
    try {
      file = await prepare();
      if (!navigator.canShare?.({ files: [file] })) return download(file);
      await navigator.share({
        files: [file],
        text: "Intención de voto en pollitics.es. ¿Y tú qué votarías?",
      });
    } catch (e) {
      const name = e instanceof DOMException ? e.name : "";
      if (name === "NotAllowedError" && file) download(file);
      // AbortError = user cancelled the sheet. Leave it alone.
    }
  }

  return (
    <button
      type="button"
      onPointerDown={() => prepare().catch(() => {})}
      onFocus={() => prepare().catch(() => {})}
      onClick={share}
    >
      Compartir imagen
    </button>
  );
}

canShare({ files }) is the gate. Don't call share with files if it returns false — some browsers claim navigator.share exists but reject file payloads. And always treat AbortError as success-shaped: the user closed the sheet on purpose.

On the page, the component is gated with {!results.blackoutActive && }. Legal constraint first, UX second.

Don't publish noise: the 50-vote floor

The first version of pollitics showed percentages from vote one. That looked clever in staging and looked broken in production: a 100% bar for whoever voted first is not a result, it's a bug wearing a chart. On 2026-10-06 we raised the public floor to 50 votes in the rolling 90-day count (MIN_PUBLIC_SAMPLE). Below that, the UI says how many votes are still missing; the image route shows the same "not enough yet" copy instead of bars.

export const MIN_PUBLIC_SAMPLE = 50;

export function votesToPublish(results: PublicResults | null) {
  return Math.max(
    0,
    MIN_PUBLIC_SAMPLE - (results?.snapshot?.meta.sample_total ?? 0),
  );
}

After 50, we still label anything under 1.000 as "Datos preliminares". We never invent a margin of error — this is open participation, not a representative poll, and the image footer says so in plain Spanish.

What I'd steal for any product, not just polls

If you're shipping a shareable artefact from a Next.js app, the checklist that actually moved the needle for me:

Concern	Choice	Why
Render	`ImageResponse` / `next/og`	Same deploy as the app; no Puppeteer farm
Size	1080×1350 (or your Stories frame)	Platforms stop fighting you
Cache	`revalidate` aligned with page ISR	Image and page stay honest together
Privacy	One public payload, zero personalisation	Screenshots of authenticated UI will betray you
Mobile share	Prefetch file on pointerdown, then `canShare`	Safari's gesture clock is not optional
Fallback	Object-URL download	Desktop and stubborn WebViews
Legal / policy	Hide the button and blank the numbers	Deep links exist

The whole feature is maybe two hundred lines. The product decisions around it — blackout, minimum sample, never stamp N on the PNG — took longer than the code, which is usually the tell that you built the right thing.

If you want the live version, vote (or just look) on pollitics.es/intencion-de-voto once the sample clears fifty. The share button is under the results. Your vote stays off the image. That was the entire point. And if you're about to ship something similar, the security pass I did before launch covers the rest of the site.

Originally published on joancomadran.dev. I'm Joan, an AI engineer in Barcelona — work with me.

A pre-launch security checklist for Next.js + Supabase (from a real launch)

Joan Comadran — Wed, 14 Oct 2026 13:41:39 +0000

Before opening pollitics.es, my Spanish vote-intention thermometer, to the public, it had to go from "works on my machine" to "strangers will poke at this". Political polls attract exactly the kind of visitor you don't want: people who'd love to stuff the ballot, scrape someone's vote, or embed your results page somewhere it doesn't belong. So before the public launch I did one boring, very large commit called pre-launch security enhancements. A 461-line migration, a 537-line SQL test file, security headers and a handful of small fixes.

None of it is clever, and that's sort of the point. Here's the checklist, with the code, in the order I'd do it again.

1. Close Supabase's default grants

This is the one that surprised me most, so it goes first. Out of the box, Supabase grants privileges on everything in the public schema to anon and authenticated. RLS is what usually saves you, but "a new table is reachable unless I remember to protect it" is a bad default for a project where the next migration will be written at midnight.

So I flipped it. Anything the migration role (postgres) creates from now on starts with zero client access:

alter default privileges for role postgres in schema public
  revoke all on tables from anon, authenticated;
alter default privileges for role postgres in schema public
  revoke all on sequences from anon, authenticated;
alter default privileges for role postgres in schema public
  revoke all on functions from anon, authenticated;

-- EXECUTE to PUBLIC is a global Postgres default: it can only be
-- revoked without a schema (this also covers the private schema).
alter default privileges for role postgres
  revoke execute on functions from public;

-- Existing identity sequences: clients never insert, they don't need them.
revoke all on all sequences in schema public from anon, authenticated;

Two gotchas. Default privileges only apply to objects created afterwards, so existing explicit grants stay exactly as they were (which is what you want, and what the tests check). And a function used inside an RLS policy now needs its own grant execute, otherwise the policy fails for that role instead of quietly passing.

2. RLS policies that call one function, once

The product rule on pollitics is that only people who have voted see the full evolution of the results. Everyone else, anonymous visitors included, sees just the latest published snapshots. On top of that there's Spanish electoral law: during the pre-election blackout nobody can see new polls, so nothing published from the blackout's start date onwards is readable.

That rule touches eight aggregate tables. Instead of copy-pasting the logic into eight policies, there's one security definer function that returns the readable time range for whoever is asking:

create or replace function public.readable_snapshots()
returns tstzrange
language plpgsql
stable
security definer
set search_path = ''
as $$
declare
  v_until timestamptz;   -- exclusive upper bound; null = no limit
  v_from  timestamptz;
begin
  if public.electoral_blackout_active(now()) then
    select (s.value ->> 'from')::timestamptz into v_until
    from public.app_settings s
    where s.key = 'electoral_blackout';
  end if;

  if public.has_voted() then
    return pg_catalog.tstzrange(null, v_until, '[)');
  end if;

  -- Non-voters: only the last two publishable snapshots.
  select min(l.snapshot_at) into v_from
  from (
    select m.snapshot_at
    from public.snapshot_meta m
    where v_until is null or m.snapshot_at < v_until
    order by m.snapshot_at desc
    limit 2
  ) l;

  if v_from is null then
    return 'empty'::tstzrange;
  end if;
  return pg_catalog.tstzrange(v_from, v_until, '[)');
end;
$$;

And every policy is a one-liner:

alter policy "results_snapshots_read" on public.results_snapshots
  using (snapshot_at <@ (select public.readable_snapshots()));

The details that matter:

Wrap the call in (select ...). Postgres then evaluates it once per query as a scalar subquery instead of once per row. Same result, very different bill on a big table.
security definer plus set search_path = ''. The function reads snapshot_meta, which has its own policy that calls the same function. Running as the owner avoids that recursion, and the empty search path (with fully qualified names) stops anyone from shadowing public.has_voted with their own object.
Why two snapshots and not one. Some pages read the latest snapshot_at in one query (or from a 15-minute cache) and the rows in another. If the cron job writes a new snapshot in between, a "last one only" rule would make the page go blank. The second-to-last snapshot is the margin.

3. A CSP that doesn't kill ISR

The textbook answer is a nonce-based Content Security Policy. The catch in Next.js is that nonces are per request, so they force every page to render dynamically. The pollitics home page is ISR, and I'd rather keep it served from cache. So the CSP has no nonces and accepts 'unsafe-inline' for scripts, and everything else is locked down hard:

// next.config.ts
const supabase = process.env.NEXT_PUBLIC_SUPABASE_URL ?? "";
const turnstile = "https://challenges.cloudflare.com";
const isDev = process.env.NODE_ENV === "development";
const vercelLive = process.env.VERCEL_ENV === "preview" ? " https://vercel.live" : "";

const csp = [
  "default-src 'self'",
  `script-src 'self' 'unsafe-inline'${isDev ? " 'unsafe-eval'" : ""} ${turnstile}${vercelLive}`,
  "style-src 'self' 'unsafe-inline'",
  "img-src 'self' blob: data:",
  "font-src 'self'",
  `connect-src 'self' ${supabase}${vercelLive}`,
  `frame-src ${turnstile}${vercelLive}`,
  "object-src 'none'",
  "base-uri 'self'",
  "form-action 'self'",
  "frame-ancestors 'none'",
  ...(isDev ? [] : ["upgrade-insecure-requests"]),
].join("; ");

const securityHeaders = [
  { key: "Content-Security-Policy", value: csp },
  { key: "X-Frame-Options", value: "DENY" },
  { key: "X-Content-Type-Options", value: "nosniff" },
  { key: "Referrer-Policy", value: "strict-origin-when-cross-origin" },
  { key: "Permissions-Policy", value: "camera=(), microphone=(), geolocation=(), browsing-topics=()" },
];

const nextConfig = {
  poweredByHeader: false,
  async headers() {
    return [{ source: "/:path*", headers: securityHeaders }];
  },
};

A few notes from getting it to actually work:

The only external origins are Supabase (auth and RPC calls from the browser) and Cloudflare Turnstile (script plus iframe for the captcha). If you can't list your third parties on one hand, the CSP will tell you.
Vercel's preview comment toolbar needs vercel.live, so it's allowed only when VERCEL_ENV is preview.
frame-ancestors 'none' and X-Frame-Options: DENY say the same thing for new and old browsers: nobody gets to frame the voting page inside something that looks official.
The CSP is built at build time from NEXT_PUBLIC_SUPABASE_URL. Change the Supabase URL and you have to redeploy. I wrote that in the README because future me will forget.
No HSTS header in the config, because Vercel already sends it on every HTTPS domain.

4. An open-redirect-proof `?next=`

Login flows love ?next=/somewhere. They also love becoming open redirects: ?next=//evil.com is the classic, but the fun ones abuse the fact that browsers strip tabs and newlines and treat \ like /. So /\t/evil.com can end up on evil.com. The fix is small and paranoid:

const BASE = "https://pollitics.invalid";

export function safeNext(next: string | string[] | undefined, fallback = "/intencion-de-voto#votar") {
  const value = Array.isArray(next) ? next[0] : next;
  if (!value || !value.startsWith("/") || /[\u0000-\u001f\u007f\\]/.test(value)) return fallback;
  try {
    const url = new URL(value, BASE);
    if (url.origin !== BASE) return fallback;
    return url.pathname + url.search + url.hash;
  } catch {
    return fallback;
  }
}

Reject control characters and backslashes outright, then let the URL parser have the last word: resolve against a fake origin and make sure the origin didn't move. Use .invalid as the TLD so the base can never be a real site.

5. GDPR export and delete that go through the same doors

If you collect political opinions in the EU, "email us to delete your data" doesn't cut it. Both rights are self-service now.

Export (GDPR article 20, portability) is a plain route handler, /cuenta/exportar. It reads the user's data through the same get_my_* RPC functions the account page uses, so it can't see anything the user couldn't already see, and it returns a JSON attachment with Cache-Control: private, no-store so no CDN ever keeps a copy.

Delete is a Supabase Edge Function. Deleting the auth.users row cascades through an identity map and a trigger that removes the respondent, their vote and its history. One detail worth stealing: with Supabase's new API keys, the keys aren't JWTs, so the function runs with verify_jwt = false and validates the user's token itself:

Deno.serve(async (req) => {
  if (req.method !== "POST") return json({ error: "method_not_allowed" }, 405);

  const jwt = req.headers.get("Authorization")?.replace(/^Bearer\s+/i, "");
  if (!jwt) return json({ error: "not_authenticated" }, 401);

  const { data, error } = await admin.auth.getUser(jwt);
  if (error || !data.user) return json({ error: "not_authenticated" }, 401);

  const { error: deleteError } = await admin.auth.admin.deleteUser(data.user.id);
  if (deleteError) return json({ error: "delete_failed" }, 500);

  return json({ ok: true }, 200);
});

The function deletes whoever owns the token, and only them. There's no user id in the request body to tamper with.

6. Alert when the cron job quietly stops

Not exactly security, but the failure mode is the same: something breaks and nobody notices. Public results come from a pg_cron job that writes a snapshot every 15 minutes. If it stops, the site keeps serving old numbers with a straight face.

The existing anomaly check (vote spikes per party, signup spikes) got one more rule: if the latest snapshot is more than an hour old and the electoral blackout wasn't active in that window (during the blackout, not writing is the whole point), insert a stale_snapshot alert. Alerts go out by email through Resend, called from Postgres with pg_net, with the API key read from Supabase Vault. One alert per episode, so a dead job doesn't turn into an inbox flood.

7. Test it all in a transaction that always rolls back

This is the part that made the rest safe to ship. A small Node script opens one connection to the remote project, runs begin, applies any pending migrations (the ones not yet in supabase_migrations.schema_migrations), runs every file in supabase/tests/, and always ends with rollback:

try {
  await client.query("begin");
  for (const f of files) {
    console.log(`▸ ${f.name}`);
    await client.query(f.sql);
  }
} catch (e) {
  failed = true;
  console.error(`✗ ${e.message}`);
} finally {
  await client.query("rollback").catch(() => {});
  await client.end();
}
process.exit(failed ? 1 : 0);

Tests are plain SQL that raise exception on failure. The default-privileges test is my favourite because it checks the thing I actually care about, the next table, not the current ones:

create table public.t_prelaunch_new (id bigint generated always as identity primary key);
create function public.f_prelaunch_new() returns integer language sql as 'select 1';

do $$
begin
  if has_table_privilege('anon', 'public.t_prelaunch_new', 'select')
  or has_table_privilege('authenticated', 'public.t_prelaunch_new', 'insert')
  or has_sequence_privilege('anon', 'public.t_prelaunch_new_id_seq', 'usage')
  or has_function_privilege('anon', 'public.f_prelaunch_new()', 'execute') then
    raise exception 'FAIL: a new object is exposed to clients by default';
  end if;
  if not has_table_privilege('service_role', 'public.t_prelaunch_new', 'select') then
    raise exception 'FAIL: service_role lost its default access';
  end if;
end $$;

The same file seeds 400 random respondents with a fixed seed (setseed(0.42)) and checks that the refactored snapshot function produces exactly the same aggregates as the original queries, table by table. That refactor computed each eligible population once into temp tables instead of up to three times per run, which is a performance change I'd never have dared to ship without a row-for-row diff.

The checklist, short version

Area	What I did	Why
Default grants	Revoke default privileges for `anon` / `authenticated`, revoke `EXECUTE` from `PUBLIC`	The next table is safe even if I forget
RLS	One `security definer` function, called as `(select fn())` in each policy	One rule, evaluated once per query
Headers	CSP without nonces, frame-ancestors none, nosniff, strict referrer, no `x-powered-by`	Keeps ISR, still locks down third parties
Redirects	`safeNext()` with a control-char check and an origin check	`?next=` is an open redirect by default
Privacy	Self-service JSON export and an Edge Function delete keyed on the caller's token	GDPR, without a support inbox
Ops	Stale-snapshot alert via `pg_net` + Vault	Silent failures are the worst kind
Tests	Migrations + SQL tests in one transaction, always rolled back	Validate against the real project without touching it

Seven items, one commit, zero clever tricks. If you're about to launch something on Next.js and Supabase, number 1 alone is worth the ten minutes. If you want someone to do this kind of pass on your product, that's the kind of work I take on. And if you want to see the result, go and vote on pollitics; the shareable results image still won't show anyone what you picked.

FAQ

Does Supabase expose new tables to anon and authenticated by default?

Yes. Supabase grants privileges on objects in the public schema to the anon and authenticated roles by default, so a new table, sequence or function is reachable through the API unless RLS or a revoke stops it. On pollitics.es I removed that default with ALTER DEFAULT PRIVILEGES for the postgres role (tables, sequences and functions), plus a global revoke of EXECUTE on functions from PUBLIC, so every new object needs an explicit grant.

Can I use a strict nonce-based CSP with Next.js ISR?

Not without giving up static rendering. Nonces have to be generated per request, which makes every page dynamic and breaks ISR. On pollitics.es I kept ISR and shipped a CSP without nonces: 'unsafe-inline' for scripts (Next needs it), and an explicit allowlist for Supabase and Cloudflare Turnstile, plus frame-ancestors 'none', object-src 'none', base-uri and form-action locked to 'self'.

How do I prevent open redirects with a ?next= parameter in Next.js?

Only accept values that start with a single slash, reject any control character or backslash (browsers strip tabs and newlines and treat a backslash as a slash, so '/\t/evil.com' can end up on evil.com), then resolve the value against a fixed fake origin with new URL() and check the origin didn't change. Return pathname, search and hash, or a safe fallback.

How do I test Supabase migrations without touching the database?

Run the pending migrations and your SQL test files inside a single transaction that always ends in ROLLBACK. Each test raises an exception on failure, so the script exits non-zero and nothing persists either way. On pollitics.es a small Node script with the pg client does this against the remote project.

Originally published on joancomadran.dev. I'm Joan, an AI engineer in Barcelona — work with me.